util/reggen/README.md

# Reggen -- Register generator

Reggen is a python3 tool to read register descriptions in hjson and
generate various output formats. Currently it 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.

```
$ cd $REPO_TOP/util
$ python3 reggen/regtool.py --doc | python3 docgen/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 module.

The regtool provides a standalone way to run reggen. In the future
this will be used to generate other formats like verilog and header
files.

Note that the same example inputs are used here as for docgen.

Generate html from the register description and be verbose. Since
embeddable html is generated the css is not included so the output
will look messy (TODO should the css be added for the standalone
case?):

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

Generate standard json from the register description:

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

Generate compact json and use it to generate html:

```
$ cd $REPO_TOP/util
$ ./regtool.py -v -c docgen/examples/uartregs.hjson | python3 reggen/regtool.py -v -d > /tmp/outuart.html
```

Generate RTL from register definition:
```
$ cd $REPO_TOP/util
$ mkdir /tmp/rtl
$ ./regtool.py -r -t /tmp/rtl ../hw/ip/uart/doc/uart_reg.hjson
```

Generate DV UVM class from register definition:

```console
$ cd $REPO_TOP/util
$ mkdir /tmp/dv
$ ./regtool.py -s -t /tmp/dv ../hw/ip/uart/doc/uart_reg.hjson
```

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