SPDX-License-Identifier: Apache-2.0
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Last Update: 2024/09/20
:warning:$${\textsf{\color{red}DISCLAIMER:\ This\ repository\ is\ under\ active\ development\ towards\ a\ Gen2\ release\ on\ branch\ main.}}$$
$${\textsf{\color{red}Functionality\ or\ quality\ is\ not\ guaranteed.}}$$
$${\textsf{\color{red}Do\ not\ integrate\ this\ into\ a\ production\ design!}}$$
Prior official releases are available at: https://github.com/chipsalliance/caliptra-rtl/releases
Releases are published as a tag, and also contain downloadable assets (which should not be used).
Instead of downloading the assets attached to the published release, integrators should consume Caliptra releases by pulling code from the repository at the associated tag, due to https://github.com/chipsalliance/caliptra-rtl/issues/471.
OS:
Lint:
Version S-2021.09-1
Version 2019.A.p15 for RHEL 6.0-64, Rev 116515, Built On 12/18/2020
Simulation:
Version R-2020.12-SP2-7_Full64
Version 5.012
Version 2021.2.1
of AHB/APB modelsVersion 1.1d
2022.3
Synthesis:
Version 2022.12-SP3
GCC:
Version 2023.04.29
riscv64-unknown-elf-gcc (g) 12.2.0
g++ (GCC) 11.2.0
CDC:
2023.3 5624840 linux_x86_64 19-Jul-2023
RDC:
2019.A.P16
RDL Compiler:
Other:
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.
./configure --enable-multilib --prefix=/path/to/tools/riscv-gnu/2023.04.29 --with-multilib-generator="rv32imc-ilp32--a*zicsr*zifencei"
make
instead of make linux
to install the tool (using newlib option)Required for simulation:
CALIPTRA_WORKSPACE
: Defines the absolute path to the directory where the Verilator "scratch" output directory will be created. Recommended to define as the absolute path to the directory that contains the Project repository root (called "Caliptra" or "caliptra-rtl")
CALIPTRA_ROOT
: Defines the absolute path to the Project repository root (called "Caliptra" or "caliptra-rtl"). Recommended to define as ${CALIPTRA_WORKSPACE}/caliptra-rtl
.
Required for Firmware (i.e. Test suites) makefile:
TESTNAME
: Contains the name of one of the tests listed inside the src/integration/test_suites
folder; only used for caliptra_top_tb
tests
caliptra-rtl
|-- LICENSE
|-- README.md
|-- Release_Notes.md
|-- SECURITY.md
|-- docs
| |-- CaliptraHardwareSpecification.md
| |-- CaliptraIntegrationSpecification.md
| |-- CaliptraReleaseChecklist.md
| |-- Caliptra_TestPlan.xlsx
| `-- images
|-- src
| |-- aes
| |-- ahb_lite_bus
| |-- caliptra_prim
| |-- caliptra_prim_generic
| |-- csrng
| |-- datavault
| |-- doe
| |-- ecc
| |-- edn
| |-- entropy_src
| |-- hmac
| |-- hmac_drbg
| |-- integration
| |-- keyvault
| |-- kmac
| |-- lc_ctrl
| |-- libs
| |-- pcrvault
| |-- riscv_core
| |-- sha256
| |-- sha512
| |-- sha512_masked
| |-- soc_ifc
| |-- spi_host
| `-- uart
`-- tools
|-- README
|-- scripts
`-- templates
The root of the repository is structured as shown above, to a depth of 2 layers.
Each sub-component is accompanied by a file list summary (located in src/
VF files provide absolute filepaths (prefixed by the CALIPTRA_ROOT
environment variable) to each compile target for the associated component.
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.
Verilog file lists are generated via VCS and included in the config directory for each unit. New files added to the design must 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 by integrators for simulation, lint, and synthesis.
demo.rdl
:Sample RDL file
Makefile
: Makefile to generate SRAM initialization files from test firmware and to run Verilator simulation
reg_gen.py
: Used to compile/export RDL files to register source code
reg_gen.sh
: Wrapper used to call reg_gen.py
for all IP cores in Caliptra
reg_doc_gen.py
: Used to compile/export top-level RDL address map to register source code, defining complete Caliptra address space, and produces HTML documentation
reg_doc_gen.sh
: Wrapper to invoke reg_doc_gen.py
reg_json.py
:Used to import JSON register definition from OpenTitan and generate SystemRDL model
rdl_post_process.py
: Post-processing functionality to make RDL generated SystemVerilog files compatible with lint/Verilator requirements
run_verilator_l0_regression.py
: Wrapper to run the L0 smoke test regression suite using the Makefile flow in Verilator
integration_vector_gen.py
: Generates test vectors for crypto core tests
veer_build_command.sh
: Shell script used to generate the VeeR-EL2 repository present in src/riscv_core/veer_el2
openocd
: Open-Source FW debug utility used for JTAG testing in automated workflows
iccm_lock
is recommended for TESTNAMEmake -C <path/to/run/folder> -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=${TESTNAME} vcs
TESTNAME=${TESTNAME}
is optional; if not provided, test defaults to value of TESTNAME environment variable, then to iccm_lock
make ... <args> ... | tee <path/to/run/folder>/vcs.log
make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile CALIPTRA_INTERNAL_QSPI=0 CALIPTRA_INTERNAL_UART=0 CALIPTRA_INTERNAL_I3C=0 CALIPTRA_INTERNAL_TRNG=1 vcs
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.${CALIPTRA_ROOT}/tools/scripts/Makefile
with target 'program.hex' to produce SRAM initialization files from the firmware found in src/integration/test_suites/${TESTNAME}
make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile program.hex
make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=iccm_lock program.hex
make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile CALIPTRA_INTERNAL_QSPI=0 CALIPTRA_INTERNAL_UART=0 CALIPTRA_INTERNAL_I3C=0 CALIPTRA_INTERNAL_TRNG=1 program.hex
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.
+RAND_DOE_VALUES
plusarg during simulationcaliptra_top_tb
as the top targeticcm_lock
is recommended for TESTNAME${CALIPTRA_WORKSPACE}/scratch/$USER/verilator/<date>
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.make -C <path/to/run/folder> -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=${TESTNAME} debug=1 verilator
debug=1
is optional; if provided, the verilator run will produce a .vcd file with waveform informationTESTNAME=${TESTNAME}
is optional; if not provided, test defaults to value of TESTNAME environment variable, then to iccm_lock
make ... <args> ... | tee <path/to/run/folder>/verilate.log
run_verilator_l0_regression.py
python3 run_verilator_l0_regression.py
${CALIPTRA_WORKSPACE}/scratch/$USER/verilator/<timestamp>/<testname>
for each test runsrc/<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.<name>_tb
as the top targetcaliptra_top
: Description:
The UVM Framework generation tool was used to create the baseline UVM testbench for verification of the top-level Caliptra image. The top-level bench leverages the soc_ifc_top
testbench as a subenvironment, to reuse environment level sequences, agents, register models, and predictors.
Prerequisites:
Environment Variables:
UVM_HOME
: Filesystem path to the parent directory containing SystemVerilog source code for the UVM library of the desired version.
UVMF_HOME
: Filesystem path to the parent directory containing source code (uvmf_base_pkg) for the UVM Frameworks library, a tool available from Mentor Graphics for generating baseline UVM projects.
QUESTA_MVC_HOME
: Filesystem path to the parent directory containing source code for Mentor Graphics QVIP, the verification library from which AHB/APB UVM agents are pulled in the Caliptra UVM environment.
Steps:
verification_ip
provided for soc_ifc
found in Caliptra/src/soc_ifc/uvmf_soc_ifc
caliptra_top
testbench found in Caliptra/src/integration/uvmf_caliptra_top
src/integration/uvmf_caliptra_top/config/uvmf_caliptra_top.vf
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 systemprogram.hex
, caliptra_fmc.hex
, caliptra_rt.hex
and must be placed in the simulation run directorymake -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
Caliptra/src/integration/uvmf_caliptra_top/uvmf_template_output/project_benches/caliptra_top/tb/tests/src
+UVM_TESTNAME=<test>
argument to simulationDescription:
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:
Prerequisites:
Steps:
verification_ip
provided for the target testbenchsrc/<block>/uvmf_<name>/config/<name>.vf
Caliptra/src/<block>/uvmf_<name>/uvmf_template_output/project_benches/<block>/tb/testbench/hdl_top.sv
is the top-level TB wrapper for the systemCaliptra/src/<block>/uvmf_<name>/uvmf_template_output/project_benches/<block>/tb/tests/src
+UVM_TESTNAME=<test>
argument to simulationOnly tests from the L0 Regression List should be run. The list is defined in the file L0_regression.yml
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.