{"id":18352619,"url":"https://github.com/chipsalliance/caliptra-ss","last_synced_at":"2026-04-02T00:32:35.013Z","repository":{"id":255260323,"uuid":"747911082","full_name":"chipsalliance/caliptra-ss","owner":"chipsalliance","description":"HW Design Collateral for Caliptra Subsystem, which comprises Caliptra RoT IP and additional manufacturer controls.","archived":false,"fork":false,"pushed_at":"2026-03-20T22:47:11.000Z","size":23957,"stargazers_count":39,"open_issues_count":86,"forks_count":37,"subscribers_count":16,"default_branch":"main","last_synced_at":"2026-03-21T10:50:23.244Z","etag":null,"topics":["caliptra","ocp","opencomputeproject","root-of-trust","rot","security"],"latest_commit_sha":null,"homepage":"","language":"SystemVerilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chipsalliance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-24T22:05:44.000Z","updated_at":"2026-03-19T22:48:42.000Z","dependencies_parsed_at":"2024-09-17T22:19:53.760Z","dependency_job_id":"144efc48-8bf5-4a0e-94da-d506bfc7ce7d","html_url":"https://github.com/chipsalliance/caliptra-ss","commit_stats":null,"previous_names":["chipsalliance/caliptra-ss"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/chipsalliance/caliptra-ss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2Fcaliptra-ss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2Fcaliptra-ss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2Fcaliptra-ss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2Fcaliptra-ss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chipsalliance","download_url":"https://codeload.github.com/chipsalliance/caliptra-ss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2Fcaliptra-ss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caliptra","ocp","opencomputeproject","root-of-trust","rot","security"],"created_at":"2024-11-05T21:36:39.260Z","updated_at":"2026-04-02T00:32:34.985Z","avatar_url":"https://github.com/chipsalliance.png","language":"SystemVerilog","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Caliptra Subsystem Overview\n_*Last Update: 2025/10/12*_\n\nHW Design Collateral for Caliptra Subsystem, which comprises Caliptra RoT IP and additional infrastructure to support manufacturer custom controls.\n\n## Project Links\n\n[caliptra-ss](https://github.com/chipsalliance/caliptra-ss)\u003cBR\u003e\n[Caliptra Subsystem v2.0 Example Register Map](https://chipsalliance.github.io/caliptra-ss/v2_0/regs/?p=)\u003cBR\u003e\n[Caliptra Subsystem v2.1 Example Register Map](https://chipsalliance.github.io/caliptra-ss/v2_1/regs/?p=)\u003cBR\u003e\n[Caliptra Subsystem Example Register Map (main branch)](https://chipsalliance.github.io/caliptra-ss/main/regs/?p=)\u003cBR\u003e\n\n## **Tools Used** ##\n\nOS:\n - Build instructions assume a Linux environment\n\nLINT:\n - Synopsys SpyGlass\n   - `Version U-2023.03-SP2-8 -- Aug 09, 2024`\n\nSimulation:\n - Synopsys VCS with Verdi\n   - `Version U-2023.03-SP1-1_Full64`\n - Mentor Graphics AVERY\n   - `avery/2025.1_20250313` AXI interconnect and I3C VIP\n - ARM AXI Protocol Checker\n   - `BP063-BU-01000-r0p1-00rel0` Axi4PC.sv must be acquired from the ARM website\n - UVM installation\n   - `Version 1.1d`\n\nGCC:\n - RISCV Toolchain for generating memory initialization files\n   - `Version 2023.04.29`\n   - `riscv64-unknown-elf-gcc (g) 12.2.0`\n - G++ Used to compile Verilator objects and test firmware\n   - `g++ (GCC) 11.2.0`\n\nCDC:\n - Questa CDC\n   - `2023.4_3 5762808 linux_x86_64 29-Feb-2024`\n\nRDC:\n - Real Intent Meridian\n    - 2022.A.P10.2\n\nSynthesis:\n - Synopsys Design Compiler (R) NXT \n    - Version U-2022.12-SP6\n\nScripts:\n - Python\n    - tools/scripts/fuse_ctrl_script/gen_fuse_ctrl_vmem.py\n        - 3.7.3\n        - Package dependencies:\n           - jsonschema==4.5.1\n           - ruamel-yaml==0.17.32\n           - hjson==3.1.0\n           - importlib_resources==5.4.0\n           - Mako==1.0.6\n           - pycryptodome==3.21.0\n           - tabulate==0.8.10\n    - All other scripts\n        - 3.9.2\n        - RDL Compiler dependencies:\n           - systemrdl-compiler==1.27.3\n           - peakrdl-systemrdl==0.3.0\n           - peakrdl-regblock==0.21.0\n           - peakrdl-uvm==2.3.0\n           - peakrdl-ipxact==3.4.3\n           - peakrdl-html==2.10.1\n           - peakrdl-cheader==1.0.0\n           - peakrdl==1.1.0\n\nOther:\n - Playbook (Microsoft Internal workflow management tool)\n\n### **RISCV Toolchain installation** ###\nThere is significant configurability when installing the RISCV toolchain.\nThese instructions may be used to create a RISCV installation that will be compatible\nwith the provided Makefile for compiling test C programs.\n\n1. Install from this repository:\n    - https://github.com/riscv-collab/riscv-gnu-toolchain\n    - Follow the included README in that repository for installation instructions\n2. The most recently tested toolchain build that was confirmed to work was 2023-04-29\n    - https://github.com/riscv-collab/riscv-gnu-toolchain/releases/tag/2023.04.29\n3. A compatible tool installation requires newlib cross-compiler, multilib support, and the zicsr/zifencei extensions. Use this configure command:\n    - `./configure --enable-multilib --prefix=/path/to/tools/riscv-gnu/2023.04.29 --with-multilib-generator=\"rv32imc-ilp32--a*zicsr*zifencei\"`\n4. Use `make` instead of `make linux` to install the tool (using newlib option)\n\n## **ENVIRONMENT VARIABLES** ##\nRequired for simulation:\u003cBR\u003e\n`CALIPTRA_WORKSPACE`: Defines the absolute path to the directory where the simulation \"scratch\" output directory will be created. Recommended to define as the absolute path to the directory that contains a subdirectory \"chipsalliance\" which, in turn, contains the Project repository root (called \"caliptra-ss\")\u003cBR\u003e\n`CALIPTRA_SS_ROOT`: Defines the absolute path to the Project repository root (called \"caliptra-ss\"). Recommended to define as `${CALIPTRA_WORKSPACE}/chipsalliance/caliptra-ss`.\u003cBR\u003e\n`CALIPTRA_ROOT`: Defines the absolute path to the Caliptra submodule root. Must be defined as `${CALIPTRA_SS_ROOT}/third_party/caliptra-rtl`.\u003cBR\u003e\n`ADAMSBRIDGE_ROOT`: Defines the absolute path to the Adams-Bridge submodule root. Must be defined as `${CALIPTRA_ROOT}/submodules/adams-bridge`.\u003cBR\u003e\n`CALIPTRA_PRIM_ROOT`: Set to $CALIPTRA_ROOT/src/caliptra_prim_generic for simulation. See Caliptra core integration specification for technology specific instructions.\n`CALIPTRA_PRIM_MODULE_PREFIX`: Set to caliptra_prim_generic for simulation. See Caliptra core integration specification for technology specific instructions.\n`CALIPTRA_AXI4PC_DIR`: Path to the directory that contains the ARM AXI4 Protocol Checker file. This file must be acquired from the Arm website by integrators, as it contains copyrighted materials.\u003cBR\u003e\n`AVERY_HOME`: Installation root for Avery VIP\u003cBR\u003e\n`AVERY_PLI`: Directory within AVERY\\_HOME that contains avery\\_pli\u003cBR\u003e\n`AVERY_SIM`: Directory within AVERY\\_HOME that contains avery\\_sim\u003cBR\u003e\n`AVERY_AXI`: Directory within AVERY\\_HOME that contains axixactor\u003cBR\u003e\n`AVERY_I3C`: Directory within AVERY\\_HOME that contains i3cxactor\u003cBR\u003e\n\nRequired for Firmware (i.e. Test suites) makefile:\u003cBR\u003e\n  `TESTNAME`: Contains the name of one of the tests listed inside the `$CALIPTRA_SS_ROOT/src/integration/test_suites` folder; used for simulations with `caliptra_ss_top_tb` tests\u003cBR\u003e\n  `CALIPTRA_TESTNAME`: Identifies which firmware test will be compiled and executed on the Caliptra Core RV processor as part of the Subsystem test. This may indicate the name of a directory inside `$CALIPTRA_ROOT/src/integration/test_suites`, or it may indicate the name of a test firmware file contained inside the caliptra-ss repository for execution on Caliptra core. In this case, the file must be:\n  * Named with a `cptra` prefix, to uniquely identify it from MCU firmware test files, and EITHER\n  * Located in the same directory as the MCU test firmware, i.e. `$CALIPTRA_SS_ROOT/src/integration/test_suites/$TESTNAME` OR\n  * Located in the the test\\_suites folder in a directory with the same name as the test file, i.e. `$CALIPTRA_SS_ROOT/src/integration/test_suites/$CALIPTRA_TESTNAME`\n\n## **Repository Overview** ##\n```\n├── config\n│   └── compilespecs.yml\n├── docs\n│   ├── Caliptra_Gen2_SS_TestPlan.xlsx\n│   ├── CaliptraSSCoverage.md\n│   ├── CaliptraSSHardwareSpecification.md\n│   ├── CaliptraSSIntegrationSpecification.md\n│   ├── CaliptraSSReleaseChecklist.md\n│   ├── coverage_reports\n│   └── images\n├── LICENSE\n├── README.md\n├── Release_Notes.md\n├── SECURITY.md\n├── src\n│   ├── ast\n│   ├── axi2tlul\n│   ├── axi_mem\n│   ├── dmi\n│   ├── fuse_ctrl\n│   ├── i3c_core\n│   ├── integration\n│   ├── lc_ctrl\n│   ├── libs\n│   ├── mci\n│   ├── mcu\n│   ├── pwrmgr\n│   ├── riscv_core\n│   └── tlul\n├── third_party\n│   ├── caliptra-rtl\n│   ├── cocotbext-i3c\n│   └── i3c-core\n└── tools\n    └── scripts\n```\n\n## **Verilog File Lists** ##\nVF files provide absolute filepaths (prefixed by the `CALIPTRA_SS_ROOT` environment variable) to each compile target for the associated component.\u003cBR\u003e\nThe \"Integration\" sub-component contains the top-level fileset for Caliptra Subsystem. `src/integration/config/compile.yml` defines the required filesets and sub-component dependencies for this build target. All of the files/dependencies for compiling the top-level testbench are explicitly listed in `src/integration/config/caliptra_ss_top_tb.vf`. Users may compile the entire design using only this VF filelist.\u003cBR\u003e\nVerilog file lists are generated via VCS and included in the config directory for each unit. 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. Compilation using the provided Verilog file lists requires all [environment variables](#environment-variables) to be defined.\n\nImportant: Users must download the [ARM AXI4 Protocol Checker](https://developer.arm.com/downloads/view/BP063) from ARM, as it is a dependency\nfor the Avery AXI VIP. These files contain proprietary materials and therefore are not included in the\ncaliptra-ss GitHub repository.\n\n## **Simulation Flow** ##\n\n### Caliptra SS Top VCS Steps: ###\n1. Setup tools, add to PATH (ensure RISC-V toolchain is also available)\n1. Define all environment variables above\n    - For the initial test run after downloading repository, `mcu_hello_world` is recommended for TESTNAME\n    - See [Regression Tests](#Regression-Tests) for information about available tests\n1. Create a run folder for build outputs (and cd to it)\n1. Either use the provided Makefile or execute each of the following steps manually to run VCS simulations\n1. Makefile usage:\n    - Example command:\n        `make -C \u003cpath/to/run/folder\u003e -f ${CALIPTRA_SS_ROOT}/tools/scripts/Makefile TESTNAME=${TESTNAME} CALIPTRA_TESTNAME=${CALIPTRA_TESTNAME} vcs`\n    - NOTE: `TESTNAME=${TESTNAME}` is optional; if not provided, test defaults to value of TESTNAME environment variable, then to `mcu_hello_world`\n1. Remaining steps describe how to manually run the individual steps for a VCS simulation\n1. [OPTIONAL] By default, this run flow will use the RISC-V toolchain to compile test firmware (according to TESTNAME, CALIPTRA_TESTNAME) into mcu_program.hex, mcu_lmem.hex, mcu_dccm.hex, program.hex, iccm.hex, dccm.hex, and mailbox.hex. \n1. 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}`, `src/integration/test_suites/${CALIPTRA_TESTNAME}` or in `${CALIPTRA_ROOT}/src/integration/test_suites/${CALIPTRA_TESTNAME}`\n    - E.g.: `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile program.hex`\n    - NOTE: CALIPTRA_TESTNAME may also be overridden in the makefile command line invocation, e.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile CALIPTRA_TESTNAME=smoke_test_mbox program.hex`\n    - NOTE: The following macro values must be overridden to match the value provided (later) during hardware compilation. The full L0 regression suite includes tests that will fail if the firmware and hardware configuration has a discrepancy. Default values in the Makefile are shown with each macro:\n      - CALIPTRA_INTERNAL_TRNG=1\n      - E.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile CALIPTRA_INTERNAL_TRNG=1 program.hex`\n1. Invoke `${CALIPTRA_SS_ROOT}/tools/scripts/Makefile` with target 'mcu_program.hex' to produce SRAM initialization files from the firmware found in `src/integration/test_suites/${TESTNAME}`\n    - E.g.: `make -f ${CALIPTRA_SS_ROOT}/tools/scripts/Makefile mcu_program.hex`\n    - NOTE: TESTNAME may also be overridden in the makefile command line invocation, e.g. `make -f ${CALIPTRA_SS_ROOT}/tools/scripts/Makefile TESTNAME=mcu_hello_world program.hex`\n1. Compile complete project using `src/integration/config/caliptra_ss_top_tb.vf` as a compilation target in VCS. When running the `vcs` command to generate simv, users should ensure that `caliptra_ss_top_tb` and `ai3c_tests_bench` are explicitly specified as the top-level components in their command.\n    - NOTE: The following macro values must be defined (or omitted) to match the value provided during firmware compilation. The full L0 regression suite includes tests that will fail if the firmware and hardware configuration has a discrepancy.\n      - CALIPTRA_INTERNAL_TRNG\n1. Copy the test generator scripts to the run output directory:\n    - $(CALIPTRA_SS_ROOT)/src/fuse_ctrl/data/otp-img.2048.vmem\n    - $(CALIPTRA_SS_ROOT)/third_party/caliptra-rtl/src/ecc/tb/ecc_secp384r1.exe\n    - $(CALIPTRA_SS_ROOT)/third_party/caliptra-rtl/src/doe/tb/doe_test_gen.py\n    - $(CALIPTRA_SS_ROOT)/third_party/caliptra-rtl/src/sha256/tb/sha256_wntz_test_gen.py\n    - $(CALIPTRA_SS_ROOT)/third_party/caliptra-rtl/submodules/adams-bridge/src/mldsa_top/uvmf/Dilithium_ref/dilithium/ref/test/test_dilithium5\n    - $(CALIPTRA_SS_ROOT)/third_party/caliptra-rtl/submodules/adams-bridge/src/mldsa_top/uvmf/Dilithium_ref/dilithium/ref/test/test_dilithium5_debug\n    - $(CALIPTRA_SS_ROOT)/third_party/caliptra-rtl/src/mldsa/tb/smoke_test_mldsa_vector.hex\n1. Simulate project with `caliptra_ss_top_tb` as the top target\n\n## **MCU Veer-EL2 Core Configuration** ##\n\nThe Caliptra Subsystem includes an MCU based on the Veer-EL2 RISC-V core. Users can customize the MCU configuration to meet specific requirements such as cache sizes, memory configurations, or feature enablement. This section describes how to modify the MCU Veer-EL2 core configuration.\n\n### Prerequisites ###\n- Git access to the Cores-VeeR-EL2 repository\n- Basic understanding of Veer-EL2 configuration options\n\n### Configuration Modification Steps ###\n\n1. **Clone the Veer-EL2 Repository**\n   ```bash\n   git clone git@github.com:chipsalliance/Cores-VeeR-EL2.git\n   ```\n\n2. **Set RV_ROOT Environment Variable**\n   \n   Set RV_ROOT to the root of the repository cloned in step 1:\n   ```bash\n   export RV_ROOT=\"/path/to/Cores-VeeR-EL2\"\n   ```\n\n3. **Backup prefix_macros.sh (Workaround)**\n   \n   This file was not committed to the repository until after the 2.0 tag, so it needs to be backed up before checking out the specific commit. The command below is just an example - use any safe backup location:\n   ```bash\n   cp $RV_ROOT/tools/prefix_macros.sh ~/backup/prefix_macros.sh\n   ```\n\n4. **Checkout Required Commit**\n   \n   First, find the required commit hash in `$CALIPTRA_SS_ROOT/src/riscv_core/veer_el2/rtl/riscv_rev_info`, then checkout that specific version:\n   ```bash\n   cd $RV_ROOT\n   git checkout \u003ccommit_hash_from_riscv_rev_info\u003e\n   ```\n   \n   Example:\n   ```bash\n   cd $RV_ROOT\n   git checkout c5c004589ee0a308b63278ee609e1597f61a4143\n   ```\n\n5. **Restore prefix_macros.sh**\n   ```bash\n   mv ~/backup/prefix_macros.sh $RV_ROOT/tools/prefix_macros.sh\n   ```\n\n6. **Modify Veer Build Configuration**\n   \n   Edit the build command script to specify your desired MCU configuration:\n   ```bash\n   $CALIPTRA_SS_ROOT/tools/scripts/veer_build_command.sh\n   ```\n\n7. **Generate New Configuration**\n   \n   Run the build command script with a descriptive snapshot directory name:\n   ```bash\n   $CALIPTRA_SS_ROOT/tools/scripts/veer_build_command.sh new-mcu-config\n   ```\n\n8. **Set Environment Variables for Prefix Script**\n   \n   Configure the required environment variables for the prefix macro script:\n   ```bash\n   export PREFIX=\"css_mcu0_\"\n   export DESIGN_DIR=\"$CALIPTRA_SS_ROOT/src/riscv_core/veer_el2/rtl/design\"\n   export DEFINES_PATH=\"$RV_ROOT/snapshots/new-mcu-config\"\n   ```\n\n9. **Run Prefix Macros Script**\n   ```bash\n   $RV_ROOT/tools/prefix_macros.sh\n   ```\n\n10. **Update Caliptra SS Design Files**\n    \n    Compare and copy the generated configuration files to the Caliptra SS repository:\n    ```bash\n    # Review differences\n    diff -r $DEFINES_PATH $CALIPTRA_SS_ROOT/src/riscv_core/veer_el2/rtl/defines/\n    \n    # Copy updated files (review changes first!)\n    cp $DEFINES_PATH/* $CALIPTRA_SS_ROOT/src/riscv_core/veer_el2/rtl/defines/\n    ```\n\n### Verification ###\nAfter modifying the configuration:\n\n1. **Rebuild the project** using the standard [simulation flow](#simulation-flow)\n2. **Run smoke tests** to verify the new configuration works correctly\n3. **Check simulation logs** for any configuration-related warnings or errors\n\n## **Regression Tests** ##\n\n### Standalone SystemVerilog Testbench Regression ###\nOnly tests from existing regression test lists should be run:\n* L0 smoke tests: [L0_Promote_caliptra_ss_top_tb_regression.yml](https://github.com/chipsalliance/caliptra-ss/blob/main/src/integration/stimulus/L0_Promote_caliptra_ss_top_tb_regression.yml)\n* L1 strict directed tests: [L1_Nightly_Directed_Strict_caliptra_ss_top_tb_regression.yml](https://github.com/chipsalliance/caliptra-ss/blob/main/src/integration/stimulus/L1_Nightly_Directed_Strict_caliptra_ss_top_tb_regression.yml)\n* L1 pseudorandom directed tests: [L1_Nightly_Directed_caliptra_ss_top_tb_regression.yml](https://github.com/chipsalliance/caliptra-ss/blob/main/src/integration/stimulus/L1_Nightly_Directed_caliptra_ss_top_tb_regression.yml)\n* L1 random tests: [L1_Nightly_Random_caliptra_ss_top_tb_regression.yml](https://github.com/chipsalliance/caliptra-ss/blob/main/src/integration/stimulus/L1_Nightly_Random_caliptra_ss_top_tb_regression.yml)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipsalliance%2Fcaliptra-ss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchipsalliance%2Fcaliptra-ss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipsalliance%2Fcaliptra-ss/lists"}