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

Release history

The tables below list all official ROM and FMC+Runtime firmware releases. For ROM releases the SHA256 is the digest embedded inside each ROM binary (it covers all ROM bytes before the RomInfo struct, using the builder's word-reversed hashing convention), and the SHA384 is computed over the entire raw ROM binary. Both the no-log (caliptra-rom.bin) and with-log (caliptra-rom-with-log.bin) variants are included. For FW releases the SHA384 hashes are the digests stored inside the firmware image manifest's TOC entries for the FMC and Runtime images — they are not hashes of the firmware bundle file itself. The rom-1.0.3 entry was built from source because its GitHub release does not contain pre-built binary artifacts. The RTL column indicates which caliptra-rtl release(s) each ROM or firmware binary is known to be compatible with.

These tables can be regenerated or extended by running:

cargo xtask release info --markdown --build

ROM Releases

Version	RTL	SHA256 (no log)	SHA256 (with log)	SHA384 (no log)	SHA384 (with log)	Git Commit	SVN
rom-1.0.0	1.0	6bbe42fcda193d19b371ba39d41f515bbb06d1e7381b2aa8f41057cb27d6e286	60f31e3c65577e5dbaac05bd5d754ab927af05557844bebb3affbca88d59b483	73bf24f7285b08137e03a8d6dbaca3bf03f8651eb319c4409ac8767be62fd90724aa8545261a4994d93c21f5ab1a904a	70348fa78230ebff9cffbc98c120d22f876b7cd41f630bbf740e7f0e99aeb7676a37699889c35ef3842c5622d3287f80	e61eb66	0
rom-1.0.1	1.0	5c509ab7299c20e10cb2c4d32341f039ed77fa29ce36e8baeafa0c79feef4642	67e538ca65e0c690e8c3f955c3f19a052c8ea347ddb90a6cbf226e73f1c8e4fc	b364341552d08e63b3294914a319e697cf8b8b937604bcd28bc3e15bd6e32315cd403ba69f064bfd3c447baad012864e	4da8decde59f3bebd8d7a31db7c8d7f4596da29ea0db44dcbf3848430d57b1155c8da3e6b1a9d9ab08391c89c4351799	9342687	0
rom-1.0.2	1.0	604dd02bba786bba5d9e7284bcd99f42d314ccb5d3b9ff080aca7477b2d5bcb7	f69d4fba7f1bdbc2cbd3682f807e0d144ad227a0eaf0afd455f7d6931453a10c	7b3b83b569a5a4e1fc6f49be988aa5ac49ed579ad166708c022b330e6bbc02bcb19067debbe3bb944a3e9a5441794817	f51fdcf0fc460f005f37e908229851fd1fd3dfc21d54ad6fdab132844974a4264a4524b75bb82ab039e0b52b55768630	30887b7	0
rom-1.0.3	1.0	6d02fb958125550a641546c1dde5a31a6e4ac8f9c54cdb38da4815295b533add	13ea3613a6803431146b6974f1fb3587bd56c8ea0238f3c30b0819270ca848cb	e18a393e604230509d468205972185fe1b55e6a39a088a40ecc46c7e82749110e3c0287de565cd735aaf0e3bcf19e003	94851338e4ab00ce6ea7e3d0bdd568791545b9b92936a8fd0741a8efced4c79fe75ae98dfbf29014b46b8d566607698b	e8e23d9	0
rom-1.1.0	1.1	875d30a2e26d55c35ad9cbc0affc3db057d40cebdd6f3e31c7c39b5ae34d4491	34e015d6d8c44109576aee80cd8428bea27286d34af3704a48c395c1fc32a424	b92ed17a39ce58d5b58c697aa6b7959d51282219ea14d7a9eafaed9bd78bfb94138bc5dd6c48b760990165094abc7e01	ff37afba4b438f306da48885b87badd9506c5cf6cbef3bacdf013d148878dad889f688fcaa46bc19ed14b0ca25068fe8	51ff0a8	0
rom-1.1.1	1.1	37f8f863a2b563757db9caec87b5c901765515e0ac61fe6f8da766b262638702	0212785561da4479f3a14aa516c8a6db0a887b428a3a9053bf5f2ea529a5d6bd	7af29db7dca485a6ede47cf78330973b97eaba1bb3c0eb7482c73cde8d128d7a151a54d5ecd8b2cc3b1e73bea0910ebd	71f54d7806a0a4c5055cf50a78f4286c484fd1bd548443e291722ea6b52ec17e7c10a90380da24a6a6167db88b13fc77	d6713db	0
rom-1.2.0	1.1	de1a164d2431459cd61b80f989c9b59a22fc132dc664e6cbd4eddca734b93c3b	af44c1c1a7763c7197a9497112e3f3ad3224fe895c8713510543282330407484	6759cb95de60d8f58e44f9b8a0b5512d9e8aa6c5cef450484b887cb7d8d6d8ad4fedb0c646bdd30852b6a85f6aa84d95	64da5237e2412bcbd203db756136e474e2d8d078d8752b68bddd5b9717563abeecd27874ac0eead1bc777a4f01f5fc24	3b50c6a	0
rom-2.0.0	2.0.2+	34340911bda1d1e162a4ce74e6b00b79ef14fd0625f39d0420fc882a8f865a04	58505d9ca0b7d35607ef737c14d1b860a6140548ec655d68b3b08761f9518011	fe713cc28b370457ba16041e7f9a0f72de8249b6cd958b077cef9bc53e734bcff98368dbe33417e4aaa9f914192709c2	721e9dd57ef1738c3bbc49f8f9461395f30c448a5ba16240eaac986893fd2fd94c67be603008779a8e58e797f73dac07	62c8009	0
rom-2.0.1	2.0.2+	c59fb3d1577c9390060ad23d0e1a3d657b38d3f3d0f995102c0cd76718792260	d97d8a56581419143f6eb75d922bba845eb9887e48f38aabd060e386e57efb6d	c19abd419720eeb5dad7beb20e587185bf0aa61546cbbc6514f56edc041730d6c9831175156c8d19e087f733ebbb382e	4f718dcda9ca6d4237db7f7fdcb9903ce629354ecae5605622fadb0575a4c1066902102085122d4c3b860bb66c2c64b7	3824083	0
rom-2.0.2	2.0.2+	87422a3bbfabb277fa3c5cd3ea1118d7aae9a7c9483125b48b03eb29e8c12a4c	e977291bf7662327a45d2db252f420b930a0480c2f40a112c334ddea41f14d1a	a2a76fe0ef50fb1076a02f35c174ae01aec49816f86693438301807874274d0a4a1fc56b9aaaf6cb7bffcf0ad441f09c	516dc77518b344ae9c4eddda195ee7a0a4503a0ea8854ab1ab9e18abc725425550b501a95decc31bda97541442436e58	473ae25	0
rom-2.1.0	2.1	d4cfdc9e413adc37c0079e1db7e88c1d4d049e0f19480d00e1f9898b6d2c21a7	99ba0ba9b4c5961a4749129458483f7b4b5222c3e5b33af092d991ae1eeb25ff	0d59b814c836b721f41bdd62cd46df5cf412e3ce673c6004f90f4cdb9645e57082cc0a6615aa26744eefd9629c189cca	4a7b5c2005562b1624f12ebdb771c2ba4b99ce0afc5ebadad0f520e6e25bab5b4c59c4f320f075608f97b93574242a86	a72a76f	0
rom-2.1.1	2.1	028268971f9514409caa4846dfa3e82faf20e8efec69123da97e00a3cdb04e1d	512c69c828f0cca54b858937003dfd72fc799abd8078534f3cef27fc03302aeb	721657be76a4ac343cd3141d4d3a52ca9623590a40dace54dd022e321fcdab1b2050f5c2e9ca868c0a9786723695db69	4583491bd505f1b7d01e43376362741086ace56073e20096fac8bff04f73128a85ef11d5bbbb806dacca04fb298c692d	510a23a	0

FMC+Runtime FW Releases

Version	RTL	FMC SHA384	Runtime SHA384	Git Commit	SVN
fmc-1.0.0 / rt-1.0.0	1.0	442ff0ea0e4661f984a9cff4ecb32d960898c6e8978c9fafaa7b6e199f53f7ecca15a4c5280b6aefd7b2941a31fadcf1	af0e463499a3c3ccf9f0a2b6f8b8cfc7d4075ccf0f4258685b10620e763e14c8b3b97d72ef5e1356001ec67820a95756	cddb376	0
fmc-1.0.2 / rt-1.0.2	1.0	d725fab9c02ef81d6fc3327443c569c3707608de36183d5236cb784bd5d70afb253613be59fdf72c5d0ddeb134fd4907	92f057c0f4cf1dd026433fe49a216520916eed4f7522162d903f225904371e14413e138c8239bca647c0e2d7814efe93	30887b7	0
fmc-1.1.0 / rt-1.1.0	1.0, 1.1	493f979282a01779783b7edaa6f0e114b7b12f963e514e5f6e7dcfb02b627546d5d0b1fcfcfeebe6da09deae5d200ff6	adfc57dfead8a290bb71a92bab1317d6cca0f8c1e2b74d0a181e0136865783c0f6158ccabf2cc6a26c4071a250d21f3f	51ff0a8	0
rt-1.2.0	1.0, 1.1	3c205680003c6e9d7064456de1f3c690256a68ad29739ff40e5c46a677d82ee7d044bd7f322642d4df6e2a7cafe63bcf	002809d7387f0bc6ce16e09e1f585d05c0a7557083c52586d95fc576a725999a9e229badfdedc2c78aeeb4a5e9a3471b	951209a	0
rt-1.2.1	1.0, 1.1	45c6fdce6654e24eecf2351daa73a9c78a1c1cdc7623704e03f11e173624d68597f7f50d30abd2790528c8edd53d4c78	b6838fd4328d3729b34725ac4e79991760143e35483077ae3a7202f9fbff5eb9e5c72c1480457f1cf289eca7c131a52e	98df57b	0
rt-1.2.2	1.0, 1.1	4b37512f0697e362d98b609699da612ad027dfd78b6315e71a6cff833dfb716c4ac809ca4cdc0e5368f0e0d94c1dcca2	09ce915a76c9e8d7725f2a9122135d886bc623daa655177c7f553d9dbfcc75432e6d489621c17eefc184dc49ab5462b7	cccf641	0
rt-1.2.3	1.0, 1.1	21cd61a7659bcea8b9b9ff7bd9181bee4c4671c9e7aa24d67b727bdf1cae149b9883e144986af8d37195eff9ba9a9e51	89865e07491547ecfa6da9897edfd1c0a81a8143462d9628c5acf3e696b7857af31a82492a51e1b6734a24d01561d484	1551253	0
rt-1.2.4	1.0, 1.1	2ecc7de8e0de934e6c331fc8e8bc7a7bc4247a23f6cb5d17d5883c6ad91a632b4eb7070b90ad5114fec9f2e5070fe8a9	4aac73bfe46d09998445f2ee862e142540a24f5aa6a352f97707030daeb8c12f9a8e7d0d8a2310644c38ffe21a65fd0d	84ca1a1	0
fw-2.0.0	2.0.2+	472130e91363e1370c3fd20bc28b7e9c5f177d1546f73ec4ba880064e4bca3782c40f40a8412306777e6011fe8cdded1	d1ae602a36933198429702b875ebc9b221f6756666f986d6ab89fbf341fae02b8af8129f0f2b4c89518c6bc9612cd7e3	8efce03	0
fw-2.0.1	2.0.2+	4d9a757130dbc0236d8187f958626935b5566c8869fe266724d52a77a78361884ee140dc39b9c9a2d211b2b28321b5f2	f31899a4ede94bcc166eaf8c4692112637442b9179497ca9fd315947c1682d5327994b020b93c11d486203d028021fee	1a77f86	0
fw-2.1.0	2.1	a34cb959b33bac15ca774275f10732a37f101bb159eb5ff6908fe88a8015469534f2a23fcc6c3f42d72bd71c6955d737	674c3caff5e834b044619e824d3f2c6d041d34a29d04bda081449d4ff2d1e00638b8ac4ec3389af50a1894a5799f452f	7da3b01	0
rt-1.2.5	1.0, 1.1	2ecc7de8e0de934e6c331fc8e8bc7a7bc4247a23f6cb5d17d5883c6ad91a632b4eb7070b90ad5114fec9f2e5070fe8a9	67406db51e0a2315361e14bd1c7263f1b106a3bda4b5774e43d573243ea3ffa8538ea0534e2b5c38e340112b9156b8c2	b8d1f59	0

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.

caliptra-ureg

Register abstraction and code generator to create register libraries. The registers directory has a binary that creates the register code that includes caliptra-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.

For a streamlined development experience, use the xtask FPGA flow, which automates building, programming, and testing:

# Setup once per power cycle
cargo xtask fpga bootstrap

# Build and run tests
cargo xtask fpga build
cargo xtask fpga build-test
cargo xtask fpga test