[acrc, dv] Autogen DV Darjeeling AC Range Check IP

- Run the command:
util/ipgen.py generate \
-C hw/ip_templates/ac_range_check \
-o hw/top_darjeeling/ip_autogen/ac_range_check \
-c hw/top_darjeeling/ip_autogen/ac_range_check/data/\
top_darjeeling_ac_range_check.ipconfig.hjson -f

Signed-off-by: Martin Velay <[email protected]>

Author: martin-velay

hw/top_darjeeling/ip_autogen/ac_range_check/doc/checklist.md

@@ -0,0 +1,129 @@
+# AC_RANGE_CHECK DV document
+
+## Goals
+* **DV**
+  * Verify all AC_RANGE_CHECK IP features by running dynamic simulations with a SV/UVM based testbench
+  * Develop and run all tests based on the [testplan](#testplan) below towards closing code and functional coverage on the IP and all of its sub-modules
+* **FPV**
+  * Verify TileLink device protocol compliance with an SVA based testbench
+
+## Current status
+* [Design & verification stage](../../../../README.md)
+  * [HW development stages](../../../../../doc/project_governance/development_stages.md)
+* [Simulation results](https://reports.opentitan.org/hw/top_darjeeling/ip_autogen/ac_range_check/dv/latest/report.html)
+
+## Design features
+For detailed information on `ac_range_check` design features, please see the [`ac_range_check` HWIP technical specification](../README.md).
+
+## Testbench architecture
+The `ac_range_check` UVM DV testbench has been constructed based on the [CIP testbench architecture](../../../../dv/sv/cip_lib/README.md).
+
+### Block diagram
+![Block diagram](./doc/tb.svg)
+
+### Top level testbench
+Top level testbench is located at `hw/top_darjeeling/ip_autogen/ac_range_check/dv/tb/tb.sv`.
+It instantiates the `ac_range_check` DUT module `hw/ip/ac_range_check/rtl/ac_range_check.sv`.
+In addition, the testbench 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)
+* [Reset shadowed interface](../../../../dv/sv/common_ifs/README.md)  // TODO add something in this doc about this interface.
+* [TileLink host interface for the CSRs](../../../../dv/sv/tl_agent/README.md)
+* [TileLink host interface for the Unfiltered CTN accesses](../../../../dv/sv/tl_agent/README.md)
+* [TileLink device interface for the Filtered CTN accesses](../../../../dv/sv/tl_agent/README.md)
+* Interrupts ([`pins_if`](../../../../dv/sv/common_ifs/README.md))
+* Alerts ([`alert_esc_if`](../../../../dv/sv/alert_esc_agent/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)
+
+### Compile-time configurations
+[list compile time configurations, if any and what are they used for]
+
+### Global types & methods
+All common types and methods defined at the package level can be found in `ac_range_check_env_pkg`.
+Some of them in use are:
+```systemverilog
+[list a few parameters, types & methods; no need to mention all]
+```
+
+### TL_agent
+* `ac_range_check` UVM environment instantiates a (already handled in CIP base env) [tl_agent](../../../../dv/sv/tl_agent/README.md) which provides the ability to drive and independently monitor random traffic via TL host interface into `ac_range_check` device, to access to the CSRs (Control/Status Registers).
+* Host interface to the Unfiltered CTN accesses.
+* Device interface to the Filtered CTN accesses.
+
+The `tl_agent` monitor supplies partial TileLink request packets as well as completed TileLink response packets over the TLM analysis port for further processing within the `ac_range_check` scoreboard.
+
+### Alert_agent
+`ac_range_check` testbench instantiates (already handled in CIP base env) [alert_agents](../../../../dv/sv/alert_esc_agent/README.md):
+[list alert names].
+The alert_agents provide the ability to drive and independently monitor alert handshakes via alert interfaces in AC_RANGE_CHECK device.
+
+### UVM RAL Model
+The `ac_range_check` RAL model is created with the [`ralgen`](../../../../dv/tools/ralgen/README.md) FuseSoC generator script automatically when the simulation is at the build stage.
+
+It can be created manually by invoking [`regtool`](../../../../../util/reggen/doc/setup_and_use.md):
+
+#### Sequence cfg
+An efficient way to develop test sequences is by providing some random variables that are used to configure the DUT / drive stimulus.
+The random variables are constrained using weights and knobs that can be controlled.
+These weights and knobs take on a "default" value that will result in the widest exploration of the design state space, when the test sequence is randomized and run as-is.
+To steer the randomization towards a particular distribution or to achieve interesting combinations of the random variables, the test sequence can be extended to create a specialized variant.
+In this extended sequence, nothing would need to be done, other than setting those weights and knobs appropriately.
+This helps increase the likelihood of hitting the design corners that would otherwise be difficult to achieve, while maximizing reuse.
+
+This object aims to provide such run-time controls.
+
+#### Env cfg
+The `ac_range_check_env_cfg`, environment configuration object provides access to the following elements:
+* Build-time controls to configure the UVM environment composition during the `build_phase`
+* Downstream agent configuration objects for ease of lookup from any environment component
+  * This includes the `tl_agent_cfg` objects for both TL interfaces
+* All virtual interfaces that connect to the DUT listed above (retrieved from the `uvm_config_db`)
+* Sequence configuration object described above
+
+All environment components contain a handle to an instance of this class (that was created in the test class via the parent `dv_base_test`).
+By housing all of the above, all pertinent information is more easily shared with all environment components.
+
+### Stimulus strategy
+#### Test sequences
+All test sequences reside in `hw/top_darjeeling/ip_autogen/ac_range_check/dv/env/seq_lib`.
+The `ac_range_check_base_vseq` virtual sequence is extended from `cip_base_vseq` and serves as a starting point.
+All test sequences are extended from `ac_range_check_base_vseq`.
+It provides commonly used handles, variables, functions and tasks that the test sequences can simple use / call.
+Some of the most commonly used tasks / functions are as follows: From `hw/top_darjeeling/ip_autogen/ac_range_check/dv/env/seq/ac_range_check_base_vseq.sv`,
+* task 1:
+* task 2:
+
+#### Functional coverage
+To ensure high quality constrained random stimulus, it is necessary to develop a functional coverage model.
+The following covergroups have been developed to prove that the test intent has been adequately met:
+* cg1:
+* cg2:
+
+### Self-checking strategy
+#### Scoreboard
+It creates the following analysis ports to retrieve the data monitored by corresponding interface agents:
+* analysis port1:
+* analysis port2:
+<!-- explain inputs monitored, flow of data and outputs checked -->
+
+#### Assertions
+* TLUL assertions: The `hw/top_darjeeling/ip_autogen/ac_range_check/dv/sva/ac_range_check_bind.sv` binds the `tlul_assert` [assertions](../../../../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](../../../../../util/dvsim/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 smoke test:
+```console
+$ cd $REPO_TOP
+$ ./util/dvsim/dvsim.py hw/top_darjeeling/ip_autogen/ac_range_check/dv/ac_range_check_sim_cfg.hjson -i ac_range_check_smoke
+```
+
+## Testplan
+[Testplan](../data/ac_range_check_testplan.hjson)

hw/top_darjeeling/ip_autogen/ac_range_check/dv/README.md

@@ -0,0 +1,32 @@
+CAPI=2:
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+name: lowrisc:opentitan:top_darjeeling_ac_range_check_sim:0.1
+description: "AC_RANGE_CHECK DV sim target"
+filesets:
+  files_rtl:
+    depend:
+      - lowrisc:ip:tlul
+      - lowrisc:opentitan:top_darjeeling_ac_range_check:0.1
+    file_type: systemVerilogSource
+
+  files_dv:
+    depend:
+      - lowrisc:opentitan:top_darjeeling_ac_range_check_test
+      - lowrisc:opentitan:top_darjeeling_ac_range_check_sva
+      - lowrisc:opentitan:top_darjeeling_ac_range_check_cov
+    files:
+      - tb/tb.sv
+    file_type: systemVerilogSource
+
+targets:
+  sim: &sim_target
+    toplevel: tb
+    filesets:
+      - files_rtl
+      - files_dv
+    default_tool: xcelium
+
+  lint:
+    <<: *sim_target

hw/top_darjeeling/ip_autogen/ac_range_check/dv/ac_range_check_sim.core

@@ -0,0 +1,63 @@
+// Copyright lowRISC contributors (OpenTitan project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+{
+  // Name of the sim cfg - typically same as the name of the DUT.
+  name: ac_range_check
+
+  // Top level dut name (sv module).
+  dut: ac_range_check
+
+  // Top level testbench name (sv module).
+  tb: tb
+
+  // Simulator used to sign off this block
+  tool: xcelium
+
+  // Fusesoc core file used for building the file list.
+  fusesoc_core: lowrisc:opentitan:top_darjeeling_ac_range_check_sim:0.1
+
+  // Testplan hjson file.
+  testplan: "{self_dir}/../data/ac_range_check_testplan.hjson"
+
+  // Import additional common sim cfg files.
+  import_cfgs: [// Project wide common sim cfg file
+                "{proj_root}/hw/dv/tools/dvsim/common_sim_cfg.hjson",
+                // Common CIP test lists
+                "{proj_root}/hw/dv/tools/dvsim/tests/csr_tests.hjson",
+                "{proj_root}/hw/dv/tools/dvsim/tests/mem_tests.hjson",  // TODO MVy needed?
+                "{proj_root}/hw/dv/tools/dvsim/tests/intr_test.hjson",
+                "{proj_root}/hw/dv/tools/dvsim/tests/alert_test.hjson",
+                "{proj_root}/hw/dv/tools/dvsim/tests/shadow_reg_errors_tests.hjson",
+                "{proj_root}/hw/dv/tools/dvsim/tests/tl_access_tests.hjson",
+                "{proj_root}/hw/dv/tools/dvsim/tests/sec_cm_tests.hjson", // TODO MVy needed?
+                "{proj_root}/hw/dv/tools/dvsim/tests/stress_tests.hjson"]
+
+  // Add additional tops for simulation.
+  sim_tops: ["ac_range_check_bind"]
+
+  // Default iterations for all tests - each test entry can override this.
+  reseed: 50
+
+  // Default UVM test and seq class name.
+  uvm_test: ac_range_check_base_test
+  uvm_test_seq: ac_range_check_base_vseq
+
+  // List of test specifications.
+  tests: [
+    {
+      name: ac_range_check_smoke
+      uvm_test_seq: ac_range_check_smoke_vseq
+    }
+
+    // TODO: add more tests here
+  ]
+
+  // List of regressions.
+  regressions: [
+    {
+      name: smoke
+      tests: ["ac_range_check_smoke"]
+    }
+  ]
+}

hw/top_darjeeling/ip_autogen/ac_range_check/dv/ac_range_check_sim_cfg.hjson

@@ -0,0 +1,40 @@
+CAPI=2:
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+name: "lowrisc:dv:ac_range_check_env:0.1"
+description: "AC_RANGE_CHECK DV UVM environment"
+filesets:
+  files_dv:
+    depend:
+      - lowrisc:dv:ralgen
+      - lowrisc:dv:cip_lib
+      - lowrisc:dv:tl_agent
+      - lowrisc:dv:dv_base_reg
+    files:
+      - ac_range_check_env_pkg.sv
+      - ac_range_check_ral_pkg.sv
+      - ac_range_check_env_cfg.sv: {is_include_file: true}
+      - ac_range_check_env_cov.sv: {is_include_file: true}
+      - ac_range_check_virtual_sequencer.sv: {is_include_file: true}
+      - ac_range_check_scoreboard.sv: {is_include_file: true}
+      - ac_range_check_env.sv: {is_include_file: true}
+      - seq_lib/ac_range_check_vseq_list.sv: {is_include_file: true}
+      - seq_lib/ac_range_check_base_vseq.sv: {is_include_file: true}
+      - seq_lib/ac_range_check_common_vseq.sv: {is_include_file: true}
+      - seq_lib/ac_range_check_smoke_vseq.sv: {is_include_file: true}
+    file_type: systemVerilogSource
+
+generate:
+  ral:
+    generator: ralgen
+    parameters:
+      name: ac_range_check
+      ip_hjson: ../../data/ac_range_check.hjson
+
+targets:
+  default:
+    filesets:
+      - files_dv
+    generate:
+      - ral

hw/top_darjeeling/ip_autogen/ac_range_check/dv/env/ac_range_check_env.core

@@ -0,0 +1,63 @@
+// Copyright lowRISC contributors (OpenTitan project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+class ac_range_check_env extends cip_base_env #(
+    .CFG_T              (ac_range_check_env_cfg),
+    .COV_T              (ac_range_check_env_cov),
+    .VIRTUAL_SEQUENCER_T(ac_range_check_virtual_sequencer),
+    .SCOREBOARD_T       (ac_range_check_scoreboard)
+  );
+  `uvm_component_utils(ac_range_check_env)
+
+  tl_agent tl_csr_agt;
+  tl_agent tl_unfilt_agt;
+  tl_agent tl_filt_agt;
+
+  // Standard SV/UVM methods
+  extern function new(string name="", uvm_component parent=null);
+  extern function void build_phase(uvm_phase phase);
+  extern function void connect_phase(uvm_phase phase);
+endclass : ac_range_check_env
+
+
+function ac_range_check_env::new(string name="", uvm_component parent=null);
+  super.new(name, parent);
+endfunction : new
+
+function void ac_range_check_env::build_phase(uvm_phase phase);
+  super.build_phase(phase);
+
+  // Create CSR TL agent
+  tl_csr_agt = tl_agent::type_id::create("tl_csr_agt", this);
+  uvm_config_db#(tl_agent_cfg)::set(this, "tl_csr_agt*", "cfg", cfg.tl_csr_agt_cfg);
+  cfg.tl_csr_agt_cfg.en_cov = cfg.en_cov;
+
+  // Create Unfiltered TL agent
+  tl_unfilt_agt = tl_agent::type_id::create("tl_unfilt_agt", this);
+  uvm_config_db#(tl_agent_cfg)::set(this, "tl_unfilt_agt*", "cfg", cfg.tl_unfilt_agt_cfg);
+  cfg.tl_unfilt_agt_cfg.en_cov = cfg.en_cov;
+
+  // Create Fltered TL agent
+  tl_filt_agt = tl_agent::type_id::create("tl_filt_agt", this);
+  uvm_config_db#(tl_agent_cfg)::set(this, "tl_filt_agt*", "cfg", cfg.tl_filt_agt_cfg);
+  cfg.tl_filt_agt_cfg.en_cov = cfg.en_cov;
+endfunction : build_phase
+
+function void ac_range_check_env::connect_phase(uvm_phase phase);
+  super.connect_phase(phase);
+  if (cfg.en_scb) begin
+    tl_csr_agt.monitor.analysis_port.connect(scoreboard.tl_csr_fifo.analysis_export);
+    tl_unfilt_agt.monitor.analysis_port.connect(scoreboard.tl_unfilt_fifo.analysis_export);
+    tl_filt_agt.monitor.analysis_port.connect(scoreboard.tl_filt_fifo.analysis_export);
+  end
+  if (cfg.is_active && cfg.tl_csr_agt_cfg.is_active) begin
+    virtual_sequencer.tl_csr_sqr = tl_csr_agt.sequencer;
+  end
+  if (cfg.is_active && cfg.tl_unfilt_agt_cfg.is_active) begin
+    virtual_sequencer.tl_unfilt_sqr = tl_unfilt_agt.sequencer;
+  end
+  if (cfg.is_active && cfg.tl_filt_agt_cfg.is_active) begin
+    virtual_sequencer.tl_filt_sqr = tl_filt_agt.sequencer;
+  end
+endfunction : connect_phase

hw/top_darjeeling/ip_autogen/ac_range_check/dv/env/ac_range_check_env.sv

@@ -0,0 +1,47 @@
+// Copyright lowRISC contributors (OpenTitan project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+class ac_range_check_env_cfg extends cip_base_env_cfg #(.RAL_T(ac_range_check_reg_block));
+
+  // External component config objects
+  rand tl_agent_cfg tl_csr_agt_cfg;
+  rand tl_agent_cfg tl_unfilt_agt_cfg;
+  rand tl_agent_cfg tl_filt_agt_cfg;
+
+  `uvm_object_utils_begin(ac_range_check_env_cfg)
+    `uvm_field_object(tl_csr_agt_cfg, UVM_DEFAULT)
+    `uvm_field_object(tl_unfilt_agt_cfg, UVM_DEFAULT)
+    `uvm_field_object(tl_filt_agt_cfg, UVM_DEFAULT)
+  `uvm_object_utils_end
+
+  // Standard SV/UVM methods
+  extern function new(string name="");
+
+  // Class specific methods
+  extern function void initialize(bit [31:0] csr_base_addr = '1);
+endclass : ac_range_check_env_cfg
+
+
+function ac_range_check_env_cfg::new(string name="");
+  super.new(name);
+endfunction : new
+
+function void ac_range_check_env_cfg::initialize(bit [31:0] csr_base_addr = '1);
+  list_of_alerts = ac_range_check_env_pkg::LIST_OF_ALERTS;
+  super.initialize(csr_base_addr);
+  // Create tl_csr agent config obj
+  tl_csr_agt_cfg = tl_agent_cfg::type_id::create("tl_csr_agt_cfg");
+  // Create tl_unfilt agent config obj
+  tl_unfilt_agt_cfg = tl_agent_cfg::type_id::create("tl_unfilt_agt_cfg");
+  // Create tl_filt agent config obj
+  tl_filt_agt_cfg = tl_agent_cfg::type_id::create("tl_filt_agt_cfg");
+
+  // Set num_interrupts
+  begin
+    uvm_reg rg = ral.get_reg_by_name("intr_state");
+    if (rg != null) begin
+      num_interrupts = ral.intr_state.get_n_used_bits();
+    end
+  end
+endfunction : initialize