Merge dev-integrate -> main

README.md

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and<BR>
 limitations under the License.*_<BR>
 
 # **Caliptra Hands-On Guide** #
-_*Last Update: 2023/09/06*_
+_*Last Update: 2023/10/17*_
 
 
 ## **Tools Used** ##
@@ -37,6 +37,8 @@ Simulation:
    - `Version 2021.2.1` of AHB/APB models
  - UVM installation
    - `Version 1.1d`
+ - Mentor Graphics UVM-Frameworks
+   - `2022.3`
 
 Synthesis:
  - Synopsys DC
@@ -121,6 +123,9 @@ VF files provide absolute filepaths (prefixed by the `CALIPTRA_ROOT` environment
 The "Integration" sub-component contains the top-level fileset for Caliptra. `src/integration/config/compile.yml` defines the required filesets and sub-component dependencies for this build target. All of the files/dependencies are explicitly listed in `src/integration/config/caliptra_top_tb.vf`. Users may compile the entire design using only this VF filelist.<BR>
 
 
+## **Verilog File Lists** ##
+Verilog file lists are generated via VCS and included in the config directory for each unit. New files added to the design should be included in the vf list. They can be included manually or by using VCS to regenerate the vf file. File lists define the compilation sources (including all dependencies) required to build and simulate a given module or testbench, and should be used for simulation, lint, and synthesis.
+
 ## **Scripts Description** ##
 
 `demo.rdl`:Sample RDL file<BR>
@@ -142,17 +147,20 @@ The "Integration" sub-component contains the top-level fileset for Caliptra. `sr
 1. Setup tools, add to PATH (ensure riscv64-unknown-elf-gcc is also available)
 2. Define all environment variables above
     - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME
+    - See [Regression Tests](#Regression-Tests) for information about available tests.
 3. Create a run folder for build outputs (and cd to it)
 4. [OPTIONAL] By default, this run flow will use the riscv64 toolchain to compile test firmware (according to TESTNAME) into program.hex, iccm.hex, dccm.hex, and mailbox.hex. As a first pass, integrators may alternatively use the pre-built hexfiles for convenience (available for `iccm_lock` test). To do this, copy `iccm_lock.hex` to the run directory and rename to `program.hex`. `dccm.hex` should also be copied to the run directory, as-is. Use `touch iccm.hex mailbox.hex` to create empty hex files, as these are unnecessary for `iccm_lock` test.
 5. Invoke `${CALIPTRA_ROOT}/tools/scripts/Makefile` with target 'program.hex' to produce SRAM initialization files from the firmware found in `src/integration/test_suites/${TESTNAME}`
     - E.g.: `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile program.hex`
+    - NOTE: TESTNAME may also be overridden in the makefile command line invocation, e.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=iccm_lock program.hex`
 6. Compile complete project using `src/integration/config/caliptra_top_tb.vf` as a compilation target in VCS. When running the `vcs` command to generate simv, users should ensure that `caliptra_top_tb` is explicitly specified as the top-level component in their command to ensure this is the sole "top" that gets simulated.
 7. Simulate project with `caliptra_top_tb` as the top target
 
 ### Verilator Steps: ###
 1. Setup tools, add to PATH (ensure Verilator, GCC, and riscv64-unknown-elf-gcc are available)
 2. Define all environment variables above
     - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME
+    - See [Regression Tests](#Regression-Tests) for information about available tests.
 3. Create a run folder for build outputs
     - Recommended to place run folder under `${CALIPTRA_WORKSPACE}/scratch/$USER/verilator/<date>`
 4. [OPTIONAL] By default, this run flow will use the riscv64 toolchain to compile test firmware (according to TESTNAME) into program.hex, iccm.hex, dccm.hex, and mailbox.hex. As a first pass, integrators may alternatively use the pre-built hexfiles for convenience (available for `iccm_lock` test). To do this, copy `iccm_lock.hex` to the run directory and rename to `program.hex`. `dccm.hex` should also be copied to the run directory, as-is. Use `touch iccm.hex mailbox.hex` to create empty hex files, as these are unnecessary for `iccm_lock` test.
@@ -178,20 +186,38 @@ The UVM Framework generation tool was used to create the baseline UVM testbench
 **Prerequisites**:<BR>
 - QVIP 2021.2.1 for Mentor Graphics (provides the AHB/APB VIP)
 - UVM 1.1d installation
+- Mentor Graphics UVM-Framework installation
 
 Steps:<BR>
 1. Compile UVM 1.1d library
-2. Compile the AHB/APB QVIP source
-3. Compile the UVMF wrapper for APB/AHB in Caliptra/src/libs/uvmf
-4. Compile the `verification_ip` provided for `soc_ifc` found in `Caliptra/src/soc_ifc/uvmf_soc_ifc`
-5. Compile the `caliptra_top` testbench found in `Caliptra/src/integration/uvmf_caliptra_top`
-6. `Caliptra/src/integration/uvmf_caliptra_top/uvmf_template_output/project_benches/caliptra_top/tb/testbench/hdl_top.sv` is the top-level TB wrapper for the system
-7. Select a test to run from the set of tests in `Caliptra/src/integration/uvmf_caliptra_top/uvmf_template_output/project_benches/caliptra_top/tb/tests/src`
-8. Provide `+UVM_TESTNAME=<test>` argument to simulation
+1. Compile the AHB/APB QVIP source
+1. Compile the Mentor Graphics UVM-Frameworks base library
+1. Compile the UVMF wrapper for APB/AHB in Caliptra/src/libs/uvmf
+1. Compile the `verification_ip` provided for `soc_ifc` found in `Caliptra/src/soc_ifc/uvmf_soc_ifc`
+1. Compile the `caliptra_top` testbench found in `Caliptra/src/integration/uvmf_caliptra_top`
+1. `Caliptra/src/integration/uvmf_caliptra_top/uvmf_template_output/project_benches/caliptra_top/tb/testbench/hdl_top.sv` is the top-level TB wrapper for the system
+1. Compile the validation firmware (as described in [Regression Tests](#Regression-Tests)) that will run on Caliptra's embedded RISC-V core
+    - The expected output products are `program.hex`, `caliptra_fmc.hex`, `caliptra_rt.hex` and must be placed in the simulation run directory
+    - `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=caliptra_top program.hex`
+    - `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=caliptra_fmc caliptra_fmc.hex`
+    - `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=caliptra_rt  caliptra_rt.hex`
+1. Select a test to run from the set of tests in `Caliptra/src/integration/uvmf_caliptra_top/uvmf_template_output/project_benches/caliptra_top/tb/tests/src`
+1. Provide `+UVM_TESTNAME=<test>` argument to simulation
 
 ## **Regression Tests** ##
 
-Only tests from the L0 Regression List should be run. 
+### Standalone SystemVerilog Testbench Regression ###
+Only tests from the L0 Regression List should be run.
+The list is defined in the file [L0_regression.yml](https://github.com/chipsalliance/caliptra-rtl/blob/main/src/integration/stimulus/L0_regression.yml)
+
+### UVM Regression ###
+The UVM simulation environment for `caliptra_top` uses a special set of validation firmware to generate stimulus as required for the test plan. This firmware suite is found in `src/integration/test_suites` and includes:
+ - `caliptra_top`: A C-based program that emulates a minimal set of bringup functions similar to the function of the ROM. This C file transitions very early to either a the FMC image or Runtime image based on bringup (reset reason) conditions.
+ - `caliptra_fmc`: A C-based program that emulates the functionality of the First Mutable Code. In this reduced-functionality validation implementation, the FMC code is a simple intermediary that runs from ICCM and serves to boot the Runtime Firmware.
+ - `caliptra_rt`: A C-based program that emulates the functionality of the production Runtime code. This program receives and services interrupts, defines a minimal Non-Maskable Interrupt handler, generates FW resets as needed, processes mailbox commands (generated through the UVM validation test plan), and runs some baseline Watchdog Timer testing.
+
+These three programs are designed to be run within the context of a UVM simulation, and will fail to generate meaningful stimulus in the standalone `caliptra_top_tb` test.
+
 ## **NOTES** ##
 
 * The internal registers are auto rendered at the [GitHub page](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs)

src/caliptra_prim/rtl/caliptra_prim_assert.sv

@@ -49,8 +49,8 @@
 // Static assertions for checks inside SV packages. If the conditions is not true, this will
 // trigger an error during elaboration.
 `define CALIPTRA_ASSERT_STATIC_IN_PACKAGE(__name, __prop)              \
-  function automatic bit assert_static_in_package_``__name();          \
-    bit unused_bit [((__prop) ? 1 : -1)];                              \
+  function automatic logic assert_static_in_package_``__name();        \
+    logic unused_bit [((__prop) ? 1 : -1)];                            \
     unused_bit = '{default: 1'b0};                                     \
     return unused_bit[0];                                              \
   endfunction

src/csrng/rtl/csrng_reg_top.sv

@@ -1947,74 +1947,74 @@ module csrng_reg_top #(
   // Read data return
   always_comb begin
     reg_rdata_next = '0;
-    unique case (1'b1)
-      addr_hit[0]: begin
+    unique case (addr_hit)
+      17'h00001: begin
         reg_rdata_next[0] = intr_state_cs_cmd_req_done_qs;
         reg_rdata_next[1] = intr_state_cs_entropy_req_qs;
         reg_rdata_next[2] = intr_state_cs_hw_inst_exc_qs;
         reg_rdata_next[3] = intr_state_cs_fatal_err_qs;
       end
 
-      addr_hit[1]: begin
+      17'h00002: begin
         reg_rdata_next[0] = intr_enable_cs_cmd_req_done_qs;
         reg_rdata_next[1] = intr_enable_cs_entropy_req_qs;
         reg_rdata_next[2] = intr_enable_cs_hw_inst_exc_qs;
         reg_rdata_next[3] = intr_enable_cs_fatal_err_qs;
       end
 
-      addr_hit[2]: begin
+      17'h00004: begin
         reg_rdata_next[0] = '0;
         reg_rdata_next[1] = '0;
         reg_rdata_next[2] = '0;
         reg_rdata_next[3] = '0;
       end
 
-      addr_hit[3]: begin
+      17'h00008: begin
         reg_rdata_next[0] = '0;
         reg_rdata_next[1] = '0;
       end
 
-      addr_hit[4]: begin
+      17'h00010: begin
         reg_rdata_next[0] = regwen_qs;
       end
 
-      addr_hit[5]: begin
+      17'h00020: begin
         reg_rdata_next[3:0] = ctrl_enable_qs;
         reg_rdata_next[7:4] = ctrl_sw_app_enable_qs;
         reg_rdata_next[11:8] = ctrl_read_int_state_qs;
       end
 
-      addr_hit[6]: begin
+      17'h00040: begin
         reg_rdata_next[31:0] = '0;
       end
 
-      addr_hit[7]: begin
+      17'h00080: begin
         reg_rdata_next[0] = sw_cmd_sts_cmd_rdy_qs;
         reg_rdata_next[1] = sw_cmd_sts_cmd_sts_qs;
       end
 
-      addr_hit[8]: begin
+      17'h00100: begin
         reg_rdata_next[0] = genbits_vld_genbits_vld_qs;
         reg_rdata_next[1] = genbits_vld_genbits_fips_qs;
       end
 
-      addr_hit[9]: begin
+      17'h00200: begin
         reg_rdata_next[31:0] = genbits_qs;
       end
 
-      addr_hit[10]: begin
+      17'h00400: begin
         reg_rdata_next[3:0] = int_state_num_qs;
       end
 
-      addr_hit[11]: begin
+      17'h00800: begin
         reg_rdata_next[31:0] = int_state_val_qs;
       end
 
-      addr_hit[12]: begin
+      17'h01000: begin
         reg_rdata_next[15:0] = hw_exc_sts_qs;
       end
 
-      addr_hit[13]: begin
+      17'h02000: begin
         reg_rdata_next[0] = recov_alert_sts_enable_field_alert_qs;
         reg_rdata_next[1] = recov_alert_sts_sw_app_enable_field_alert_qs;
         reg_rdata_next[2] = recov_alert_sts_read_int_state_field_alert_qs;
@@ -2023,7 +2023,7 @@ module csrng_reg_top #(
         reg_rdata_next[13] = recov_alert_sts_cs_main_sm_alert_qs;
       end
 
-      addr_hit[14]: begin
+      17'h04000: begin
         reg_rdata_next[0] = err_code_sfifo_cmd_err_qs;
         reg_rdata_next[1] = err_code_sfifo_genbits_err_qs;
         reg_rdata_next[2] = err_code_sfifo_cmdreq_err_qs;
@@ -2052,11 +2052,11 @@ module csrng_reg_top #(
         reg_rdata_next[30] = err_code_fifo_state_err_qs;
       end
 
-      addr_hit[15]: begin
+      17'h08000: begin
         reg_rdata_next[4:0] = err_code_test_qs;
       end
 
-      addr_hit[16]: begin
+      17'h10000: begin
         reg_rdata_next[7:0] = main_sm_state_qs;
       end
     endcase