[dv, doc] doc & Hjson tesetplan fixes
- replaced {hjson, HJSON} with Hjson
- updated all existing Hjson testplans (along with the templates) to use
{V1, V2, V3} instead of lower case
- additional minor style related fixes
diff --git a/hw/dv/sv/dv_lib/README.md b/hw/dv/sv/dv_lib/README.md
index 81308af..434de3b 100644
--- a/hw/dv/sv/dv_lib/README.md
+++ b/hw/dv/sv/dv_lib/README.md
@@ -1,22 +1,53 @@
-### dv_base_reg_block
-This class extends from uvm_reg_block and is used as the base class of all
-auto-generated UVM RAL models for all IPs. This class provides a virtualized
-`build(base_addr)` method that is used by the actual derived RAL models to build
-the entire RAL structure. An instance of the RAL model is created in `cip_base_cfg`.
-The model is however, locked by calling `uvm_reg_block::lock_model()` during
-`cip_base_env::end_of_elaboration_phase()` to allow any customizations to
-the RAL structures if needed during the`build_phase`.
+# DV library classes
-There are a few enhancement planned in future to this base ral model, that will
-automatically be available in the extended IP specific RAL models through
-inheritance:
-* CSR exclusion automation:
- We will add cip_base_reg and cip_base_field extensions to add attributes that
- can be automated during the IP ral model auto-generation, which can be used to
- exclude certain CSRs and fields from the CSR suite of tests.
-* Support parameterized RAL model generation:
- In future, we may have parameterized IPs that will have parameterized number of
- CSRs / fields. Having this base class provides a path to support this.
+{{% toc 4 }}
-TODO add description for the other classes
+## Overview
+The DV library classes form the base layer / framework for constructing UVM
+testbenches. These classes provide features (settings, methods, hooks and other
+constructs used in verification) that are generic enough to be reused across
+all testbenches.
+In this doc, we will capture some of the most salient / frequently used features
+in extended classes. These classes are being updated frequently. So, for a more
+detailed understanding, please read the class definitions directly.
+
+The DV library classes fall into 3 categories - UVM RAL (register abstraction
+layer), UVM agent, and UVM environment extensions.
+
+### UVM RAL extensions
+The RAL model generated using the [reggen](../../../util/reggen/README.md) tool
+extend from these classes. These themselves extend from the corresponding RAL
+classes provided in UVM.
+
+#### `dv_base_reg_field`
+Currently, this class does not provide any additional features. One of the
+features planned for future is setting exclusion tags at the field level for the
+CSR suite of tests that will be extracted automatically from the Hjson-based
+IP CSR specification.
+
+#### `dv_base_reg`
+This class provides the following functions to support verification:
+* `gen_n_used_bits()`: This function returns the actual number of bits used in
+ the CSR (sum of all available field widths).
+* `get_msb_pos()`: This function returns the MSB bit position of all available
+ fields. CSR either ends at this bit (bit `TL_DW - 1) or has reserved / invalid
+ bits beyond this bit.
+
+#### `dv_base_reg_block`
+* ` build(uvm_reg_addr_t base_addr)`: This function is implemented as a pseudo
+ pure virtual function (returns a fatal error if called directly). It is used
+ for building the complete RAL model. For a polymorphic approach, the DV user
+ can use this class handle to create the extended (IP specific) class instance
+ and call this function to build the acuual RAL model. This is exactly how it
+ is done in [dv_base_env_cfg](# dv_base_env_cfg).
+
+#### `dv_base_reg_map`
+Currently, this class does not provide any additional features. Having this
+extension provides an opportunity to add common features in future.
+
+### UVM Agent extensions
+TODO
+
+### UVM Environment extensions
+TODO
diff --git a/hw/dv/sv/i2c_agent/README.md b/hw/dv/sv/i2c_agent/README.md
index ca68b60..c3f27ab 100644
--- a/hw/dv/sv/i2c_agent/README.md
+++ b/hw/dv/sv/i2c_agent/README.md
@@ -1,3 +1,5 @@
-{{% lowrisc-doc-hdr I2C DV UVM Agent }}
+# I2C UVM Agent
-I2C DV UVM Agent is extended from DV library agent classes.
+{{% toc 4 }}
+
+I2C UVM Agent is extended from DV library agent classes.
diff --git a/hw/dv/sv/jtag_agent/README.md b/hw/dv/sv/jtag_agent/README.md
index 97f780e..aacda54 100644
--- a/hw/dv/sv/jtag_agent/README.md
+++ b/hw/dv/sv/jtag_agent/README.md
@@ -1,3 +1,5 @@
-{{% lowrisc-doc-hdr JTAG DV UVM Agent }}
+# JTAG UVM Agent
-JTAG DV UVM Agent is extended from DV library agent classes.
+{{% toc 4 }}
+
+JTAG UVM Agent is extended from DV library agent classes.
diff --git a/hw/dv/sv/spi_agent/README.md b/hw/dv/sv/spi_agent/README.md
index 0d66eff..2850f37 100644
--- a/hw/dv/sv/spi_agent/README.md
+++ b/hw/dv/sv/spi_agent/README.md
@@ -1 +1,5 @@
-# SPI Agent
+# SPI UVM Agent
+
+{{% toc 4 }}
+
+SPI UVM Agent is extended from DV library agent classes.
diff --git a/hw/dv/sv/tl_agent/README.md b/hw/dv/sv/tl_agent/README.md
index d485a36..1ec0990 100644
--- a/hw/dv/sv/tl_agent/README.md
+++ b/hw/dv/sv/tl_agent/README.md
@@ -1 +1,4 @@
-# TileLink Agent
+# TileLink UVM Agent
+
+{{% toc 4 }}
+
diff --git a/util/uvmdvgen/README.md.tpl b/util/uvmdvgen/README.md.tpl
index 4164db7..85783d4 100644
--- a/util/uvmdvgen/README.md.tpl
+++ b/util/uvmdvgen/README.md.tpl
@@ -1,3 +1,5 @@
-{{% lowrisc-doc-hdr ${name.upper()} DV UVM Agent }}
+# ${name.upper()} UVM Agent
-${name.upper()} DV UVM Agent is extended from DV library agent classes.
+{{% toc 4 }}
+
+${name.upper()} UVM Agent is extended from DV library agent classes.
