[doc] minor fixes to dv related docs
- fixed broken links in the DV plan templates
- fixed bullets in util docs
diff --git a/hw/dv/doc/dv_plan_template.md b/hw/dv/doc/dv_plan_template.md
index 0ec2db2..823f5af 100644
--- a/hw/dv/doc/dv_plan_template.md
+++ b/hw/dv/doc/dv_plan_template.md
@@ -1,16 +1,15 @@
-<!-- Copy this file to hw/ip/foo/doc/foo_dv_plan.md and make changes as needed.
-For convenience 'foo' in the document can be searched and replaced easily with the
-desired IP (with case sensitivity!). Also, use the testbench block diagram here:
-https://drive.google.com/open?id=1LfnTSutIW5E6zSCOCf4-scS8MQ8lXhPAPgSfFx2Aqh0
-as a starting point and modify it to reflect your foo testbench and save it
-to hw/ip/foo/doc/tb.svg. It should get linked and rendered under the block
-diagram section below. Please update / modify / remove sections below as
-applicable. Once done, remove this comment before making a PR. -->
-
---
title: "FOO DV Plan"
---
+<!-- Copy this file to hw/ip/foo/doc/foo_dv_plan.md and make changes as needed.
+For convenience 'foo' in the document can be searched and replaced easily with the
+desired IP (with case sensitivity!). Also, use the testbench block diagram
+located at OpenTitan team drive / 'design verification'
+as a starting point and modify it to reflect your foo testbench and save it
+to hw/ip/foo/doc/tb.svg. It should get linked and rendered under the block
+diagram section below. Please update / modify / remove sections below as
+applicable. Once done, remove this comment before making a PR. -->
## Goals
* **DV**
@@ -25,7 +24,8 @@
* DV regression results dashboard (link TBD)
## Design features
-For detailed information on FOO design features, please see the [FOO design specification](foo.md).
+<!-- TODO: uncomment link to the spec below -->
+For detailed information on FOO design features, please see the [FOO HWIP technical specification]({{</* relref "hw/ip/foo/doc" */>}}).
## Testbench architecture
FOO testbench has been constructed based on the [CIP testbench architecture]({{< relref "hw/dv/sv/cip_lib/doc" >}}).
@@ -115,4 +115,4 @@
## Testplan
<!-- TODO: uncomment the line below after adding the testplan -->
-{{</* testplan "../data/foo_testplan.hjson" */>}}
+{{</* testplan "hw/ip/foo/data/foo_testplan.hjson" */>}}
diff --git a/util/testplanner/README.md b/util/testplanner/README.md
index 94541d6..1c32b96 100644
--- a/util/testplanner/README.md
+++ b/util/testplanner/README.md
@@ -1,58 +1,58 @@
---
+title: "Testplanner tool"
---
-# Testplanner tool
-
Testplanner is a Python based tool for parsing testplans written in Hjson
format into a data structure that can be used for:
* Expanding the testplan inline within the DV plan as a table
* Annotating the regression results with testplan entries for a document driven DV execution
-Please see [DV methodology](\{\{\< relref "doc/ug/dv_methodology.md" \>\}\}) for more details on the
-rationale and motivation for writing and maintaining testplans in a machine-parsable
-format (`Hjson`).
-
-This document will focus on the anatomy of a Hjson testplan,
-list of features supported and some of the ways of using the tool.
+Please see [DV methodology]({{< relref "doc/ug/dv_methodology.md#documentation" >}})
+for more details on the rationale and motivation for writing and maintaining testplans
+in a machine-parsable format (`Hjson`).
+This document will focus on the anatomy of a Hjson testplan, list of features supported
+and some of the ways of using the tool.
## Hjson Testplan
-### Testplan entry contents
+
+### Testplan entries
Minimally, the following items are sufficient to adequately capture the
intent of a planned test:
* **name: name of the planned test**
- This is a single `lower_snake_case` string that succinctly describes the intended
- feature being tested. As an example, a basic sanity test which is typically the
- first test written on a brand new testbench would be simply named `sanity`.
+ This is a single `lower_snake_case` string that succinctly describes the intended
+ feature being tested. As an example, a basic sanity test which is typically the
+ first test written on a brand new testbench would be simply named `sanity`.
* **milestone: verification milestone**
- This is one of {"`V1`", "`V2`" and "`V3`"}. This allows us concretely indicate that
- all goals for a particular milestone have been achieved and we can transition
- to the next.
+ This is one of {"`V1`", "`V2`" and "`V3`"}. This allows us to concretely indicate
+ that all goals for a particular milestone have been achieved and we can
+ transition to the next.
* **desc: description of the planned test**
- A multi-line string that briefly describes the intent of the test. It is
- recommended to add a high level goal, stimulus and checking procedure so
- that the reader gets the full picture of what and how the said feature is being
- tested.
+ A multi-line string that briefly describes the intent of the test. It is
+ recommended to add a high level goal, stimulus and checking procedure so
+ that the reader gets the full picture of what and how the said feature is being
+ tested.
- Full [markdown]({{< relref "doc/rm/markdown_usage_style" >}}) syntax is supported when writing
- the description.
+ Full [markdown]({{< relref "doc/rm/markdown_usage_style" >}}) syntax is supported
+ when writing the description.
* **tests: list of actual written tests that maps to this planned test**
- Testplans are written very early in the V0 stage of the HW development
- [life-cycle]({{< relref "doc/project/hw_stages.md" >}}). When the DV engineer gets to actually
- developing the test, it may not map 1:1 to the planned test - it may be possible
- that an already written test that mapped to another planned test also satisfies
- the current one; OR it may also be possible that the planned test needs to be
- split into multiple smaller tests. To cater to these needs, we provide the ability
- to set a list of actual written tests that maps to each planned test. This
- information will then be used to map the regression results and annotate them
- to the tesplan to generate the final table. This list does not have to be populated
- right away. It can be updated as and when tests are written.
+ Testplan is written in the initial work stage of the verification
+ [life-cycle]({{< relref "doc/project/hw_stages#hardware-verification-stages" >}}).
+ When the DV engineer gets to actually developing the test, it may not map 1:1 to
+ the planned test - it may be possible that an already written test that mapped
+ to another planned test also satisfies the current one; OR it may also be
+ possible that the planned test needs to be split into multiple smaller tests.
+ To cater to these needs, we provide the ability to set a list of actual written
+ tests that maps to each planned test. This information will then be used to map
+ the regression results and annotate them to the tesplan to generate the final
+ table. This list does not have to be populated right away. It can be updated
+ as and when tests are written.
If need arises, more entries can be added to this list relatively easily.
@@ -161,19 +161,21 @@
```
### Example sources
+
The following examples provided within `util/testplanner/examples` can be used as
a starting point.
-- **`foo_testplan.hjson`**: DUT testplan
-- **`common_testplan.hjson`**: shared testplan imported within the DUT tesplan
-- **`foo_dv_plan.md`**: DUT testplan imported within the DV plan doc in markdown
+* **`foo_testplan.hjson`**: DUT testplan
+* **`common_testplan.hjson`**: shared testplan imported within the DUT tesplan
+* **`foo_dv_plan.md`**: DUT testplan imported within the DV plan doc in markdown
In addition, see the [UART DV Plan]({{< relref "hw/ip/uart/doc/dv_plan" >}}) for a
real 'production' example of inline expansion of an imported testplan as a table
within the DV Plan document.
-The [UART tesplan](https://github.com/lowRISC/opentitan/blob/master/hw/ip/uart/data/uart_testplan.hjson) imports the shared
-testplans located at `hw/dv/tools/testplans` area.
+The [UART tesplan](https://github.com/lowRISC/opentitan/blob/master/hw/ip/uart/data/uart_testplan.hjson)
+imports the shared testplans located at `hw/dv/tools/testplans` area.
### Limitations
+
The following limitations currently hold:
* Only the DUT testplan can import shared testplans; the imported
testplans cannot further import more testplans
@@ -181,7 +183,9 @@
its imported tetsplans need to be unique
## Usage examples
+
### Standalone tool invocations
+
Generate the testplan table in HTML to stdout:
```console
$ util/testplanner.py testplanner/examples/foo_testplan.hjson
diff --git a/util/uvmdvgen/README.md b/util/uvmdvgen/README.md
index c93b1a8..b3cd00d 100644
--- a/util/uvmdvgen/README.md
+++ b/util/uvmdvgen/README.md
@@ -1,4 +1,6 @@
-# uvmdvgen: UVM agent & complete testbench boilerplate code auto-generation tool
+---
+title: "Uvmdvgen: Initial testbench auto-generation tool"
+---
`uvmdvgen` is a Python 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
@@ -10,13 +12,12 @@
When starting with a new DV effort, the user typically goes through a copy-paste
exercise to replicate an existing UVM testbench code to the current one and has
to go through several debug cycles to get it working. This tool aims to
-eliminate that. Also, as a part of the 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 environment from the common
-code, the effort is drastically reduced.
+eliminate that. Also, as a part of our
+[DV methodology]({{< relref "doc/ug/dv_methodology#code-reuse" >}}),
+we provide utilities and base class structures that contain several
+pieces of common code which can be reused when setting up a new DV environment.
### Help switch (-h)
-
Running the tool with `-h` switch provides a brief description of all available
switches.
```console
@@ -61,7 +62,6 @@
```
### 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]({{< relref "hw/dv/sv/dv_lib/README.md" >}}). Please see
@@ -70,86 +70,87 @@
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.
+ 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`.
+ 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`.
+ 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`.
+ 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 the monitor component extended from `dv_base_monitor`. It provides
+ the following items:
- 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`.
+ * `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 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:
- This task is for resetting the initial value of the `vif` signals.
+ * `virtual task reset_signals()`
- * `virtual task get_and_drive()`
+ This task is for resetting the initial value of the `vif` signals.
- 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.
+ * `virtual task get_and_drive()`
- If the `-s` switch is passed, the tool creates `jtag_host_driver` and
- `jtag_device_driver` instead, and their contents are exactly the same.
+ 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`.
+ This is extended from `dv_base_seq`.
* `seq_lib/jtag_seq_list`
- This is a list of sequences included in one place.
+ 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.
+ 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.
+ 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 separately.
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
+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]({{< relref "hw/dv/sv/dv_lib/README.md" >}}). If the `-c` switch is
-passed, it extends from [cip library]({{< relref "hw/dv/sv/cip_lib/doc" >}}). With
-`-ea` switch, user can provide a list of downstream agents to create within the
-environment. Please see description for more details.
+extend from [DV base library]({{< relref "hw/dv/sv/dv_lib/README.md" >}}).
+If the `-c` switch is passed, it extends from
+[CIP base library]({{< relref "hw/dv/sv/cip_lib/doc" >}}). 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
@@ -163,132 +164,130 @@
(don't create interrupts or alerts). When set, it will create `intr_if` and
`alerts_if` in the testbench and set them into `uvm_config_db` for the
`cip_base_env` to pick up.
-
* `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.
+ 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.
+ 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]({{< relref "util/reggen/README.md" >}}).
+ 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]({{< relref "util/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.
+ 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.
+ 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.
+ 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 `i2c_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`.
+ This is the basic sanity test sequence that user needs to develop as the first
+ test sequence. It extends from `i2c_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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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]({{< relref "hw/dv/tools/README.md" >}}).
- It already includes the sanity and CSR suite of tests to allow users to start
- running tests right away.
+ This is the simulation Makefile that is used as the starting point for
+ building and running tests using the [make flow]({{< relref "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`
+* `i2c_host_dv_plan.md`
- This is the empty DV plan document that will describe the entire testbench. A
- template for this is available [here](https://github.com/lowRISC/opentitan/blob/master/hw/dv/doc/dv_plan_template.md).
+ This is the initial DV plan document that will describe the entire testbench. This
+ is equivalent to the template available [here](https://github.com/lowRISC/opentitan/blob/master/hw/dv/doc/dv_plan_template.md).
#### Examples
-
```console
$ util/uvmdvgen.py i2c -a
```
@@ -325,7 +324,6 @@
This will create the complete `i2c_host` DV testbench extended from CIP lib and will
instantiate `i2c_agent`.
-
```console
$ util/uvmdvgen.py dma -e -eo hw/ip/dma/dv
```
diff --git a/util/uvmdvgen/dv_plan.md.tpl b/util/uvmdvgen/dv_plan.md.tpl
index 2e404b7..7907f67 100644
--- a/util/uvmdvgen/dv_plan.md.tpl
+++ b/util/uvmdvgen/dv_plan.md.tpl
@@ -1,17 +1,16 @@
+---
+title: "${name.upper()} DV Plan"
+---
+
<!-- Copy this file to hw/ip/${name}/doc/${name}_dv_plan.md and make changes as needed.
For convenience '${name}' in the document can be searched and replaced easily with the
-desired IP (with case sensitivity!). Also, use the testbench block diagram here:
-https://drive.google.com/open?id=1LfnTSutIW5E6zSCOCf4-scS8MQ8lXhPAPgSfFx2Aqh0
+desired IP (with case sensitivity!). Also, use the testbench block diagram
+located at OpenTitan team drive / 'design verification'
as a starting point and modify it to reflect your ${name} testbench and save it
to hw/ip/${name}/doc/tb.svg. It should get linked and rendered under the block
diagram section below. Please update / modify / remove sections below as
applicable. Once done, remove this comment before making a PR. -->
-{{% lowrisc-doc-hdr ${name.upper()} DV Plan }}
-{{% import_testplan ../data/${name}_testplan.hjson }}
-
-{{% toc 4 }}
-
${'##'} Goals
* **DV**
* Verify all ${name.upper()} IP features by running dynamic simulations with a SV/UVM based testbench
@@ -20,15 +19,15 @@
* Verify TileLink device protocol compliance with an SVA based testbench
${'##'} Current status
-* [Design & verification stage](../../../../doc/project/hw_dashboard.md)
- * [HW development stages](../../../../doc/project/hw_stages.md)
+* [Design & verification stage]({{< relref "doc/project/hw_dashboard" >}})
+ * [HW development stages]({{< relref "doc/project/hw_stages" >}})
* DV regression results dashboard (link TBD)
${'##'} Design features
-For detailed information on ${name.upper()} design features, please see the [${name.upper()} design specification](${name}.md).
+For detailed information on ${name.upper()} design features, please see the [${name.upper()} HWIP technical specification]({{< relref "hw/ip/${name}/doc" >}}).
${'##'} Testbench architecture
-${name.upper()} testbench has been constructed based on the [CIP testbench architecture](../../../dv/sv/cip_lib/README.md).
+${name.upper()} testbench has been constructed based on the [CIP testbench architecture]({{< relref "hw/dv/sv/cip_lib/doc" >}}).
${'###'} Block diagram
@@ -36,17 +35,17 @@
${'###'} Top level testbench
Top level testbench is located at `hw/ip/${name}/dv/tb/tb.sv`. It instantiates the ${name.upper()} DUT module `hw/ip/${name}/rtl/${name}.sv`.
In addition, it instantiates the following interfaces, connects them to the DUT and sets their handle into `uvm_config_db`:
-* [Clock and reset interface](../../../dv/sv/common_ifs/README.md)
-* [TileLink host interface](../../../dv/sv/tl_agent/README.md)
+* [Clock and reset interface]({{< relref "hw/dv/sv/common_ifs/README.md" >}})
+* [TileLink host interface]({{< relref "hw/dv/sv/tl_agent/README.md" >}})
* ${name.upper()} IOs
-* Interrupts ([`pins_if`](../../../dv/sv/common_ifs/README.md))
-* Alerts ([`pins_if`](../../../dv/sv/common_ifs/README.md))
-* Devmode ([`pins_if`](../../../dv/sv/common_ifs/README.md))
+* Interrupts ([`pins_if`]({{< relref "hw/dv/sv/common_ifs/README.md" >}})
+* Alerts ([`pins_if`]({{< relref "hw/dv/sv/common_ifs/README.md" >}})
+* Devmode ([`pins_if`]({{< relref "hw/dv/sv/common_ifs/README.md" >}})
${'###'} Common DV utility components
The following utilities provide generic helper tasks and functions to perform activities that are common across the project:
-* [dv_utils_pkg](../../../dv/sv/dv_utils/README.md)
-* [csr_utils_pkg](../../../dv/sv/csr_utils/README.md)
+* [dv_utils_pkg]({{< relref "hw/dv/sv/dv_utils/README.md" >}})
+* [csr_utils_pkg]({{< relref "hw/dv/sv/csr_utils/README.md" >}})
${'###'} Compile-time configurations
[list compile time configurations, if any and what are they used for]
@@ -60,7 +59,7 @@
% if is_cip:
${'###'} TL_agent
-${name.upper()} testbench instantiates (already handled in CIP base env) [tl_agent](../../../dv/sv/tl_agent/README.md)
+${name.upper()} testbench instantiates (already handled in CIP base env) [tl_agent]({{< relref "hw/dv/sv/tl_agent/README.md" >}})
which provides the ability to drive and independently monitor random traffic via
TL host interface into ${name.upper()} device.
% endif
@@ -77,7 +76,7 @@
[Describe here or add link to its README]
${'###'} RAL
-The ${name.upper()} RAL model is constructed using the [regtool.py script](../../../../util/reggen/README.md) and is placed at `env/${name}_reg_block.sv`.
+The ${name.upper()} RAL model is constructed using the [regtool.py script]({{< relref "util/reggen/README.md" >}}) and is placed at `env/${name}_reg_block.sv`.
${'###'} Reference models
[Describe reference models in use if applicable, example: SHA256/HMAC]
@@ -107,13 +106,13 @@
<!-- explain inputs monitored, flow of data and outputs checked -->
${'####'} Assertions
-* TLUL assertions: The `tb/${name}_bind.sv` binds the `tlul_assert` [assertions](../../tlul/doc/TlulProtocolChecker.md) to the IP to ensure TileLink interface protocol compliance.
+* TLUL assertions: The `tb/${name}_bind.sv` binds the `tlul_assert` [assertions]({{< relref "hw/ip/tlul/doc/TlulProtocolChecker.md" >}}) to the IP to ensure TileLink interface protocol compliance.
* Unknown checks on DUT outputs: The RTL has assertions to ensure all outputs are initialized to known values after coming out of reset.
* assert prop 1:
* assert prop 2:
${'##'} Building and running tests
-We are using our in-house developed [regression tool](../../../dv/tools/README.md) for building and running our tests and regressions.
+We are using our in-house developed [regression tool]({{< relref "hw/dv/tools/README.md" >}}) for building and running our tests and regressions.
Please take a look at the link for detailed information on the usage, capabilities, features and known issues.
Here's how to run a basic sanity test:
```console
@@ -122,4 +121,5 @@
```
${'##'} Testplan
-{{% insert_testplan x }}
+<!-- TODO: uncomment the line below after adding the testplan -->
+{{</* testplan "hw/ip/${name}/data/${name}_testplan.hjson" */>}}
