Duplication of the documentation for array element

[MarekPikula]

Follow up to issue #5:

A related issue here is the duplication of the documentation for each array element.
I think the structure of the documentation should be the same for all generators (HTML, PDF, Markdown), but I have to run a few examples before I can make a proposal.
This month I also discussed with Alex how parameterized definitions are used by generators, and this adds a few extra consideration on how to document everything and just once.

Originally posted by @jeras in #5 (comment)

Another option for the expected output would be to show the array explicitly instead of each individual element:

Offset	Identifier	Name
0x104	TEST_REGISTER[0:63]	Test Register description

Another problem is, that each element of the array has its own documentation section, with the heading lacking any index, just TEST_REGISTER.

There is also a conceptual problem. Since a full list of individual array elements adds clutter and causes scrolling fatigue, I would usually prefer a more compact approach, where arrays are represented with a range instead of individual elements, and for each array a single element is documented (if I have 8 identical SPI controllers, I do not need 8 copies of their full description).

On the other hand, if I am looking for the absolute address of a register, then a full listing would be appreciated.

One solution to this problem I see (which is also common in existing documentation), would be to have 2 generators:

• one for a flat table which includes all absolute addresses, but only short names as description,
• the other hierarchical (address offsets), with arrays defined only with a range, and not a list, containing full documentation strings, but only once for each array element.

Originally posted by @jeras in #5 (comment)

[bwhitchurch]

I had some ideas on this topic while working on the original issues, but I think they end up touching a lot of the code so better that this got separated.

For both table and detailed documentation I was considering a compressed vs full format that would be controlled with command line arguments, i.e. peakrdl markdown --table-format compressed --desc-format full. A full formatted description would mean enumerating all array elements (with possible change to add the index into the header name), while the compressed description would be one block that maybe also includes stride and array size.
This would be nice and flexible, but requires a bit of work to modify the generation process.

[saberxt]

Having same trouble when generating markdown document with array-like regs.

In 1.0.2, we noticed the identifiers of regs in the table of the regfile are distinguished by indexes, but they are still the same in the title of each section of reg.

[shotaminato]

I have the same problem. Is there any updates for this?

[jeras]

Hi @MarekPikula I finally did some research and wrote a proposal.

Ideas

I am planning to work on this problem, and a few other features:

• array unrolling to be made optional,
• linking between table element and its description section,
• support for Markdown, AsciiDoc, reStructuredText, by choosing a Jinja template,

Multiple instances and array instances

Inspiration

I tried to find some data sheets containing a register map to be used as inspiration. First I checked the CSR definition for RISC-V, but those are very specific, even containing features not present in the SystemRDL standard. The other two are my first tries and they look good. I was also thinking to look into some NPX ARM Microcontrollers.

1. Zynq UltraScale+ Devices Register Reference
2. RP2350 Datasheet chapter 2.2. Address Map

Xilinx

In the Xilinx document I noticed the following:

1. The following hierarchy is used:

   • x Top addrmap containing a table of regfile instances with links to sections x.y for each regfile component definition/description.
   • x.y For each regfile a table of reg instances with links to sections x.y.z for each reg component definition/description.
   • x.y.z For each reg a table of field instances, without links, the description is part of the table.

   This hierarchy avoids mixing different component types on the same hierarchical level,
   For example a addrmap or regfile containing a mix of both regfile and reg instances.
   This approach reduces the number of complex interactions within a documentation generator.

2. Arrays of regfile and reg instances are unrolled inside tables.
   There might be cases, where an array range is used [0:N-1], but I did not see any yet.
   The arrays were of length around 4, some of length 16.

3. There are two types of unrolling:

   1. In case the regfile and reg instances share the same definition/description section
      like ZDMA module
      are appended the n suffix (no separator, index) in tables.

      In this case, there is also a list of base address for all regfile instances,
      and a list of absolute address for the same reg in all regfile instances.

      https://docs.amd.com/r/en-US/ug1087-zynq-ultrascale-registers/ZDMA_ERR_CTRL-ZDMA-Register

   2. Some regfile arrays use the _n suffix (_ separator and index) and also link to separate definitions.
      For example CORESIGHT_A53_CTI_0/1/2/3.

      It seems the use of the suffix is not strict, since some registers have
      the suffix without the separator and separate definitions.

      https://docs.amd.com/r/en-US/ug1087-zynq-ultrascale-registers/CTIINEN0-A53_CTI_0-Register

   I did not check yet, whether the repeated definitions for apparently identical regfile/reg instances
   also have identical descriptions, but it appears they do.
   The base address for regfile and absolute address for reg are distinct as expected.

   There are also cases with indexes which are not arrays.
   Like control registers which do not fit into 32-bits and are therefore split into CTRL0, CTRL1.

   https://docs.amd.com/r/en-US/ug1087-zynq-ultrascale-registers/ZDMA_CH_CTRL0-ZDMA-Register

Raspberry PI

An example of multiple instances of the same regfile would be the 3 PIO instances
within the AHB `, see section 2.2.5. AHB Registers.
All three instances link to the same PIO documentation.

At the end of the PIO documentation there is section 11.7. List of Registers.
At the beginning of the section are again listed the base addresses for each PIO instance.
Curiously this part of the document was not updated to list 3 PIO compared to the old chip with just 2 PIO.

The documentation for individual registers does not list the absolute address for each PIO instance,
instead just a an offset is provided.

Proposed solutions

1. By default do not duplicate component description sections for multiple instances or arrays.
   This should be straight forward as long as the the instances are within the same parent.
   To avoid special accommodations for parameters, each parameterization shall have a separate section.
2. By default unroll all arrays up to a threshold (could be 4 or 8 by default provided from CLI).
3. Within the description for a duplicated component optionally provide base/absolute addresses
   for each instance array element. For arrays only up to the array unrolling threshold.
4. Provide user defined properties for duplication, unrolling, that can be applied to each instance separately.

Linking between table element and its description section

For example a link from the identifier of a register in a table
to the section fully documenting this register (similar for fields, ...).

Initially I thought this would be difficult, since Markdown links to headers
are constructed from the header text, and this would not work well if there are
multiple headers with the same text.
Than I noticed at least GitHub is appending an additional index (-n)
to the n-th heading with the same text.
So it would be extra work to track this index, but it is doable.

AsciiDoc provides the ID Attribute
which provides an unique path for links.

There might be something similar for reStructuredText, I did not check yet.

Support for multiple formatted text languages

The three document formats Markdown, AsciiDoc, reStructuredText all have a similar approach.
They are based on human readable text, and are often parsed/rendered
by version control web interfaces (GitHub, GitLab, ...).

Since all three have similar features, it would probably be possible to support
all three formats by the same Python jude, just by switching the Jinja template.

It wold probably make sense to find a new name for such a combined tool?

• PeakRDL-TextDoc,
• PeakRDL-DocText,
• PeakRDL-DocGen.

Implementation plan

1. example SystemRDL file showcasing desired features
3. add more Jinja2 templates
4. update documentation

[MarekPikula]

Hi @jeras, thank you for the write-up and sorry for a long delay.

Multiple instances and array instances

It would be great to create a minimal RDL example of this and put it to examples/minimal_example.rdl to have a good base for tests – that could be a valuable contribution on its own.

Linking between table element and its description section

In general, a good idea, but indeed tricky to implement because of how header links work in Markdown (as you pointed out).

Than I noticed at least GitHub is appending an additional index (-n)

I'd need to check what's the behaviour of m2r2 (for use with Sphinx). Of course, having a separate (proposed) RST exporter would be the proper solution, but overall I find it rather hacky either way, so it would need to be available as an opt-in flag.

Support for multiple formatted text languages

That would be great, and it was something I thought about in the beginning (especially that my main use case was importing it to Sphinx doc with m2r2), but I opted for a Markdown exporter for simplicity and due to existence of the py-markdown-table library. Either way, the proposed Jinja2-based approach would be nice, as it would make implementing additional backends (like RST, AsciiDoc) much easier, and would address #6. It would be a big refactor though, so I would keep it as a separate item.

To sum up, you're welcome to work on this issue, but I would appreciate small, self-contained PRs, as I have a limited bandwidth to work on this project at the moment. Also, it will enable us to work on a nice approach iteratively.