This repository contains firmware, libraries, and tools related to the Caliptra Project.

• Caliptra ROM Module Specification
• Caliptra FMC Module Specification
• Caliptra Runtime Module Specification
• libcaliptra Guide
• Caliptra GitHub GCP Runner Infrastructure

Definitions for the Caliptra mailbox and other basic firmware interfaces.

Tool for building the Caliptra firmware bundle.

Library containing Control-Flow Integrity attack countermeasure implementations.

Various tools used for Continuous Integration flows.

Common code shared across multiple other code modules.

Tool for collecting code coverage metrics from Caliptra tests.

Implementations of CPU-specific features such as NMI and Trap handlers.

DICE Protection Environment submodule (reference to its own repository).

A rust library containing drivers for the Caliptra hardware, intended to be used by firmware running on Caliptra's RISC-V CPU.

Comprehensive list of all Caliptra error codes.

"First Mutable Code", the code that the boot ROM measures and jumps to after validation succeeds.

Caliptra RTL submodule location and implementations of RTL based test environments for verilator and fpga.

A high-level testing library for instantiating and manipulating models of the hardware. Intended to target multiple backends, including sw-emulator, verilator, and FPGA.

Libraries for generating and verifying Caliptra firmware images.

Known Answer Tests for all cryptographic operations supported by Caliptra.

C-API library and example code for accessing Caliptra from its external interfaces.

Type definitions for the Leighton-Micali Hash-Based Signatures algorithm.

Register definitions for the caliptra hardware peripherals, generated from the RDL files in the caliptra-rtl repo.

"Read Only Memory", the code that is first executed when the chip is powered on. Normally the ROM is part of the silicon.

Caliptra runtime environment that is responsible for all Caliptra functionality after the boot process. This module is jumped to from FMC.

Fast software-based simulation of the Caliptra hardware. This is the fastest and easiest way to test changes to firmware, but fidelity may not be perfect.

RDL parser used in the creation of register definitions.

Test suites for various portions of the Caliptra implementation.

A library for building self-contained test firmware binaries. This sets up minimal infrastructure for panic-handling and provides macros for defining test cases in firmware.

Register abstraction and code generator to create register libraries. The registers directory has a binary that creates the register code that includes ureg.

Code used to build and verify the various X509-formatted certificates produced by Caliptra.

To build Caliptra firmware or tools, you need a Linux installation with a recent Rust toolchain. See Getting started with Rust for more information on installing an up-to-date Rust toolchain. We use version 1.70 of the Rust toolchain for all continuous integration.

git clone https://github.com/chipsalliance/caliptra-sw \
    --config submodule.recurse=true \
    --recurse-submodules=dpe
cd caliptra-sw
cargo build

To run all unit tests on the host CPU, and run all integration tests against the sw-emulator:

# (from caliptra-sw/)
cargo test

To run a single emulator test:

cargo test -p caliptra-drivers test_doe

You may wish to get a primitive trace from the sw-emulator while running the test:

$ CPTRA_TRACE_PATH=/tmp/trace.txt cargo test -p caliptra-drivers test_doe
$ cat /tmp/trace.txt
<snip>
pc=0xf6
pc=0xf8
UC write4 *0x50002290 <- 0xffffffff
pc=0xfa
pc=0xb2
pc=0xb6
UC read1 *0x500022b5 -> 0xff
pc=0xba
<snip>

We use Verilator to provides a high-fidelity simulation based on Caliptra's RTL. Running tests in this environment can reveal bugs in the firmware, hardware, and the integration between the two.

If you don't have verilator 5.004 or later installed, follow these directions.

To run all the tests in verilator (this will take several hours):

cargo test --features=verilator --release

Sometimes you may only want to run a single test, like this pcrbank driver test (hosted by the driver integration tests) that can run in seconds:

cargo test --features=verilator -p caliptra-drivers test_pcrbank

To get a VCD dump of ALL waveforms while running the test:

CPTRA_TRACE_PATH=/tmp/trace.vcd cargo test --features=verilator -p caliptra-drivers test_pcrbank

You can open the vcd file with a tool like GTKWave to debug the hardware/firmware.

FPGA provides a fast environment for development with Caliptra RTL. FPGA build directions and further details are available in this README

Download caliptra-fpga-bitstream from the latest fpga builds of main

Load the FPGA image and run a test:

sudo ./hw/fpga/setup_fpga.sh caliptra_fpga.bin

CPTRA_UIO_NUM=4 cargo test --features=fpga_realtime,itrng -p caliptra-test smoke_test::smoke_test