Should you always keep hierarchical structure when generating code from SystemRDL?

[RasmusGOlsen]

What are people's thoughts on hierarchical design structure and code generation?

When I read the SystemRDL specification, I understood that there are two hierarchical components, the addrmap and the regfile. Furthermore, I can specify arrays of instances such as addrmap, regfile and reg. I would prefer to keep the specified hierarchy in the generated code. But does this always make sense? Are there some contexts where unrolling or flattening the design is intuitive?

Consider you want to generate code from this small example in the following contexts. How would you translate the hierarchical structure specified?

• Verilog/VHDL RTL
• UVM RAL
• JSON
• HTML
• C headers

addrmap example {
    reg {
        field {} A[8];
    } A;

    reg {
        field {} B;
    } B[8];

    regfile {
        reg {
            field {} C[8];
        } C;
    } C;

    regfile {
        reg {
            field {} D[8];
        } D;
    } D[2];
};

[amykyta3]

My approach has always been to preserve hierarchy as much as possible. The hierarchical structure ends up being useful for many consumers of the output, so its nice to avoid flattening at all costs.
Preserving hierarchy is most useful if you use arrays of RDL components. This lets you write repeated structures using generate loops in RTL, write more modular software in C/C++, and also implement re-usable blocks in your UVM testbench.

If I absolutely have to flatten something, I'll still try to preserve the hierarchical name, so I'll usually do this trick:

child_identifier = child_node.get_rel_path(top_node, hier_separator="__", array_suffix="_{index:d}")

This would result in the hierarchy for field D in your example to flatten to these identifiers:

D_0__D__D
D_1__D__D

Kinda ugly, but it helps avoid name collisions.

RTL

SystemVerilog introduces the concept of structs which are extraordinarily useful for stuff like this. You can nest structs and arrays of structs arbitrarily to create a signal hierarchy that exactly matches your RDL. This is not possible with Verilog-2005 or older, so you'd be forced to flatten hierarchy.
You should be able to do something similar with VHDL records.

UVM RAL

Definitely preserve hierarchy here. Not sure why you'd flatten.
See how I do this in the PeakRDL-uvm tool.
I take it a step further and make a best-effort attempt to re-use classes based on RDL type definitions as well. Although the type definition names have their namespace'd identifiers flattened, the resulting RAL structure retains the RDL hierarchy exactly.

Documentation

HTML is totally open-ended, so its pretty intuitive to keep the hierarchy. See: https://systemrdl.github.io/PeakRDL-html/

I considered making a PDF generator, but that actually has the opposite problem - you're attempting to render a hierarchical data structure onto a natively flat medium. @muneebullashariff made a really spiffy PDF generator here https://github.com/muneebullashariff/PeakRDL-pdf. This works great for small RDL definitions, but I imagine the generated output gets cumbersome if you have too many layers of hierarchy.

C/C++ headers

If you're emitting #define macros, then yeah, you're basically forced to flatten hierarchy.

The alternative is to avoid the defines entirely and have a C/C++ header generator create a nested struct typedef.
This can be cast as a volatile pointer to your hardware address space, where you can access everything by-name which is super convenient. You can take this approach all the way down to bitfield structs if you wish, however be aware of the performance implications.
Since this method relies on you getting the struct packing exactly right, you need to be careful about the following situations:

• Need to account for padding bytes for reserved space between RDL components.
• Be careful about how the C compiler handles struct packing, especially if your regwidth is smaller than the native processor word width. The compiler may insist on adding implicit padding. RDL lets you do some nasty things with addressing if you try hard enough. For this reason, I prefer to enable the optional STRICT_SELF_ALIGN error/warning.
• Beware of edge cases in RDL such as overlapping registers. For example a read and write register/field that share the same location: https://github.com/SystemRDL/systemrdl-compiler/blob/master/examples/atxmega_spi.rdl#L59-L67. You might be able to work around with a C union, but that starts getting messy real fast.

[RasmusGOlsen]

From your response, I can see that I'm pretty much aligned with your view on this topic. I can see that in the UVM RAL model you treat both addrmap and regfile as register blocks, which makes sense, maybe it is only in the RTL generation you actually want to distinguish between addrmap and regfile.

[krcb197]

The specification does give some hints, notably with regard to Address Maps:

An address component map (addrmap) contains registers, register files, memories, and/or other address
maps and assigns a virtual address or final addresses; this map defines the boundaries of an implementation
(e.g., RTL).

I would interrupt that as separate modules/files for different address maps at the least.

Registers and Fields in my opinion have to be preserved in the generated outputs as the hardware structure often needs to be understood by the users of these structures.

I think the area which is open to debate is Register Files, which could in theory by ignored. These are often just used as structures and implementation for the system RDL code but may not be relevant to other domains.

On balance, I think it is useful if all the derivate code structures follow the same hierarchy, otherwise can just make these confusing between different parts of the engineering community.

The one issue, that may cause me to contemplate not reflecting the hierarchy, is any output forms that don't support hierarchy, notably a #define C header. In order to create unique names, one strategy is to concatenate the hierarchy node names into a giant string separated by underscores, which can reduce the readability of code or cause problems if maximum variable name lengths are enforced. In this case, preserving the hierarchy may be difficult. I think this is best handled by persuading the author of the systemRDL to be less verbose in their choice of names.

[amykyta3]

Oh and for JSON, see my tutorial here for one of many possible solutions: https://systemrdl-compiler.readthedocs.io/en/latest/examples/json_exporter.html