# chipsalliance/caliptra architecture

> Architecture diagram of the GitHub repository chipsalliance/caliptra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chipsalliance/caliptra
- Repository: https://github.com/chipsalliance/caliptra

## Overview

##### Project type and purpose
- Caliptra is neither a web app nor a traditional full-stack project; it is a hardware IP + firmware reference design (Root of Trust for Measurement) intended to be integrated into datacenter-class SoCs. This repository houses governance, documentation, and pointers to code across multiple repos (RTL, ROM, FMC, runtime, subsystem, MCU, DPE, etc.).

##### File structure
- Top-level items (.github, doc/, README, CONTRIBUTING, SECURITY) revolve around process, docs, and governance.
- There is no source code here; actual implementations live in external repos (caliptra-rtl, caliptra-sw, caliptra-ss, caliptra-mcu-sw, caliptra-dpe, etc.).
- Within doc/: comprehensive spec for Caliptra 1.x and 2.x, FIPS compliance, branding, OCP_LOCK, trademark.

##### README for additional insights
- Caliptra provides:
- Hardware (RTL) for a RoT block inside an SoC
- ROM: immutable bootloader code
- FMC (First-Stage Controller) firmware
- Runtime firmware for higher-level services (attestation, key management)
- Subsystem MCU and DPE profiles as optional components
- The lifecycle: power-on → ROM → FMC → runtime → external attestation

a. Main components
- SoC (host processor subsystem)
- Caliptra RoT block
- Hardware RTL (crypto engines, state machines, MMIO registers)
- On-chip ROM (bootloader)
- FMC firmware (first-stage code)
- Runtime firmware (attestation, measured boot, key services)
- Optional: DPE environment, Subsystem MCU
- External services
- Attestation verifier (cloud or management controller)
- Identity provisioning authority
- OCP bus interconnect / host agent (access to Caliptra registers via I3C or APB)
b. Relationships & interactions
- On power-on, the hardware RTL vector jumps into ROM.
- ROM performs basic self-tests & hands off to FMC.
- FMC measures subsequent firmware stages, initializes crypto engines, then loads and starts runtime.
- Runtime implements attestation protocols, key wrapping/unwrapping, manifest-based authorization.
- The host/management controller interacts through MMIO or mailbox registers (I3C, APB).
- External verifier polls or requests signed measurements/CSRs.
c. Architectural patterns & design principles
- Layered boot sequence: immutable → measured → attested
- Hardware–firmware co-design: hardware enforces isolation and atomic measurements; firmware drives the logic;
- Principle of least privilege (FMC and runtime run in isolated hardware contexts)
- Modular specifications: separate repos for RTL, firmware (ROM, FMC, runtime), subsystem (MCU), DPE, etc.
d. Key technologies
- Verilog/SystemVerilog RTL for hardware
- Rust/C for firmware (ROM, FMC, runtime)
- MMIO register libraries (caliptra-ureg)
- I3C or APB bus interfaces
- Crypto primitives (ECC, LMS, ML-DSA)

##### Detail without overthinking
- Break the block into as many logical sub-components as needed (self-test FSM, key vault, mailbox interface, etc.).
- Every piece that plays a role in secure boot, measurement, and attestation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Boot Sequence
    POR["Power-On Reset"]:::hw
    POR --> RTL
    subgraph "Hardware IP (RTL)"
        RTL["Caliptra RTL"]:::hw
        CE["Crypto Engines"]:::hw
        FSM["Self-Test FSM"]:::hw
        REG["MMIO Registers"]:::hw
    end
    RTL --> ROM
    ROM["On-Chip ROM (Bootloader)"]:::fw
    ROM --> FMC
    FMC["FMC Firmware"]:::fw
    FMC --> RT
    RT["Runtime Firmware"]:::fw

    %% Optional Components
    subgraph "Optional Components"
        MCU["Subsystem MCU"]:::opt
        DPE["DPE Environment"]:::opt
    end
    RT --> MCU
    RT --> DPE

    %% Host & External Services
    Host["Host APB/I3C Interface"]:::ext
    Provision["Identity Provisioning Authority"]:::ext
    Verifier["External Attestation Verifier"]:::ext

    Host --> REG
    RT -->|"Attestation Response"| Verifier
    Verifier -->|"Request Measurements"| RT
    Provision -->|"Provision Identities/Keys"| ROM

    %% Documentation & Governance
    subgraph "Governance & Docs"
        GH[".github/"]:::doc
        CO["CODEOWNERS"]:::doc
        CM["CONTRIBUTING.md"]:::doc
        SM["SECURITY.md"]:::doc
        RM["README.md"]:::doc
        subgraph "Hardware IP Spec"
            D1["doc/caliptra_1x/Caliptra.md"]:::doc
            D2["doc/caliptra_20/Caliptra.md"]:::doc
        end
        subgraph "FMC & Runtime Docs"
            D3["doc/caliptra_1x/Caliptra.md"]:::doc
            D4["doc/caliptra_20/README.md"]:::doc
        end
        subgraph "FIPS Compliance"
            Df1["doc/caliptra_1x/fips/README.md"]:::doc
            Df2["doc/caliptra_1x/fips/compliance_summary/"]:::doc
            Df3["doc/caliptra_1x/fips/security_policy_1_0/"]:::doc
            Df4["doc/caliptra_1x/fips/security_policy_1_1/"]:::doc
        end
        subgraph "OCP_LOCK Interface"
            OL1["doc/ocp_lock/README.md"]:::doc
            OL2["doc/ocp_lock/lock_spec.ocp"]:::doc
            OL3["doc/ocp_lock/diagrams/uml/"]:::doc
        end
        subgraph "Branding & Trademark"
            BG["doc/branding_guide/Caliptra_Compliant_Brand_Guidelines_2025-02-17.pdf"]:::doc
            TM["doc/trademark/Caliptra Conformance Program -*.pdf"]:::doc
        end
        subgraph "Release & Roadmap"
            RR["doc/caliptra_20/Roadmap.md"]:::doc
        end
        subgraph "CI/CD"
            DW[".github/workflows/deploy_pages.yml"]:::doc
        end
    end

    %% Click Events
    click GH "https://github.com/chipsalliance/caliptra/tree/main/.github/"
    click CO "https://github.com/chipsalliance/caliptra/tree/main/CODEOWNERS"
    click CM "https://github.com/chipsalliance/caliptra/blob/main/CONTRIBUTING.md"
    click SM "https://github.com/chipsalliance/caliptra/blob/main/SECURITY.md"
    click RM "https://github.com/chipsalliance/caliptra/blob/main/README.md"
    click D1 "https://github.com/chipsalliance/caliptra/blob/main/doc/caliptra_1x/Caliptra.md"
    click D2 "https://github.com/chipsalliance/caliptra/blob/main/doc/caliptra_20/Caliptra.md"
    click D3 "https://github.com/chipsalliance/caliptra/blob/main/doc/caliptra_1x/Caliptra.md"
    click D4 "https://github.com/chipsalliance/caliptra/blob/main/doc/caliptra_20/README.md"
    click Df1 "https://github.com/chipsalliance/caliptra/blob/main/doc/caliptra_1x/fips/README.md"
    click Df2 "https://github.com/chipsalliance/caliptra/tree/main/doc/caliptra_1x/fips/compliance_summary/"
    click Df3 "https://github.com/chipsalliance/caliptra/tree/main/doc/caliptra_1x/fips/security_policy_1_0/"
    click Df4 "https://github.com/chipsalliance/caliptra/tree/main/doc/caliptra_1x/fips/security_policy_1_1/"
    click OL1 "https://github.com/chipsalliance/caliptra/blob/main/doc/ocp_lock/README.md"
    click OL2 "https://github.com/chipsalliance/caliptra/blob/main/doc/ocp_lock/lock_spec.ocp"
    click OL3 "https://github.com/chipsalliance/caliptra/tree/main/doc/ocp_lock/diagrams/uml/"
    click BG "https://github.com/chipsalliance/caliptra/blob/main/doc/branding_guide/Caliptra_Compliant_Brand_Guidelines_2025-02-17.pdf"
    click TM "https://github.com/chipsalliance/caliptra/blob/main/doc/trademark/Caliptra Conformance Program -*.pdf"
    click RR "https://github.com/chipsalliance/caliptra/blob/main/doc/caliptra_20/Roadmap.md"
    click DW "https://github.com/chipsalliance/caliptra/blob/main/.github/workflows/deploy_pages.yml"

    %% Styles
    classDef hw fill:#dddddd,stroke:#333,stroke-width:1px
    classDef fw fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef ext fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef opt fill:#f3e5f5,stroke:#8e24aa,stroke-width:1px,stroke-dasharray: 5 5
    classDef doc fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
```
