[PATCH] eng: Add register block specification types

[Sebastian Huber]

On 16/09/2021 01:47, Chris Johns wrote:
> On 15/9/21 3:33 pm, Sebastian Huber wrote:
>> On 15/09/2021 00:48, Chris Johns wrote:
>>> On 14/9/21 8:08 pm, Sebastian Huber wrote:
>>>> On 10/09/2021 16:41, Sebastian Huber wrote:
>>>>> A register block may be used to specify the memory-mapped interface to
>>>>> the hardware.  Register blocks consist of register block members.
>>>>> Register block members are either instances of registers or instances of
>>>>> other register blocks.  Registers consists of bit fields.
>>>>>
>>>>> Update #3715.
>>>>
>>>> Any objections to integrate this?
>>>
>>> I am sorry but in it's current form I do.
>>>
>>>> The hardware specification is work in
>>>> progress. What I have currently is a proof of concept for the GR740 and the
>>>> GR712RC. It should cause no harm to have it documented. If this stuff is
>>>> generally useful is an open question.
>>>
>>> Who fixes the spec for the other bus models?
>>
>> The register block specification doesn't need to be fixed.
> 
> I think it does. As I stated earlier showing how an indirect device can be
> handled would help.

For devices which are specified in an abstract address space, you could 
change the "register-block-type" from "memory" to "whatever". The code 
generator could then for example generate a set of defines with address 
space offset constants instead of a C structure.

> 
>> It is independent of
>> bus models, device driver frameworks, and programming languages.
> 
> If it can directly generate a struct to access the registers it is not
> independent by definition. You have assumed the implicit integration of the CPU
> and connecting buses which may be fine for a SOC or devices used only with one
> CPU and bus architecture but it is not generic. A device word size is a physical
> constraint of the device, the bus word size is another constraint and they may
> not directly align. For example an 8bit UART device connected to a 32bit bus may
> result in each register being 32bit aligned. Which offset is in the register
> definition?

I really don't see what is the problem here with the register block 
specification. The offsets are just numbers relative to a base address.

> 
>> The register
>> block specification contains the same information as a hardware manual in terms
>> of register blocks, registers, and bit fields. The only difference is that the
>> register block specification is machine readable and a hardware manual not
>> really in general.
> 
> I suggest you review ....
> 
> https://japan.xilinx.com/support/documentation/ip_documentation/axi_iic/v2_0/pg090-axi-iic.pdf
> 
> ... Register Space on page 11. You can enter the offsets but you have no idea
> how this IP presents to the CPU until you get the extra piece of information
> from the FPGA designer who placed it in the PL. The values in table 2-4 are
> address space offsets in the register space and nothing more. The choice of
> wording is deliberate and worth noting.

You could directly rewrite table 2-4 and the following register 
definitions in the register block specification.

> 
>>> Will those fixes be compatible and
>>> if not who fixes the existing specs or drivers?
>>
>> In order to support a particular device driver implementation framework you just
>> have to write a code generator which reads the register block specification and
>> outputs the code.
> 
> I understand this but the use of `bytes` in size and few other things means the
> spec language is too specific to the immediate purpose you have. It just needs
> to be broadened and it needs to discuss and deal with buses. In your case a 1:1
> mapping of device word size and bus word size.

Ok, so your real problem is that I wrote "bytes" in the description of 
the register-block-size and offset attributes? We could change this into 
something like this:

offset

The attribute value shall be an integer number. It shall be the offset 
in units of address space granules from the register
block begin to the register member.  For memory-mapped register blocks 
the address space granule is one byte.

register-block-size

The attribute value shall be an integer number. It shall be the size of 
the register block in units of address space granules.  For 
memory-mapped register blocks the address space granule is one byte.


> 
>> The existing code generator just outputs a header file with C
>> structures and defines for the bit fields. You could use this header file with
>> the FreeBSD bus space API.
> 
> Presenting the struct and defines in a single file and using the bus space API
> does not make sense to me and that should not be encouraged. I do understand a
> header with the address space offsets and bit maps and then a header with the
> struct for those bus archs that can support it but current versions of these
> types of headers I have used do not do this, ie zynq uart. Considering this now
> I think the separation is something we should mandate.

This is a problem related to the code generator and not the the register 
blocks specification. This patch set is about the register block 
specification.

> 
>>> Those questions expose the liability the project is left with. For me to make
>>> changes and look after the GR740 and GR712RC it would be a lot of work because I
>>> have not worked with those devices and they are important to some users.
>>
>> The existing GRLIB header files are incomplete. What we have now is a complete
>> set of register block header files for the GR740.
> 
> Will you test all these new definitions? If not how do you know which has been
> tested and can be trusted?

These are valid questions, however, they are not relevant to the 
register block specification of this patch set.

> 
>>> I do not see the value in us hosting a custom or subset solution for a model to
>>> access hardware we should not be encouraging.
>>
>> We don't have a general bus space API in RTEMS. Basically every BSP has its own
>> solution. No matter which model you have to access the hardware, you need
>> something which tells you how the hardware looks like. This could be a manual or
>> a machine readable description.
> 
> Agreed and this needs to be part of the specification process or the information
> being added is custom and useful only for a specific sub-set of parts. And if I
> wanted to use this for something that did not fit I may break the specs and then
> the generation tool and that is a liability I would prefer we avoid if we can.
> 
>>> I see value in a solution that can
>>> support all bus solutions.
>>
>> I don't know if the register block specification supports all bus solutions, but
>> it could support all I know currently. It is just a machine readable hardware
>> description.
> 
> I appreciate this. I am asking there be an addition of a bus and bus details. A
> bus for a struct that maps to a device means the device and bus words map 1:1. A
> device word needs to be defined as a number of bits. A struct mapped bus word
> size if the CPU machine word size. The generator should reference this data.

The register width is in bits:

width

The attribute value shall be an integer number. It shall be the width of 
the register in bits.

A specification of a bus would be done in a separate specification item. 
The proposed register block specification is general enough from my 
point of view (with the documentation change from "byte" to "address 
space granule").

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/