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

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

For details on the register definition format, see the register tool documentation. To ensure things stay up to date, the register definition format information is documented by the tool itself.

Running $REPO_TOP/util/regtool.py --doc or $REPO_TOP/util/selfdoc.py reggen will print the JSON format information to standard output.

All documentation for this repo can be generated by running the following commands:

$REPO_TOP/util/site/build-docs.sh

Under the hood, one of the mdbook preprocessors (./util/mdbook_reggen.py) uses the reggen to generate register tables in the documentation.

Examples using standalone regtool

Normally for documentation the mdbook_reggen.py will automatically use reggen. The script regtool.py provides a standalone way to run reggen. See the register tool documentation for details about how to invoke the tool.

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/dv
    uart_ral_pkg.sv

By default, the generated block, register and field models are derived from dv_base_reg classes provided at hw/dv/sv/dv_base_reg. If required, the user can supply the --dv-base-names <block>:<type>:<entity-name> switch to have the models derive from custom, user-defined RAL classes instead:

$ cd $REPO_TOP/util
$ mkdir /tmp/dv
$ ./regtool.py -s -t /tmp/dv ../hw/ip/uart/data/uart.hjson \
  --dv-base-names <block>:<type>:<entity-name>
$ ls /tmp/dv
    uart_ral_pkg.sv

Multiple sources of DV base names may be passed in. <type> must be one of: pkg, block, reg, field, mem, all.

This makes the following assumptions:

• A FuseSoC core file aggregating the <my_base> RAL classes with the VLNV name pavona:dv:<my_base>_reg is provided in the cores search path.
• These custom classes are derived from the corresponding dv_base_reg classes and have the following names:
  • <my_base>_reg_pkg.sv: The RAL package that includes the below sources
  • <my_base>_reg_block.sv: The register block abstraction
  • <my_base>_reg.sv: The register abstraction
  • <my_base>_reg_field.sv: The register field abstraction
  • <my_base>_mem.sv: The memory abstraction
• If any of the above class specializations is not needed, it can be typedef’ed in <my_base>_reg_pkg:

  package <my_base>_reg_pkg;
    import dv_base_reg_pkg::*;
    typedef dv_base_reg_field <my_base>_reg_field;
    typedef dv_base_mem <my_base>_mem;
    `include "<my_base>_reg.sv"
    `include "<my_base>_reg_block.sv"
  endpackage
  

The following shows an example of how to generate a FPV CSR read write assertion module from a register description:

$ cd $REPO_TOP/util
$ mkdir /tmp/fpv/vip
$ ./regtool.py -f -t /tmp/fpv/vip ../hw/ip/uart/data/uart.hjson
$ ls /tmp/fpv
    uart_csr_assert_fpv.sv

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