Caliptra firmware and software

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

Documentation

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

Directory structure

api

Definitions for the Caliptra mailbox and other basic firmware interfaces.

builder

Tool for building the Caliptra firmware bundle.

cfi

Library containing Control-Flow Integrity attack countermeasure implementations.

ci-tools

Various tools used for Continuous Integration flows.

common

Common code shared across multiple other code modules.

coverage

Tool for collecting code coverage metrics from Caliptra tests.

cpu

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

dpe

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

drivers

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

error

Comprehensive list of all Caliptra error codes.

fmc

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

hw

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

hw-model

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

image

Libraries for generating and verifying Caliptra firmware images.

kat

Known Answer Tests for all cryptographic operations supported by Caliptra.

libcaliptra

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

lms-types

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

registers

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

rom

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

runtime

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

sw-emulator

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.

systemrdl

RDL parser used in the creation of register definitions.

test

Test suites for various portions of the Caliptra implementation.

test-harness

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.

ureg

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

x509

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

Building / Testing

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.

Checkout and build

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

Testing in a hurry

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>

Testing against Verilator

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.

Testing against FPGA

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