[FEATURE] hierarchy based on component type_name instead of nodes

[jeras]

The current hierarchy based on nodes is lacking usability for generators, which generate a type_name definition only once, and create multiple instances of it. And this is most generators I wrote till now. For example generators for VHDL, C structures, documentation. In my code I wrote extra code to create a list of all type_name-s used inside a node, and for each of the type_name-s a list of all instances inside a node. This code could be integrated into the SystemRDL-compiler, since it is part of most generators I wrote.

Here I will use the work component, although I am not sure the SystemRDL-compiler distinction between component and node is exactly what I am looking for. So I use component for a definition with multiple instances or nodes.

So a component based hierarchy (parent/child) would look something like this:

- addrmap component EXAMPLE
  - properties
  - list of all children nodes inside the component EXAMPLE
  - list of all children components instantiated inside EXAMPLE (this is where the hierarchy of components expands to children).
  - list of all instances (nodes) of component EXAMPLE inside its parent

Here are the problems I experienced while attempting to create this hierarchy for a jinja2 based Markdown documentation generator.

1. Components do not have properties as nodes do, so they can either be taken from the first node in the list of instances, or copied. Neither solution seems great, using the first instance node seems arbitrary, and making a copy seems redundant.
2. If each node is also a full hierarchy, than this entire structure becomes very big and difficult to visualize (print). Having shallow nodes would solve this problem, but those would not be the same nodes as in the current implementation.

I only created this structure for jinja2 based exporter, here is the code (based on PeakRDL-html, WARNING: beta code):

https://github.com/jeras/PeakRDL-html/blob/devel/src/peakrdl_markup/exporter.py#L201-L258

---

As a related issue. If the SystemRDL-compiler could create a default context for jinja2 based generators, this would enable the creation of generators based just on jinja2 templates. Something like PeakRDL-jinja could take a template as the input and create a proper exporter.

As en example, a custom documentation generator could be a user, by just modifying a jinja2 template. It could be something something trivial, like adding section numbering (not really trivial), or replacing some text like "Base address" with "Absolute address". Or the template could generate custom output for a specific type_name, for example Reg containing VHDL fixed point number types.

PROS:

• shared context for multiple templates,
• instead of writing a separate exporter in Python and a jinja2 template, it would be enough to just write a template.

CONS:

• Adding complex code to a jinja template is more difficult (and not recomended) compared to writing them in Python. But this might not be necessary for most templates.
• Debugging jinja2 templates is difficult.

I did not investigate this yet, but it might be possible to make the entire SystemRDL compiler module available inside a jinja2 template, so there would be no need to create a dedicated context for jinja, instead the existing node/component hierarchy could be used directly inside a template. The problem is, such a solution would be rather verbose.

[jeras]

As an experiment, to see whether the native node structure of SystemRDL compiler could be used natively with jinja2, I wrote a template and some code to pass the the systemrdl module and the top node as context.

The template is here:

https://github.com/jeras/PeakRDL-html/blob/devel_jinja_with_SystemRDL/src/peakrdl_markup/templates/markup-absolute-systemrdl.md.jinja

The code to pass the top node as context and the systemrdl module (also the isinstance and a couple debug functions):

https://github.com/jeras/PeakRDL-html/blob/devel_jinja_with_SystemRDL/src/peakrdl_markup/exporter.py#L144-L150

To reproduce the results do:

git clone -b devel_jinja_with_SystemRDL https://github.com/jeras/PeakRDL-html.git
cd PeakRDL-html
peakrdl markup example/example32.rdl -o output_file.md

The generated Markdown file is output_file.md/test.md.

The code need a lot of cleanup, but as mentioned it is just an experiment to see if Exporters could be written entirely as a Jinja2 template.

[amykyta3]

This feature already exists. Please see: https://systemrdl-compiler.readthedocs.io/en/stable/api/node.html#systemrdl.node.Node.get_global_type_name Note that the output may still change slightly depending on the outcome of #198

…

On Wed, Feb 19, 2025 at 8:05 AM Iztok Jeras ***@***.***> wrote: As an experiment, to see whether the native node structure of SystemRDL compiler could be used natively with jinja2, I wrote a template and some code to pass the the systemrdl module and the top node as context. The template is here: https://github.com/jeras/PeakRDL-html/blob/devel_jinja_with_SystemRDL/src/peakrdl_markup/templates/markup-absolute-systemrdl.md.jinja The code to pass the top node as context and the systemrdl module (also the isinstance and a couple debug functions): https://github.com/jeras/PeakRDL-html/blob/devel_jinja_with_SystemRDL/src/peakrdl_markup/exporter.py#L144-L150 To reproduce the results do: git clone -b devel_jinja_with_SystemRDL https://github.com/jeras/PeakRDL-html.git cd PeakRDL-html peakrdl markup example/example32.rdl -o output_file.md The generated Markdown file is output_file.md/test.md. The code need a lot of cleanup, but as mentioned it is just an experiment to see if Exporters could be written entirely as a Jinja2 template. — Reply to this email directly, view it on GitHub <#252 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AC3W6IYDDJC7RPNB6N5SU432QSTTFAVCNFSM6AAAAABXOD74QKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMNRZGA4DSNZVHA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***> [image: jeras]*jeras* left a comment (SystemRDL/systemrdl-compiler#252) <#252 (comment)> As an experiment, to see whether the native node structure of SystemRDL compiler could be used natively with jinja2, I wrote a template and some code to pass the the systemrdl module and the top node as context. The template is here: https://github.com/jeras/PeakRDL-html/blob/devel_jinja_with_SystemRDL/src/peakrdl_markup/templates/markup-absolute-systemrdl.md.jinja The code to pass the top node as context and the systemrdl module (also the isinstance and a couple debug functions): https://github.com/jeras/PeakRDL-html/blob/devel_jinja_with_SystemRDL/src/peakrdl_markup/exporter.py#L144-L150 To reproduce the results do: git clone -b devel_jinja_with_SystemRDL https://github.com/jeras/PeakRDL-html.git cd PeakRDL-html peakrdl markup example/example32.rdl -o output_file.md The generated Markdown file is output_file.md/test.md. The code need a lot of cleanup, but as mentioned it is just an experiment to see if Exporters could be written entirely as a Jinja2 template. — Reply to this email directly, view it on GitHub <#252 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AC3W6IYDDJC7RPNB6N5SU432QSTTFAVCNFSM6AAAAABXOD74QKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMNRZGA4DSNZVHA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[jeras]

For now I feel like we are talking about different things. I will do some more experimentation, and later post an updated question.