[dv, doc] doc for dv_lib, plus some fixes - added README for dv_lib (WIP) - some basic fixes - fixes to support moving DV plan document to ip/*/doc and testplan Hjson to ip/*/data
diff --git a/hw/dv/doc/dv_plan_template.md b/hw/dv/doc/dv_plan_template.md index 25a1ef9..8ae9e81 100644 --- a/hw/dv/doc/dv_plan_template.md +++ b/hw/dv/doc/dv_plan_template.md
@@ -1,15 +1,15 @@ -<!-- Copy this file to hw/ip/foo/dv/foo_dv_plan.md and make changes as needed. +<!-- 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/dv/tb.svg. It should get linked and rendered under the block +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. --> {{% lowrisc-doc-hdr FOO DV Plan }} <!-- TODO: uncomment the line below after adding the testplan --> -<!-- {{% import_testplan foo_testplan.hjson }} --> +<!-- {{% import_testplan ../data/foo_testplan.hjson }} --> {{% toc 4 }} @@ -26,12 +26,10 @@ * DV regression results dashboard (link TBD) ## Design features -For detailed information on FOO design features, please see the -[FOO design specification](../doc/foo.md). +For detailed information on FOO design features, please see the [FOO design specification](foo.md). ## Testbench architecture -FOO testbench has been constructed based on the -[CIP testbench architecture](../../../dv/sv/cip_lib/README.md). +FOO testbench has been constructed based on the [CIP testbench architecture](../../../dv/sv/cip_lib/README.md). ### Block diagram  @@ -72,7 +70,7 @@ [Describe here or add link to its README] ### RAL -The FOO RAL model is constructed using the [regtool.py script](../../../../util/doc/rm/RegisterTool.md) and is placed at `env/foo_reg_block.sv`. +The FOO RAL model is constructed using the [regtool.py script](../../../../util/reggen/README.md) and is placed at `env/foo_reg_block.sv`. ### Reference models [Describe reference models in use if applicable, example: SHA256/HMAC]
diff --git a/hw/dv/sv/dv_lib/README.md b/hw/dv/sv/dv_lib/README.md index 434de3b..15f983c 100644 --- a/hw/dv/sv/dv_lib/README.md +++ b/hw/dv/sv/dv_lib/README.md
@@ -31,7 +31,7 @@ * `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 + fields. CSR either ends at this bit (bit \`TL_DW - 1) or has reserved / invalid bits beyond this bit. #### `dv_base_reg_block` @@ -39,8 +39,8 @@ 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). + and call this function to build the actual 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 @@ -51,3 +51,4 @@ ### UVM Environment extensions TODO +
diff --git a/hw/ip/uart/doc/uart_dv_plan.md b/hw/ip/uart/doc/uart_dv_plan.md index 92bc4ac..b501c31 100644 --- a/hw/ip/uart/doc/uart_dv_plan.md +++ b/hw/ip/uart/doc/uart_dv_plan.md
@@ -16,12 +16,10 @@ * DV regression results dashboard (link TBD) ## Design features -For detailed information on UART design features, please see the -[UART design specification](uart.md). +For detailed information on UART design features, please see the [UART design specification](uart.md). ## Testbench architecture -UART testbench has been constructed based on the -[CIP testbench architecture](../../../dv/sv/cip_lib/README.md). +UART testbench has been constructed based on the [CIP testbench architecture](../../../dv/sv/cip_lib/README.md). ### Block diagram [Block diagram](tb.svg) @@ -58,7 +56,7 @@ data, parity, baud rate etc. ### RAL -The UART RAL model is constructed using the [regtool.py script](../../../../util/doc/rm/RegisterTool.md) and is placed at `env/uart_reg_block.sv`. +The UART RAL model is constructed using the [regtool.py script](../../../../util/reggen/README.md) and is placed at `env/uart_reg_block.sv`. ### Stimulus strategy #### Test sequences
diff --git a/util/testplanner/README.md b/util/testplanner/README.md index 7053968..6376675 100644 --- a/util/testplanner/README.md +++ b/util/testplanner/README.md
@@ -160,10 +160,10 @@ - **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 [UART DV Plan](../../hw/ip/uart/dv/uart_dv_plan.md) for a +In addition, see [UART DV Plan](../../hw/ip/uart/doc/uart_dv_plan.md) for a real 'production' example of inline expansion of an imported testplan as a table within the DV Plan document done using [docgen](../docgen/README.md). -The [UART tesplan](../../hw/ip/uart/dv/uart_testplan.hjson) imports the shared +The [UART tesplan](../../hw/ip/uart/data/uart_testplan.hjson) imports the shared testplans located at `hw/dv/tools/testplans` area. ### Limitations @@ -213,7 +213,7 @@ plan document. This is done by invoking: ```console Example 1: -$ util/docgen.py -c ../hw/ip/uart/dv/uart_dv_plan.md -o /tmp/uart_dv_plan.html +$ util/docgen.py -c ../hw/ip/uart/doc/uart_dv_plan.md -o /tmp/uart_dv_plan.html Example 2: $ util/docgen.py -c testplanner/examples/foo_dv_plan.md -o /tmp/foo_dv_plan.html
diff --git a/util/uvmdvgen.py b/util/uvmdvgen.py index 18c56f3..adc5e83 100755 --- a/util/uvmdvgen.py +++ b/util/uvmdvgen.py
@@ -35,11 +35,10 @@ """IP / block agent creates a separate driver for host and device modes. (ignored if -a switch is not passed)""") - parser.add_argument( - "-e", - "--gen_env", - action='store_true', - help="Generate testbench UVM env code") + parser.add_argument("-e", + "--gen_env", + action='store_true', + help="Generate testbench UVM env code") parser.add_argument( "-c", @@ -88,9 +87,14 @@ "-eo", "--env_outdir", default="name", - metavar="[hw/ip/<ip>/dv]", - help="""Path to place the env code. 3 directories are created - env, - tb and tests. (default set to './<name>')""") + metavar="[hw/ip/<ip>]", + help= + """Path to place the full tetsbench code. It creates 3 directories - dv, data and doc. + The DV plan and the testplan Hjson files are placed in the doc and data directories + respectively. These are to be merged into the IP's root directory (with the existing + data and doc directories). Under dv, it creates 3 sub-directories - env, + tb and tests to place all of the testbench sources. (default set to './<name>')""" + ) args = parser.parse_args() if args.agent_outdir == "name": args.agent_outdir = args.name
diff --git a/util/uvmdvgen/dv_plan.md.tpl b/util/uvmdvgen/dv_plan.md.tpl index 6dd2cc7..3e61430 100644 --- a/util/uvmdvgen/dv_plan.md.tpl +++ b/util/uvmdvgen/dv_plan.md.tpl
@@ -1,15 +1,14 @@ -<!-- Copy this file to hw/ip/${name}/dv/${name}_dv_plan.md and make changes as needed. +<!-- 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 as a starting point and modify it to reflect your ${name} testbench and save it -to hw/ip/${name}/dv/tb.svg. It should get linked and rendered under the block +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 }} -<!-- TODO: uncomment the line below after adding the testplan --> -<!-- {{% import_testplan ${name}_testplan.hjson }} --> +{{% import_testplan ../data/${name}_testplan.hjson }} {{% toc 4 }} @@ -26,12 +25,10 @@ * DV regression results dashboard (link TBD) ${'##'} Design features -For detailed information on ${name.upper()} design features, please see the -[${name.upper()} design specification](../doc/${name}.md). +For detailed information on ${name.upper()} design features, please see the [${name.upper()} design specification](${name}.md). ${'##'} 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](../../../dv/sv/cip_lib/README.md). ${'###'} Block diagram  @@ -80,7 +77,7 @@ [Describe here or add link to its README] ${'###'} RAL -The ${name.upper()} RAL model is constructed using the [regtool.py script](../../../../util/doc/rm/RegisterTool.md) and is placed at `env/${name}_reg_block.sv`. +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`. ${'###'} Reference models [Describe reference models in use if applicable, example: SHA256/HMAC] @@ -125,5 +122,4 @@ ``` ${'##'} Testplan -<!-- TODO: uncomment the line below after adding the testplan --> -<!-- {{% insert_testplan x }} --> +{{% insert_testplan x }}
diff --git a/util/uvmdvgen/env_cov.sv.tpl b/util/uvmdvgen/env_cov.sv.tpl index c07b312..18cd77c 100644 --- a/util/uvmdvgen/env_cov.sv.tpl +++ b/util/uvmdvgen/env_cov.sv.tpl
@@ -2,6 +2,12 @@ // Licensed under the Apache License, Version 2.0, see LICENSE for details. // SPDX-License-Identifier: Apache-2.0 +/** + * Covergoups that are dependent on run-time parameters that may be available + * only in build_phase can be defined here + * Covergroups may also be wrapped inside helper classes if needed. + */ + % if is_cip: class ${name}_env_cov extends cip_base_env_cov #(.CFG_T(${name}_env_cfg)); % else: @@ -13,10 +19,20 @@ // ${name}_env_cfg: cfg // covergroups + // [add covergroups here] function new(string name, uvm_component parent); super.new(name, parent); - // instantiate all covergroups here + // [instantiate covergroups here] endfunction : new + virtual function void build_phase(uvm_phase phase); + super.build_phase(phase); + // [or instantiate covergroups here] +% if is_cip: + // Please instantiate sticky_intr_cov array of objects for all interrupts that are sticky + // See cip_base_env_cov for details +% endif + endfunction + endclass
diff --git a/util/uvmdvgen/gen_env.py b/util/uvmdvgen/gen_env.py index cc998cc..ebd6a07 100644 --- a/util/uvmdvgen/gen_env.py +++ b/util/uvmdvgen/gen_env.py
@@ -13,27 +13,27 @@ def gen_env(name, is_cip, has_interrupts, has_alerts, env_agents, root_dir): # yapf: disable # 4-tuple - sub-path, ip name, class name, file ext - env_srcs = [('env', name + '_', 'env_cfg', '.sv'), - ('env', name + '_', 'env_cov', '.sv'), - ('env', name + '_', 'env_pkg', '.sv'), - ('env', name + '_', 'reg_block', '.sv'), - ('env', name + '_', 'scoreboard', '.sv'), - ('env', name + '_', 'virtual_sequencer', '.sv'), - ('env', name + '_', 'env', '.sv'), - ('env', name + '_', 'env', '.core'), - ('env/seq_lib', name + '_', 'base_vseq', '.sv'), - ('env/seq_lib', name + '_', 'sanity_vseq', '.sv'), - ('env/seq_lib', name + '_', 'common_vseq', '.sv'), - ('env/seq_lib', name + '_', 'vseq_list', '.sv'), - ('tb', '', 'tb', '.sv'), - ('tb', name + '_', 'bind', '.sv'), - ('tests', name + '_', 'base_test', '.sv'), - ('tests', name + '_', 'test_pkg', '.sv'), - ('tests', name + '_', 'test', '.core'), - ('.', '', 'Makefile', ''), - ('.', name + '_', 'dv_plan', '.md'), - ('.', name + '_', 'testplan', '.hjson'), - ('.', name + '_', 'sim', '.core')] + env_srcs = [('dv/env', name + '_', 'env_cfg', '.sv'), + ('dv/env', name + '_', 'env_cov', '.sv'), + ('dv/env', name + '_', 'env_pkg', '.sv'), + ('dv/env', name + '_', 'reg_block', '.sv'), + ('dv/env', name + '_', 'scoreboard', '.sv'), + ('dv/env', name + '_', 'virtual_sequencer', '.sv'), + ('dv/env', name + '_', 'env', '.sv'), + ('dv/env', name + '_', 'env', '.core'), + ('dv/env/seq_lib', name + '_', 'base_vseq', '.sv'), + ('dv/env/seq_lib', name + '_', 'sanity_vseq', '.sv'), + ('dv/env/seq_lib', name + '_', 'common_vseq', '.sv'), + ('dv/env/seq_lib', name + '_', 'vseq_list', '.sv'), + ('dv/tb', '', 'tb', '.sv'), + ('dv/tb', name + '_', 'bind', '.sv'), + ('dv/tests', name + '_', 'base_test', '.sv'), + ('dv/tests', name + '_', 'test_pkg', '.sv'), + ('dv/tests', name + '_', 'test', '.core'), + ('dv', '', 'Makefile', ''), + ('doc', name + '_', 'dv_plan', '.md'), + ('data', name + '_', 'testplan', '.hjson'), + ('dv', name + '_', 'sim', '.core')] # yapf: enable for tup in env_srcs: @@ -52,11 +52,10 @@ with open(path_dir + "/" + fname, 'w') as fout: try: fout.write( - tpl.render( - name=name, - is_cip=is_cip, - has_interrupts=has_interrupts, - has_alerts=has_alerts, - env_agents=env_agents)) + tpl.render(name=name, + is_cip=is_cip, + has_interrupts=has_interrupts, + has_alerts=has_alerts, + env_agents=env_agents)) except: log.error(exceptions.text_error_template().render())