Repository files navigation

This repository contains firmware, libraries, and tools related to theCaliptra 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 beused 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 aftervalidation succeeds.

Caliptra RTL submodule location and implementations of RTL based test environments forverilator andfpga.

A high-level testing library for instantiating and manipulating models of thehardware. 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 RDLfiles in thecaliptra-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 functionalityafter the boot process. This module is jumped to from FMC.

Fast software-based simulation of the Caliptra hardware. This is the fastest andeasiest 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. Theregisters directory has a binary that creates the register code that includes ureg.

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

To build Caliptra firmware or tools, you need a Linux installation with a recentRust toolchain. SeeGetting started withRust for more information oninstalling an up-to-date Rust toolchain. We use version 1.70 of the Rusttoolchain for all continuous integration.

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

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

# (from caliptra-sw/)cargotest

To run a single emulator test:

cargotest -p caliptra-drivers test_doe

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

$CPTRA_TRACE_PATH=/tmp/trace.txt cargotest -p caliptra-drivers test_doe$cat /tmp/trace.txt<snip>pc=0xf6pc=0xf8UC write4 *0x50002290 <- 0xffffffffpc=0xfapc=0xb2pc=0xb6UC read1 *0x500022b5 -> 0xffpc=0xba<snip>

We useVerilator to provides ahigh-fidelity simulation based onCaliptra's RTL. Running tests inthis environment can reveal bugs in the firmware, hardware, and the integrationbetween the two.

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

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

cargotest --features=verilator --release

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

cargotest --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 cargotest --features=verilator -p caliptra-drivers test_pcrbank

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

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

Download caliptra-fpga-bitstream from thelatest fpga builds of main

Load the FPGA image and run a test:

sudo ./hw/fpga/setup_fpga.sh caliptra_fpga.binCPTRA_UIO_NUM=4 cargotest --features=fpga_realtime,itrng -p caliptra-test smoke_test::smoke_test