hw/dv/tools/ralgen/README.md

# `ralgen`: A FuseSoC generator for UVM RAL package

The `ralgen.py` script is implemented as a
[FuseSoC generator](https://fusesoc.readthedocs.io/en/master/user/generators.html).
which enables the automatic creation of the SystemVerilog UVM RAL package and
its insertion into the dependency tree when compiling the DV testbench.

This approach is useful for DV simulation flows that use FuseSoC as the backend
to generate the filelist for compilation. A separate RAL package generation
step is no longer needed since it gets handled within FuseSoC.

## Generator

The adjoining `ralgen.core` file registers the `ralgen` generator. The FuseSoC
core file that 'calls' the generator adds it as a dependency. When calling the
generator, the following parameters are set:
* **name (mandatory)**: Name of the RAL package (typically, same is the IP).
* **dv_base_prefix (optional)**: The prefix added to the base classes from
  which the register classes are derived. Set this option to derive the register
  classes not from the default `dv_base_reg`, but from user defined custom
  class definitions.
* **ip_hjson**: Path to the hjson specification written for an IP which includes
  the register descriptions. This needs to be a valid input for `reggen`.
* **top_hjson**: Path to the hjson specification for a top level design. This
  needs to be a valid input for `topgen`.

Only one of the last two arguments is mandatory. If both are set, or if neither
of them are, then the tool throws an error and exits.

The following snippet shows how it is called:
```
generate:
  ral:
    generator: ralgen
    parameters:
      name: <name>
      ip_hjson|top_hjson: <path-to-hjson-spec>
      [dv_base_prefix: my_base]


targets:
  default:
    ...
    generate:
      - ral
```

Note that the path to `hjson` specification in the snippet above is relative
to the core file in which the generator is called.

## `ralgen` script

When FuseSoC processes the dependency list and encounters a generator, it
passes a YAML file containing the above parameters to the generator tool
(the `ralgen.py`) as a single input. It then parses the YAML input to
extract those parameters.

`ralgen.py` really is just a wrapper around
[`reggen`]({{< relref "util/reggen/README.md" >}}) and the `util/topgen.py`
scripts, which are the ones that actually create the RAL package.
Due to the way those scripts are implemented, RAL packages for the IP level
testbenches are generated using
[`reggen`](({{< relref "util/reggen/README.md" >}})), and for the chip level
testbench, `util/topgen.py`. Which one to choose is decided by whether
the `ip_hjson` or `top_hjson` parameter is supplied.

In addition, the `ralgen.py` script also creates a FuseSoC core file. It uses
the `name` parameter to derive the
[VLNV](https://fusesoc.readthedocs.io/en/master/user/overview.html#core-naming-rules)
name for the generated core file.

The generated core file adds **`lowrisc:dv:dv_base_reg`** as a dependency for
the generated RAL package. This is required because our DV register block,
register and field models are derived from the
[DV library]({{< relref "hw/dv/sv/dv_lib/README.md" >}}) of classes. This
ensures the right compilation order is maintained. If the `dv_base_prefix`
argument is set, then it adds **`lowrisc:dv:my_base_reg`** as an extra
dependency, where `my_base` is the value of the argument as shown in the
example above. This core file and the associated sources are assumed to be
available in the provided FuseSoC search paths.

## Limitations

The script is not designed to be manually invoked, but in theory, it can be, if
a YAML file that contains the right set of parameters is presented to it
(compliant with FuseSoC).

If the user wishes to create the RAL package manually outside of the DV
simulation flow, then the `make` command can be invoked in the `hw/'` area
instead. It generates the RTL, DV and SW collaterals for all IPs, as well as
the top level in a single step.