Reintegrate main -> dev-goog

.github/workflows/interactive-debugging.yml

@@ -315,3 +315,19 @@ jobs:
           ${CALIPTRA_ROOT}/.github/scripts/openocd_test.sh \
             -f board/caliptra-verilator-rst.cfg \
             -f ${CALIPTRA_ROOT}/src/integration/test_suites/infinite_loop/peripheral_access.tcl
+
+      - name: Build Verilated simulation
+        run: |
+          export CALIPTRA_ROOT=$(pwd)
+          rm -rf run/*
+          make -C run -f ${CALIPTRA_ROOT}/tools/scripts/Makefile verilator-build TESTNAME=infinite_loop DEBUG_UNLOCKED=1 \
+            OBJCACHE="" CC=gcc CXX=g++ LINK=g++
+          make -C run -f ${CALIPTRA_ROOT}/tools/scripts/Makefile program.hex TESTNAME=infinite_loop
+
+      - name: Test JTAG access with clock gating
+        run: |
+          export CALIPTRA_ROOT=$(pwd)
+          cd run
+          ${CALIPTRA_ROOT}/.github/scripts/openocd_test.sh \
+            -f board/caliptra-verilator.cfg \
+            -f ${CALIPTRA_ROOT}/src/integration/test_suites/infinite_loop/jtag_cg.tcl

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,10 +37,12 @@ Simulation:
    - `Version 2021.2.1` of AHB/APB models
  - UVM installation
    - `Version 1.1d`
+ - Mentor Graphics UVM-Frameworks
+   - `2022.3`
 
 Synthesis:
- - Synopsys DC
-   - `Version 2020.09-SP1`
+ - Synopsys Fusion Compiler
+   - `Version 2022.12-SP3`
 
 GCC:
  - RISCV Toolchain for generating memory initialization files
@@ -53,7 +55,7 @@ Other:
  - Playbook (Microsoft Internal workflow management tool)
 
 ### **RISCV Toolchain installation** ###
-Note that there is significant configurability when installing the RISCV toolchain.
+There is significant configurability when installing the RISCV toolchain.
 These instructions may be used to create a RISCV installation that will be compatible
 with the provided Makefile for compiling test C programs.
 
@@ -72,7 +74,7 @@ Required for simulation:<BR>
 `CALIPTRA_ROOT`: Defines the absolute path to the Project repository root (called "Caliptra" or "caliptra-rtl"). Recommended to define as `${CALIPTRA_WORKSPACE}/Caliptra`.<BR>
 
 Required for Firmware (i.e. Test suites) makefile:<BR>
-  `TESTNAME`: Contains the name of one of the tests listed inside the `src/integration/test_suites` folder<BR>
+  `TESTNAME`: Contains the name of one of the tests listed inside the `src/integration/test_suites` folder; only used for `caliptra_top_tb` tests<BR>
 
 ## **Repository Overview** ##
 ```
@@ -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>
@@ -138,21 +143,32 @@ The "Integration" sub-component contains the top-level fileset for Caliptra. `sr
 
 ## **Simulation Flow** ##
 
-### VCS Steps: ###
+### Caliptra Top VCS Steps: ###
 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.
+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](src/integration/test_suites/iccm_lock) test). To do this, copy [iccm_lock.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) to the run directory and rename to `program.hex`. [dccm.hex](src/integration/test_suites/iccm_lock/iccm_lock.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
+7. Copy the test generator scripts to the run output directory:
+    - [src/ecc/tb/ecdsa_secp384r1.exe](src/ecc/tb/ecdsa_secp384r1.exe)
+        * Necessary for [randomized_pcr_signing](src/integration/test_suites/randomized_pcr_signing)
+        * OPTIONAL otherwise
+    - [src/doe/tb/doe_test_gen.py](src/doe/tb/doe_test_gen.py)
+        * Allows use of randomized secret field inputs during testing.
+        * Required when using the `+RAND_DOE_VALUES` plusarg during simulation
+        * Also required for several smoke tests that require randomized DOE IV, such as smoke_test_doe_scan, smoke_test_doe_rand, smoke_test_doe_cg
+8. Simulate project with `caliptra_top_tb` as the top target
 
-### Verilator Steps: ###
+### Caliptra Top 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.
@@ -170,6 +186,18 @@ The "Integration" sub-component contains the top-level fileset for Caliptra. `sr
     3. NOTE: The script automatically creates run output folders at `${CALIPTRA_WORKSPACE}/scratch/$USER/verilator/<timestamp>/<testname>` for each test run
     4. NOTE: The output folder is populated with a run log that reports the run results and pass/fail status
 
+### Unit Test VCS Steps: ###
+1. Setup tools, add to PATH
+1. Define all environment variables above
+1. Create a run folder for build outputs (and cd to it)
+1. Compile complete project using `src/<block>/config/<name>_tb.vf` as a compilation target in VCS. When running the `vcs` command to generate simv, users should ensure that `<name>_tb` is explicitly specified as the top-level component in their command to ensure this is the sole "top" that gets simulated.
+1. Copy the test generator scripts or test vectors to the run output directory:
+    - [src/ecc/tb/test_vectors/mm_test_vectors\*.hex](src/ecc/tb/test_vectors)
+        * Necessary for [ecc_montgomerymultiplier_tb](src/ecc/tb/ecc_montgomerymultiplier_tb.sv)
+    - [src/sha256/tb/sha256_test_gen.py](src/sha256/tb/sha256_test_gen.py)
+        * Necessary for [sha256_random_test](src/sha256/tb/sha256_random_test.sv)
+1. Simulate project with `<name>_tb` as the top target
+
 ### UVM Testbench Steps for `caliptra_top`: <BR>
 
 **Description**:<BR>
@@ -178,20 +206,77 @@ 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. ALL compilation steps may be completed by using the file-list found at `src/integration/uvmf_caliptra_top/config/uvmf_caliptra_top.vf`
+1. NOTE: `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. Copy the test vectors to the run output directory:
+    - [src/sha512/tb/vectors/SHA\*.rsp](src/sha512/tb/vectors/)
+        * Required for SHA512 UVM unittest
+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
+
+### UVM Unit Test Steps: <BR>
+
+**Description**:<BR>
+The UVM Framework generation tool was used to create the baseline UVM testbench for verification of each IP component inside Caliptra. The following IP blocks have supported UVM testbenches:
+- [ECC](src/ecc/uvmf_ecc)
+- [HMAC](src/hmac/uvmf_2022)
+- [SHA512](src/sha512/uvmf_sha512)
+- [KeyVault](src/keyvault/uvmf_kv)
+- [PCRVault](src/pcrvault/uvmf_pv)
+- [SOC_IFC](src/soc_ifc/uvmf_soc_ifc)
+
+**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
+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 the target testbench
+1. ALL compilation steps may be completed by using the file-list found at `src/<block>/uvmf_<name>/config/<name>.vf`
+1. NOTE: `Caliptra/src/<block>/uvmf_<name>/uvmf_template_output/project_benches/<block>/tb/testbench/hdl_top.sv` is the top-level TB wrapper for the system
+1. Copy the test generator scripts to the run output directory:
+    - [src/ecc/tb/ecdsa_secp384r1.exe](src/ecc/tb/ecdsa_secp384r1.exe)
+        * Necessary for ECC unittest
+    - [src/hmac/tb/test_gen.py](src/hmac/tb/test_gen.py)
+        * Required for uvmf_hmac unittest
+    - [src/sha512/tb/vectors/SHA\*.rsp](src/sha512/tb/vectors/)
+        * Required for SHA512 UVM unittest
+1. Select a test to run from the set of tests in `Caliptra/src/<block>/uvmf_<name>/uvmf_template_output/project_benches/<block>/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)

Release_Notes.md

@@ -14,11 +14,11 @@ See the License for the specific language governing permissions and<BR>
 limitations under the License.*_<BR>
 
 # **Release Notes** #
-_*Last Update: 2023/09/13*_
+_*Last Update: 2023/11/02*_
 
-## Rev 1p0 ##
+## Rev 1p0-rc1 ##
 
-### Rev 1p0 release date: (pending ROM release for official declaration) ###
+### Rev 1p0-rc1 release date: 2023/11/03 (1p0 version pending ROM release for official declaration) ###
 - Caliptra IP Specification: see docs/ folder
 - Caliptra Integration Specification: see docs/ folder
 - Caliptra testplan: see docs/ folder

SECURITY.md

@@ -0,0 +1,3 @@
+# Caliptra Project Security Incident Response
+
+Please refer to the security policy at [Caliptra security policy](https://github.com/chipsalliance/caliptra/security/policy).