# uvmdvgen: UVM agent & complete testbench boilerplate code auto-generation tool

uvmdvgen is a python3 based tool to generate the boilerplate code for a UVM agent
as well as the complete UVM testbench for a given DUT. The tool generates all
the relevant UVM-based classes including the package and the fusesoc core file
to make it quickly plug-and-playable. The packages import the standard
utility and library packages wherever applicable, to conform to our existing
methodology and style.

When starting with a new DV effort, user goes through a copy-paste exercise to
replicate an existing UVM testbench code to the current one and has to go though
several debug cycles to get it working. This tool aims to eliminate that. Also,
as a part of OpenTitan DV methodology, we have several utilities and base class
structures (such as DV lib and CIP lib) that share all of the common code. By
extending a new DV enviroment from the common code, the effort is drastically
reducecd.

### Setup
The tool uses the mako based templates, so the following tool is required as
dependency:
```
$ pip3 install --user mako
```

### Help switch (-h)
Running the tool with `-h` switch provides a brief description of all available
switches.
```
$ util/uvmdvgen.py -h
usage: uvmdvgen.py [-h] [-a] [-s] [-e] [-c] [-ea [name] [[name] ...]]
                   [-ao [hw/dv/sv]] [-eo [hw/ip/<ip>/dv]]
                   [ip/block name]

Command-line tool to autogenerate boilerplate DV testbench code extended from dv_lib / cip_lib

positional arguments:
  [ip/block name]       Name of the ip/block for which the UVM TB is being
                        auto-generated

optional arguments:
  -h, --help            show this help message and exit
  -a, --gen_agent       Generate UVM agent code extended from DV library
  -s, --has_separate_host_device_driver
                        IP / block agent creates a separate driver for host
                        and device modes. (ignored if -a switch is not passed)
  -e, --gen_env         Generate testbench UVM environment code
  -c, --is_cip          Is comportable IP - this will result in code being
                        extended from CIP library. If switch is not passed,
                        then the code will be extended from DV library
                        instead. (ignored if -e switch is not passed)
  -ea agt1 agt2 [agt1 agt2 ...], --env_agents agt1 agt2 [agt1 agt2 ...]
                        Env creates an interface agent specified here. They are
                        assumed to already exist. Note that the list is space-
                        separated, and not comma-separated. (ignored if -e
                        switch is not passed)
  -ao [hw/dv/sv], --agent_outdir [hw/dv/sv]
                        Path to place the agent code. A directory called
                        <name>_agent is created at this location. (default set
                        to './<name>')
  -eo [hw/ip/<ip>/dv], --env_outdir [hw/ip/<ip>/dv]
                        Path to place the env code. 3 directories are created
                        - env, tb and tests. (default set to './<name>')
```

### Generating UVM agent
The boilerplate code for a UVM agent for an interface can be generated using the
`-a` switch. This results in the generation of complete agent with classes that
extend from the [dv library](../../hw/dv/sv/dv_lib/README.md). Please see
description for more details.

The tool generates an interface, item, cfg, cov, monitor, driver and sequence
library classes. Let's take `jtag` as the argument passed for the name of the IP.
The following describes their contents in each source generated:

* **jtag_if**

  This is an empty shell of an interface. User is required to add content.

* **jtag_item**

  This is an empty transaction packet extended from `uvm_sequence_item`.

* **jtag_agent_cfg**

  This is the agent configuration object, it contains the virtual interface
  handle for `jtag_if` and is called `vif`.

* **jtag_agent_cov**

  This is a coverage component extended from `dv_base_agent_cov`.

* **jtag_monitor**

  This is the monitor component extended from `dv_base_monitor`. It provides
  the following items:
  * **virtual protected task collect_trans(uvm_phase phase)**

    This is a shell task within which user is required to add logic to detect
    an event, sample the interface and create a transaction object and write
    to the analysis port. This task is called in `dv_base_monitor::run_phase`.

* **jtag_driver**

  This is the monitor component extended from `jtag_driver` which is typedef'ed
  in the pkg to `dv_base_driver` with the right parameter set. It provides the
  following items:
  * **virtual task reset_signals()**

    This task is for resetting the initial value of the `vif` signals.

  * **virtual task get_and_drive()**

    This task is used to get the next item from the sequencer, apply it to the
    interface and return the response back. This is again, an empty task at the
    moment.

  If the `-s` switch is passed, the tool creates `jtag_host_driver` and
  `jtag_device_driver` instead, and their contents are exactly the same.

* **seq_lib/jtag_base_seq**

  This is extended from `dv_base_seq`.

* **seq_lib/jtag_seq_list**

  This is a list of sequences included in one place.

* **jtag_agent_pkg**

  This is the package file that includes all of the above sources and the imports
  the dependent packages.

* **jtag_agent.core**

  This is the fusesoc core file that is used to generate the filelist for
  the build.

The tool does not create `jtag_sequencer` or `jtag_agent` classes separetely.
Instead, it typedef's the `dv_base_sequencer` and `dv_base_agent` respectively
with the right type-parameters in the pkg. The reason for this is having a
dedicated sequencer and agent is not required since the `dv_base_agent` already
has all the sub-component instantiations and connections; and `dv_base_sequencer`
already has a handle to the agent cfg object and nothing more is typically needed.

### Generating UVM environment & testbench
The boilerplate code for a UVM environment and the testbench for a DUT can be
generated using the `-e` switch. This results in the generation of classes
that extend from [dv library](../../hw/dv/sv/dv_lib/README.md). If the `-c`
switch is passed, it extends from [cip library](../../hw/dv/sv/cip_lib/README.md).
With `-ea` switch, user can provide a list of downstream agents to create within
the environment.
Please see description for more details.

The tool generates not only the UVM environment, but also the base test,
testbench, top level fusesoc core file with sim target, Makefile that already
includes the sanity and CSR test suite and more. With just a few tweaks, this
enables the user to reach the V1 milestone much quicker.  Let's take `i2c_host`
as the argument passed for the name of the IP. The following is the list of
files generated with a brief description of their contents:

* **env/i2c_host_env_cfg**

  This is the env cfg object. It creates the downstream agent cfg objects that
  were passed using the `-ea` switch in the ``initialize()` function which is
  called in the `dv_base_test::build_phase()`. Since the cfg handle is passed to
  all env components, those downstream agent cfg objects can be hierarchically
  referenced.

* **env/i2c_host_env_cov**

  This is the coverage component class. A handle of this class is passed to the
  scoreboard and the virtual sequencer so that covergroups can be sampled in the
  scoreboard as well as sequences.

* **env/i2c_host_reg_block**

  This is the UVM reg based RAL model. This is created for completeness. The
  actual RAL model needs to be generated prior to running simulations using the
  [regtool](../reggen/README.md).

* **env/i2c_host_scoreboard**

  This is the scoreboard component that already creates the analysis fifos and
  queues for the agents passed via `-ea` switch. It adds starter tasks for
  processing each fifo in a forever loop and invokes them in the `run_phase`
  using `fork-join` statement. If the `-c` switch is passed, it also adds a
  `process_tl_access` task that is extended from `cip_base_scoreboard`. This
  task provides a tilelink access packet for further processing.

* **env/i2c_host_virtual_sequencer**

  This is the virtual sequencer used by all test sequences to run the traffic.
  It adds handles to downstream agent sequencers passed via `-ea` switch.
  Sub-sequences can be started on them via the `p_sequencer` handle.

* **env/seq_lib/i2c_host_base_vseq**

  This is the base virtual sequence that user can use to add common tasks,
  functions and variables that other extended test sequences can reuse. For
  starters, it provides the `i2s_host_init()` task and `do_i2c_host_init` knob
  for controllability.

* **env/seq_lib/i2c_host_sanity_vseq**

  This is the basic sanity test sequence that user needs to develop as the first
  test sequence. It extends from `i2s_host_base_vseq`.

* **env/seq_lib/i2c_host_csr_vseq**

  This is the test sequence for the entire CSR suite of tests. It calls
  `dv_base_vseq::run_csr_vseq_wrapper()` task which is a complete test sequence.
  All the user needs to do is run the CSR tests and add exclusions if needed
  using the `add_csr_exclusions()` function provided.

* **env/seq_lib/i2c_host_vseq_list**

  This is a list of test sequences included in one place.

* **env/i2c_host_env**

  This is the env class that creates the downstream agents passed via `-ea`
  switch. It sets their correspodnding cfg objects (which are members of env cfg
  object) into the `uvm_config_db`. It also makes the analysis port connections
  in the `connect_phase` and sets the sequencer handles in the virtual
  sequencer.

* **env/i2c_host_env_pkg**

  This is the env pkg file which includes all env classes and imports the
  dependent packages.

* **env/i2c_host_env.core**

  This is the fusesoc core file for the env pkg compile unit.

* **tests/i2c_host_base_test**

  This is the base test class. The base test class it extends from already
  creates the `env` and `cfg` objects, which are available for manipulation in
  UVM phases. This class's name would be supplied to UVM_TESTNAME plusarg to run
  tests using the UVM methodology.

* **tests/i2c_host_test_pkg**

  This is the test pkg file which includes all test classes and imports the
  dependent packages.

* **tests/i2c_host_test.core**

  This is the fusesoc core file for the test pkg compile unit.

* **tb/i2c_host_bind**

  This is the assertion bind file that is compiled along with the testbench in a
  multi-top architecture. If the `-c` switch is passed, it adds the `tlul_assert`
  module bind to the `i2c_host` DUT.

* **tb/tb**

  This is the top level testbench module that instantiates the DUT along with
  some of the interfaces that are required to be instantiated and connected and
  passed on the the `uvm_config_db` since the base DV/CIP library classes
  retrieve them. The user needs to look through the RTL and make additional
  connections as needed.

* **i2c_host_sim.core**

  This is the top level fusesoc core file with the sim target. It adds the rtl
  and dv dependencies to construct the complete filelist to pass to simulator's
  build step.

* **Makefile**

  This is the simulation Makefile that is used as the starting point for
  building and running tests using the [make flow](../../hw/dv/tools/README.md).
  It already includes the sanity and CSR suite of tests to allow users to start
  running tests right away.

* **plan.md**

  This is the empty DV plan document that will describe the entire testbench. A
  template for this is available [here](../../hw/dv/doc/plan.tpl.md).

#### Examples
```
util/uvmdvgen.py i2c -a
```
This will create `./i2c/i2c_agent` and place all sources there.

```
util/uvmdvgen.py jtag -a -ao hw/dv/sv
```
This will create `hw/dv/sv/jtag_agent` directory and place all the sources
there.

```
util/uvmdvgen.py i2c -a -s -ao hw/dv/sv
```
This will create the I2C agent with separate 'host' mode and 'device' mode drivers.

```
util/uvmdvgen.py i2c_host -e -c -ea i2c -eo hw/ip/i2c_host/dv
```
This will create the complete i2c_host dv testbench extended from CIP lib and will
instantiate `i2c_agent`.

```
util/uvmdvgen.py dma -e -eo hw/ip/dma/dv
```
This will create the complete dma dv testbench extended from DV lib. It does not
instantiate any downstream agents due to absence of `-ea` switch.

```
util/uvmdvgen.py chip -e -ea uart i2c jtag -eo hw/top_earlgrey/dv
```
This will create the complete chip testbench DV lib and will instantiate `uart_agent`,
`i2c_agent` and `jtag_agent` in the env.