[PATCH] eng: Add register block specification types

[Chris Johns]

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.

> 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?

> 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.

>> 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.

> 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.

>> 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?

>> 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.

Chris