Register generator reggen and regtool

The utility script regtool.py and collateral under reggen are Python tools to read register descriptions in Hjson and generate various output formats. The tool can output html documentation, standard json, compact standard json (whitespace removed) and Hjson. The example commands assume $REPO_TOP is set to the toplevel directory of the repo.

Setup

If packages have not previously been installed you will need to set a few things up. First use pip3 to install some required packages:

$ pip3 install --user hjson
$ pip3 install --user mistletoe
$ pip3 install --user mako

Register JSON Format

To ensure things stay up to date, the register json format information is documented by the tool itself. Documentation can be generated by running the tool to produce markdown and processing that into html. This information can also be found in the register tool documentation. This references features in the docgen suite of documentation scripts.

$ cd $REPO_TOP/util
$ ./regtool.py --doc | ./docgen.py -c > /tmp/outdoc.html

Examples using standalone regtool

Normally for documentation the docgen tool will automatically use reggen. See the examples in the docgen documentation tree.

The script regtool.py provides a standalone way to run reggen. Note that the same example inputs are used here as for docgen.

This generates html from the register description and is verbose. Since embeddable html is generated, the css is not included, so the output will not be perfectly formatted.

$ cd $REPO_TOP/util
$ ./regtool.py -v -d docgen/examples/uart.hjson > /tmp/outuart.html

The following shows an example of how to generate the full featured standard json from the register description Hjson file:

$ cd $REPO_TOP/util
$ ./regtool.py -v -j docgen/examples/uart.hjson > /tmp/outuart.json

The following shows an example of how to generate RTL from a register description:

$ cd $REPO_TOP/util
$ mkdir /tmp/rtl
$ ./regtool.py -r -t /tmp/rtl ../hw/ip/uart/data/uart.hjson
$ ls /tmp/rtl
    uart_reg_pkg.sv   uart_reg_top.sv

The following shows an example of how to generate a DV UVM class from a register description:

$ cd $REPO_TOP/util
$ mkdir /tmp/dv
$ ./regtool.py -s -t /tmp/dv ../hw/ip/uart/data/uart.hjson
$ ls /tmp/rtl
    uart_reg_block.sv

If the target directory is not specified, the tool creates the DV file under the hw/ip/{module}/dv/ directory.