# 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:

```console
$ 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](../../doc/rm/register_tool/index.md).
This references features in the [docgen](../docgen/README.md) suite
of documentation scripts.

```console
$ cd $REPO_TOP/util
$ ./build_docs.py
```

### Examples using standalone regtool

Normally for documentation the `build_docs.py` tool will automatically
use `reggen`. The script `regtool.py` provides a standalone way to run
`reggen`. See the
[register tool documentation](../../doc/rm/register_tool/index.md) for
details about how to invoke the tool.

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

```console
$ 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:

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

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

```console
$ 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.