# chipsalliance/caliptra-sw architecture

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

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

## Overview

##### Main Components

a. Hardware Layer
- RISC-V CPU Core
- ROM (Read-Only Memory)
- Hardware Peripherals (from /hw/1.0/registers)
- FPGA Implementation
- Verilator Simulation Environment

b. Firmware Layer
- ROM Module (First executed code)
- FMC (First Mutable Code)
- Runtime Environment
- Drivers Layer

c. Software Layer
- libcaliptra (C-API Interface)
- Test Harness
- Build Tools
- Simulation/Emulation Tools

##### Key Relationships

a. Boot Flow
**ROM -> FMC -> Runtime**

b. Hardware Access Path
**Firmware -> Drivers -> Hardware Peripherals**

c. External Interface
**Host System -> libcaliptra -> Mailbox Interface -> Caliptra**

##### Architectural Patterns

- External Host      |

- ↕

- libcaliptra API    |

- ↕

- Mailbox Interface     |

- ↕

- Runtime Module      |

- ↕

- FMC Module        |

- ↕

- ROM Module        |

- ↕

- Hardware Layer      |

##### Component Interactions

- Hardware peripherals and drivers
- Mailbox interface and external host
- Test infrastructure and various layers

##### Additional Elements

- Build system components
- CI/CD infrastructure
- Test frameworks
- Documentation generation

Remember to emphasize:
##### Test/verification points

This will create a comprehensive view of the Caliptra system while maintaining clarity about its security-focused nature and complex testing infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Define styles
    classDef hardware fill:#b3d9ff,stroke:#333
    classDef firmware fill:#90EE90,stroke:#333
    classDef software fill:#FFE5B4,stroke:#333
    classDef interface fill:#FFB6C1,stroke:#333
    classDef testing fill:#E6E6FA,stroke:#333
    classDef security fill:#FFA07A,stroke:#333

    %% External Host and Software Layer
    subgraph SoftwareLayer
        Host["External Host System"]:::software
        LibCaliptra["libcaliptra API"]:::software
        TestHarness["Test Harness"]:::testing
        BuildTools["Build Tools"]:::software
        SimTools["Simulation/Emulation Tools"]:::software
    end

    %% Interface Layer
    Mailbox["Mailbox Interface"]:::interface

    %% Firmware Layer
    subgraph FirmwareLayer
        Runtime["Runtime Environment"]:::firmware
        FMC["First Mutable Code (FMC)"]:::firmware
        ROM["ROM Module"]:::firmware
        Drivers["Drivers Layer"]:::firmware
        Crypto["Cryptographic Operations"]:::security
    end

    %% Hardware Layer
    subgraph HardwareLayer
        CPU["RISC-V CPU Core"]:::hardware
        HWPeripherals["Hardware Peripherals"]:::hardware
        FPGA["FPGA Implementation"]:::hardware
        Verilator["Verilator Simulation"]:::hardware
        HWModel["Hardware Model"]:::hardware
    end

    %% Testing Infrastructure
    subgraph TestingLayer
        TestInfra["Test Infrastructure"]:::testing
    end

    %% Relationships
    Host --> LibCaliptra
    LibCaliptra --> Mailbox
    Mailbox --> Runtime
    Runtime --> FMC
    FMC --> ROM
    ROM --> CPU
    Runtime --> Drivers
    Drivers --> HWPeripherals
    Drivers --> Crypto
    TestHarness --> LibCaliptra
    TestHarness --> TestInfra
    TestInfra --> FirmwareLayer
    TestInfra --> HardwareLayer
    SimTools --> HWModel
    HWModel --> FPGA
    HWModel --> Verilator

    %% Click events for component mapping
    click CPU "https://github.com/chipsalliance/caliptra-sw/tree/main//cpu/"
    click HWPeripherals "https://github.com/chipsalliance/caliptra-sw/tree/main//hw/1.0/registers/"
    click FPGA "https://github.com/chipsalliance/caliptra-sw/tree/main//hw/fpga/"
    click Verilator "https://github.com/chipsalliance/caliptra-sw/tree/main//hw/verilated/"
    click ROM "https://github.com/chipsalliance/caliptra-sw/tree/main//rom/dev/"
    click FMC "https://github.com/chipsalliance/caliptra-sw/tree/main//fmc/"
    click Runtime "https://github.com/chipsalliance/caliptra-sw/tree/main//runtime/"
    click Drivers "https://github.com/chipsalliance/caliptra-sw/tree/main//drivers/"
    click LibCaliptra "https://github.com/chipsalliance/caliptra-sw/tree/main//libcaliptra/"
    click TestHarness "https://github.com/chipsalliance/caliptra-sw/tree/main//test-harness/"
    click BuildTools "https://github.com/chipsalliance/caliptra-sw/tree/main//builder/"
    click SimTools "https://github.com/chipsalliance/caliptra-sw/tree/main//sw-emulator/"
    click HWModel "https://github.com/chipsalliance/caliptra-sw/tree/main//hw-model/"
    click Mailbox "https://github.com/chipsalliance/caliptra-sw/blob/main//drivers/src/mailbox.rs"
    click Crypto "https://github.com/chipsalliance/caliptra-sw/blob/main//drivers/src/crypto.rs"
    click TestInfra "https://github.com/chipsalliance/caliptra-sw/tree/main//test/"

    %% Legend
    subgraph Legend
        L1["Hardware Component"]:::hardware
        L2["Firmware Component"]:::firmware
        L3["Software Component"]:::software
        L4["Interface Component"]:::interface
        L5["Testing Component"]:::testing
        L6["Security Component"]:::security
    end
```
