From 4721da9658858c123af0fee14c4d29c20c4ca0dd Mon Sep 17 00:00:00 2001 From: Anjana Parthasarathy Date: Fri, 28 Jul 2023 10:33:23 -0700 Subject: [PATCH] Updated README.md with note about regression test list to run, and fixed step numbers --- README.md | 56 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index c222cff63..b16062cba 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
limitations under the License.*_
# **Caliptra Hands-On Guide** # -_*Last Update: 2023/07/26*_ +_*Last Update: 2023/07/28*_ ## **Tools Used** ## @@ -59,11 +59,11 @@ with the provided Makefile for compiling test C programs. 1. Install from this repository: - https://github.com/riscv-collab/riscv-gnu-toolchain - Follow the included README in that repository for installation instructions -1. The most recently tested toolchain build that was confirmed to work was 2023-04-29 +2. The most recently tested toolchain build that was confirmed to work was 2023-04-29 - https://github.com/riscv-collab/riscv-gnu-toolchain/releases/tag/2023.04.29 -1. A compatible tool installation requires newlib cross-compiler, multilib support, and the zicsr/zifencei extensions. Use this configure command: +3. A compatible tool installation requires newlib cross-compiler, multilib support, and the zicsr/zifencei extensions. Use this configure command: - `./configure --enable-multilib --prefix=/path/to/tools/riscv-gnu/2023.04.29 --with-multilib-generator="rv32imc-ilp32--a*zicsr*zifencei"` -1. Use `make` instead of `make linux` to install the tool (using newlib option) +4. Use `make` instead of `make linux` to install the tool (using newlib option) ## **ENVIRONMENT VARIABLES** ## Required for simulation:
@@ -138,35 +138,35 @@ The "Integration" sub-component contains the top-level fileset for Caliptra. `sr ### VCS Steps: ### 1. Setup tools, add to PATH (ensure riscv64-unknown-elf-gcc is also available) -1. Define all environment variables above +2. Define all environment variables above - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME -1. Create a run folder for build outputs (and cd to it) -1. [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. -1. 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}` +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` -1. 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. -1. Simulate project with `caliptra_top_tb` as the top target +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) -1. Define all environment variables above +2. Define all environment variables above - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME -1. Create a run folder for build outputs +3. Create a run folder for build outputs - Recommended to place run folder under `${CALIPTRA_WORKSPACE}/scratch/$USER/verilator/` -1. [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. -1. Run Caliptra/tools/scripts/Makefile, which provides steps to run a top-level simulation in Verilator +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. Run Caliptra/tools/scripts/Makefile, which provides steps to run a top-level simulation in Verilator - Example command: `make -C -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=${TESTNAME} debug=1 verilator` - NOTE: `debug=1` is optional; if provided, the verilator run will produce a .vcd file with waveform information - NOTE: `TESTNAME=${TESTNAME}` is optional; if not provided, test defaults to value of TESTNAME environment variable, then to `iccm_lock` - NOTE: Users may wish to produce a run log by piping the make command to a tee command, e.g.: `make ... ... | tee /verilate.log` -1. Users have the option to run the entire suite of smoke tests using the provided python script `run_verilator_l0_regression.py` +6. Users have the option to run the entire suite of smoke tests using the provided python script `run_verilator_l0_regression.py` 1. Ensure Python 3.9.2 is available by adding to the $PATH variable - 1. Run the script with: + 2. Run the script with: `python3 run_verilator_l0_regression.py` - 1. NOTE: The script automatically creates run output folders at `${CALIPTRA_WORKSPACE}/scratch/$USER/verilator//` for each test run - 1. NOTE: The output folder is populated with a run log that reports the run results and pass/fail status + 3. NOTE: The script automatically creates run output folders at `${CALIPTRA_WORKSPACE}/scratch/$USER/verilator//` for each test run + 4. NOTE: The output folder is populated with a run log that reports the run results and pass/fail status ### UVM Testbench Steps for `caliptra_top`:
@@ -179,16 +179,18 @@ The UVM Framework generation tool was used to create the baseline UVM testbench Steps:
1. Compile UVM 1.1d library -1. Compile the AHB/APB QVIP source -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. 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=` argument to simulation +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=` argument to simulation +## **Regression Tests** ## + +Only tests from teh L0 Regression List should be run. ## **NOTES** ## -* The internal registers are auto rendered at the [GitHub - page](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs) +* The internal registers are auto rendered at the [GitHub page](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs) * So are the [external registers](https://chipsalliance.github.io/caliptra-rtl/main/external-regs)