Caliptra Subsystem Integration Specification

Version 2.0.1

• Scope
  • Document Version
  • Related repositories & specifications
• Overview
• Caliptra Subsystem High level diagram
• Integration Considerations
  • Design Considerations
  • Verification Considerations
• Verification View of Caliptra Subsystem
  • Memory Requirements
• Caliptra Subsystem Top
  • Parameters & Defines
  • Interfaces & Signals
    • AXI Interface (axi_if)
    • Caliptra Subsystem Top Interface & Signals
  • Integration Requirements
    • Clock
    • Reset
    • Power Good Signal
    • Connecting AXI Interconnect
    • Caliptra Subsystem Reference Register Map
    • FW Execution Control Connections
    • Caliptra Core Reset Control
    • MCU Reset Control
  • SRAM implementation
    • Overview
    • RISC-V internal memory export
    • SRAM timing behavior
    • SRAM parameterization
    • Example SRAM machine check reliability integration
      • Error detection and logging
      • Error injection
      • Caliptra Subsystem error handling flow
  • Programming interface
  • Sequences
  • How to test
• Caliptra Core
• MCU (Manufacturer Control Unit)
  • Overview
    • Parameters & Defines
  • MCU Integration Requirements
  • MCU Core Configuration Customization
  • MCU DCCM SRAM Sizing
  • MCU SRAM MRAC Considerations
    • Split Memory Mapping
    • Side Effect Considerations
    • iCache Considerations
  • MCU Programming interface
    • MCU Linker Script Integration
    • MCU External Interrupt Connections
• Fuse Controller
  • Overview
  • Parameters & Defines
  • Interface
  • Fuse Macro Memory Map and Fuse Controller CSR Address Map
    • SOC_SPECIFIC_IDEVID_CERTIFICATE Usage
  • FC Integration Requirements
  • Direct Access Interface
  • Initialization
  • Programming interface
  • Readout Sequence
  • Sequences: Reset, Boot
  • How to test : Smoke & more
  • Generating the Fuse Partitions
• Fuse Controller Macro
  • Overview
  • Paramteres & Defines
  • FC Macro Integration Requirements
    • Generic Strap Port Usage for FC Register Locations
      • Why These Straps Are Needed
      • Strap Definitions
  • FC Macro Test Interface
• Life Cycle Controller
  • Overview
  • Parameters & Defines
  • Interface
  • Fuse Macro Memory Map / Fuse Controller CSR Address Map
  • LC Integration Requirements
  • Programming Interface
  • Sequences: Reset, Boot
  • How to Test: Smoke & More
    • Smoke Test
    • Functional Tests
    • Advanced Tests
• MCI
  • Overview
  • Parameters & Defines
  • Interface
  • Memory Map / Address map
    • Top Level Memory Map
    • MCU SRAM Memory Map
  • MCI Integration Requirements
    • Error Aggregation Connectivity Requirements
    • Subsystem Internal Fuse Controller Initialization Connectivity Requirements
    • Subsystem Internal Life Cycle Controller Initialization Connectivity Requirements
    • MCI MCU Connectivity Requirements
    • MCI Caliptra Core Connectivity Requirements
    • LCC Gasket Connectivity Requirements
    • MCU SRAM Sizing Requirements
    • MCU MBOX SRAM Sizing Requirements
  • Programming interface
    • MCI Register Spec
    • MCU Mailbox
      • MCU Mailbox Limited Trusted AXI users
      • Reset
      • MCU Mailbox Doorbell Command DLEN
      • MCI Debug Lock Status
      • MCU to SOC Receiver Flow
      • SOC Sender to MCU Flow
      • SOC Sender to SOC Receiver Communication Flow (MCU as intermediary)
    • MCU JTAG/DMI Access
      • MCU SRAM JTAG Access
    • MCU Trace Buffer
    • MCU Halt Ack Interface
  • Sequences : Reset, Boot,
    • MCI Boot Sequencer
      • Breakpoint Flow
      • MCU No ROM Config
      • No Caliptra Core Config
    • Reset Ordering
    • MCU FW Update Flows
      • MCU FW Boot Update
      • MCU Hitless FW Update
      • MCU Warm Reset FW Update
    • Error Flows
  • Other requirements
• I3C core
  • Overview
  • Integration Considerations
  • Parameters and defines
  • Interface
  • I3C Integration Requirements
  • Programming Sequence
    • Programming Sequence from AXI Side
    • Programming Sequence from GPIO Side
  • How to test : Smoke & more
• CDC analysis and constraints
  • Known Issues
  • Analysis of missing synchronizers
  • CDC analysis conclusions
  • CDC constraints
• Reset Domain Crossing
  • Reset Architecture
  • Reset Domain Stamping and Constraints
  • Reset Sequencing
  • RDC Waivers
• Synthesis
  • Recommended LINT rules
    • Known Lint Issue
      • Signal Width Mismatches
      • Undriven signals
• Terminology

Scope

For Caliptra Subsystem, this document serves as a hardware integration specification. The scope of this document is to assist integrators in the integration of Caliptra Subsystem. It is not intended to serve as a hardware specification or to include micro-architectural details. This document includes Caliptra Subsystem top-level details along with parameters, defines, interfaces, memory map, programming reference, and guidelines on how to test the integration of the design.

Document Version

Related repositories & specifications

The components described in this document are either obtained from open-source GitHub repositories, developed from scratch, or modified versions of open-source implementations. Links to relevant documentation and GitHub sources are shared in the following table.

Table 1: Related specification and repositories

| Caliptra | GitHub - chipsalliance/Caliptra| Caliptra Gen 2.0 Specification | Caliptra-SS | GitHub - chipsalliance/caliptra-ss| Hardware Specification Document | Caliptra-rtl | GitHub - chipsalliance/caliptra-rtl | Caliptra RTL documentation | | Cores-VeeR | GitHub - chipsalliance/Cores-VeeR-EL2 | VeeR EL2 Programmer’s Reference Manual | | I3C-Core | GitHub - chipsalliance/i3c-core | I3C core documentation | | Adams Bridge | GitHub - chipsalliance/adams-bridge | Adams Bridge Documentation |

Overview

The Caliptra Subsystem is designed to provide a robust Root of Trust (RoT) for datacenter-class System on Chips (SoCs), including CPUs, GPUs, DPUs, and TPUs. It integrates both hardware and firmware components to deliver essential security services such as identity establishment, measured boot, and attestation. By incorporating the Caliptra Subsystem, integrators can enhance the security capabilities of their SoCs, providing a reliable RoT that meets industry standards and addresses the evolving security needs of datacenter environments.

Caliptra Subsystem High level diagram

The following diagram provides a high-level overview of the Caliptra subsystem. It illustrates the key components and their interconnections within the system. For an in-depth understanding of the Caliptra Subystem refer to Caliptra Subsystem Hardware Specification Document.

Following high-level diagram helps integrators understand the overall architecture and the relationships between different components within the Caliptra subsystem.

Caliptra Subsystem includes:

• Caliptra Core: The Caliptra Core IP. For more information, see Caliptra: A Datacenter System on a Chip (SoC) Root of Trust (RoT).
• MCU (Manufacturer Control Unit): A microcontroller unit that manages various control tasks within the subsystem.
• I3C Core: An interface for connecting and communicating with I3C devices, which are used for providing streaming boot support and communicating with other I3C host controllers.
• Life Cycle Controller: A component that manages the different stages of the subsystem's lifecycle, including initialization, operation, and shutdown.
• Fuse Controller (OTP): A one-time programmable memory controller used for storing critical configuration data and security keys.
• MCI (Manufacturer Control Interface (for MCU)): Manages the communication between the processor and the memory components.
• Memories: Various memory components used for storing data and instructions required by the subsystem.

Integration Considerations

By performing these design and verification tasks, the integrator ensures that the Caliptra Subsystem is properly integrated and can function as intended within the larger system. Several files contain code that may be specific to an integrator's implementation and should be overridden. This overridable code is either configuration parameters with integrator-specific values or modules that implement process-specific functionality. Code in these files should be modified or replaced by integrators using components from the cell library of their fabrication vendor. The following table describes recommended modifications for each file.

Caliptra Core RTL modifications

It is mandatory that any build processes used (e.g. simulation, lint, synthesis) define the Verilog macro CALIPTRA_MODE_SUBSYSTEM, as described in the Caliptra Core Integration Specification. This ensures that Caliptra provides all Subsystem-related features and configuration. Example build scripts provided in the Caliptra Subsystem repository (such as Makefile) demonstrate how this might be performed.

Design Considerations

1. Replace the AXI Interconnect: The subsystem utilizes an AXI-based interconnect to facilitate communication between components, with the Caliptra core connecting via an AXI interface. The integrator must replace the default AXI interconnect component with their proprietary interface. This ensures that the subsystem can communicate effectively with the rest of the subsystem components using the integrator's specific interconnect architecture.
2. Connect the Memories: The integrator must connect the various memory components required by the subsystem. These memory components are used for storing data and instructions necessary for the operation of the Caliptra subsystem.
3. No Changes to Internals: Integrators are not expected to make any changes to the internals of the design. The focus should be on ensuring proper integration and connectivity of the subsystem components.

Verification Considerations

1. Connect the I3C Core GPIO with I3C host driver: The integrator must connect the I3C core (two target I3C devices) to the appropriate driver for the GPIO pins. This connection is crucial for enabling communication with I3C devices, which are used for communication within the subsystem.

Verification View of Caliptra Subsystem

The following block diagram shows details on verification view of Caliptra Subsystem

Memory Requirements

Integrators must instantiate SRAM components outside of the Caliptra Subsystem boundary (see SRAM Implementation for more details). SRAM wrapper logic within the Caliptra Subsystem boundary facilitates the connection to SRAM instances through memory export interfaces in the top-level port list. Integrators must connect the following memory export interfaces to the instantiated SRAM components.

SoC Specific in below table means the size of the memory is not fixed and can be configured based on the design requirements by integrator. The actual size will depend on the specific implementation and configuration of the Caliptra Subsystem.

Caliptra Subsystem Top

The integration of the Caliptra Subsystem begins with the instantiation of the top-level RTL module, caliptra_ss_top.sv. This module serves as the primary entry point for the subsystem and encapsulates all the logic and components required for the functionality of the Caliptra Root of Trust (RoT). All signals must be connected based on the detailed interface and signal descriptions provided in this document. Ensure adherence to the signal direction, width, and functionality to guarantee proper integration with the host SoC.

Parameters & Defines

File at this path in the repository includes parameters and defines for Caliptra Subsystem src/integration/rtl/caliptra_ss_includes.svh

Interfaces & Signals

IMPORTANT NOTE: All signals assumed to by synchronous to cptra_ss_clk_i.

Table: Caliptra SS Straps

AXI Interface (axi_if)

Caliptra Subsystem Top Interface & Signals

Integration Requirements

Clock

The cptra_ss_clk_i signal is the primary clock input for the Caliptra Subsystem.

• Signal Name cptra_ss_clk_i
• Required Frequency 333* MHz to 400 MHz
  • I3C core imposes requirement for minimum operating clock frequency set to 333 MHz or higher to meet 12ns tSCO timing.
  • SoCs that run Caliptra lower than 333 MHz will limit the max I3C SCL frequency. See I3C Phy Spec for more details.
  • This was changed from 170 MHz floor due to CDC issue found in I3C core:
    • I3C Repo CDC Issue
    • Caliptra-SS Repo I3C CDC Issue
• Clock Source Must be derived from the SoC’s clock generation module or a stable external oscillator.
• Integration Notes
  1. Verify that the SoC or system-level clock source provides a stable clock.
  2. The clock signal must be properly buffered if necessary to meet the subsystem's setup and hold timing requirements.
  3. If a different frequency is required, ensure that a clock divider or PLL is used to generate clock before connection.

The cptra_ss_rdc_clk_cg_o output clock is a clock gated version of cptra_ss_clk_i. It is clock gated whenever cptra_ss_rst_b is asserted to avoid RDC issues from the warm reset domain to the cold reset domain/memories.

• Signal Name cptra_ss_rdc_clk_cg_o
• Required Frequency Same as cptra_ss_clk_i.
• Clock Source Caliptra SS MCI clock gater
• Integration Notes
  1. Gated a few clock cycles before cptra_ss_rst_b_o asserted and remains gated until reset is deasserted.
  2. MCU SRAM and MCU MBOX memories shall be connected to this clock to avoid RDC issues.
  3. Clock gating controlled by cptra_ss_warm_reset_rdc_clk_dis_o.
  4. Any SOC logic on a deeper reset domain than CSS can use this clock to resolve RDC issues.

The cptra_ss_mcu_clk_cg_o output clock is a gated version of cptra_ss_clk_i. It is gated whenever cptra_ss_mcu_rst_b_o is asserted to avoid RDC issues within the MCU warm and cold reset domains.

• Signal Name cptra_ss_mcu_clk_cg_o
• Required Frequency Same as cptra_ss_clk_i.
• Clock Source Caliptra SS MCI clock gater
• Integration Notes
  1. Gated a few clock cycles before cptra_ss_mcu_rst_b_o asserted and remains gated until reset is deasserted.
  2. Clock gating controlled by cptra_ss_mcu_fw_update_rdc_clk_dis_o and cptra_ss_warm_reset_rdc_clk_dis_o.
  3. Any SOC logic on a deeper reset domain than MCU can use this clock to resolve RDC issues.

Reset

The cptra_ss_rst_b_i signal is the primary reset input for the Caliptra Subsystem. It must be asserted low to reset the subsystem and de-asserted high to release it from reset. Ensure that the reset is held low for a sufficient duration (minimum of 2 clock cycles) to allow all internal logic to initialize properly.

• Signal Name cptra_ss_rst_b_i
• Active Level Active-low (0 resets the subsystem, 1 releases reset)
• Reset Type Synchronous with the cptra_ss_clk_i signal
• Integration Notes
  • The reset signal must be synchronized to the cptra_ss_clk_i clock to prevent metastability issues.
  • If the reset source is asynchronous, a synchronizer circuit must be used before connecting to the subsystem.
  • During SoC initialization, assert this reset signal until all subsystem clocks and required power domains are stable.
  • It is illegal to only toggle cptra_ss_rst_b_i until both Caliptra and MCU have received at least one FW update. Failure to follow this requirement could cause them to execute out of an uninitialized SRAM.
  • SOC should assert cptra_ss_reset_b_i after cptra_ss_mcu_halt_status_o is asserted to guarantee MCU is idle. This will guarantee no outstanding AXI transactions from MCU and help avoid RDC issues.

The cptra_ss_rst_b_o is a delayed version of cptra_ss_rst_b_i to ensure cptra_ss_rdc_clk_cg_o is gated before reset is asserted. This reset is needed for the purpose of RDC between the warm reset domain and the cold reset/memory domain.

• Signal Name cptra_ss_rst_b_o
• Active Level Active-low (0 resets the subsystem, 1 releases reset)
• Reset Type Synchronous with the cptra_ss_rdc_clk_cg_o signal
• Integration Notes
  1. SOCs shall use this reset for any memory logic connected to MCU SRAM or MCU MBOX to avoid RDC corruption of the memories.
  2. It is recommended to be used for SOC AXI interconnect if it is on the same reset domain as Caliptra SS to avoid RDC issues.
  3. SOC logic on cptra_ss_rst_b_i domain and transitions into a deeper reset domain can use this reset paired with cptra_ss_rdc_clk_cg_o to avoid RDC issues.

Power Good Signal

The cptra_ss_pwrgood_i signal serves as an indicator of stable power for the Caliptra Subsystem. When asserted (1), it confirms that power is stable and the subsystem can operate normally. When deasserted (0), the signal triggers a hard reset of the subsystem. Deassertion must be synchronized to cptra_ss_clk_i to avoid metastability issues.

• Signal Name cptra_ss_pwrgood_i
• Active Level Active-high (1 indicates stable power, 0 triggers reset)
• Assertion Type Asynchronous
• Deassertion Type Synchronous to cptra_ss_clk_i
• Integration Notes
  1. Ensure cptra_ss_pwrgood_i is properly generated by the power management unit or system power controller.
  2. Since assertion is asynchronous, it must be immediately driven high once power is stable.
  3. Use a synchronizer to properly align deassertion with cptra_ss_clk_i to prevent glitches.
  4. If cptra_ss_pwrgood_i remains low, the Caliptra Subsystem will remain in a hard reset state.

Connecting AXI Interconnect

Integrator must connect following list of manager and subordinates to axi interconnect.

• List of AXI Manager connections to AXI interconnect.

• AXI USER width is 32-bits for all AXI interfaces in the Caliptra Subsystem. Only the Address User signals are used (ARUSER and AWUSER) for secure access filtering. Other USER signals are either tied to 0 or not used (WUSER, RUSER, BUSER). ARUSER and AWUSER must be passed unmodified through the AXI interconnect to all AXI subordinates in the Subsystem. Each logic block inside the Subsystem is responsible for performing its own AXI User filtering based on access privileges. AXI interconnect is only responsible for passing the unmodified signals along with the transaction requests, not for performing any access filtering.

• AXI ID width at each MCU manager interface must not be modified from the configured values. ID width for each of the MCU AXI Manager interfaces is defined by the <IF_NAME>_BUS_TAG parameter from this file: css_mcu0_el2_param.vh. Port connections may be seen in mcu_top.sv. ID Width of the Caliptra DMA AXI Manager interface is defined in soc_ifc_pkg.sv.

  • IFU_BUS_TAG: 3. Interconnect should support ID values 0-7.
  • LSU_BUS_TAG: 3. Interconnect should support ID values 0-7.
  • SB_BUS_TAG: 1. Interconnect should support ID values 0,1.
  • CPTRA_AXI_DMA_ID_WIDTH: 5. ID signals are tied to constant 0.

• For each AXI subordinate interface in the Subsystem the following table shows ID WIDTH default value, file to review for the configured definition, and any support for configurability. | Interface | Default ID WIDTH | Reference File | Description | | ----------- | ------------------ | ---------------------------------- | ---------------------------------------------------------------- | | cptra_ss_cptra_core_s_axi_if | 8 | config_defines.svh | Default value of 8 is controlled using the macro CALIPTRA_AXI_ID_WIDTH. | | cptra_ss_mcu_rom_s_axi_if | 8 | config_defines.svh | Default value of 8 is controlled using the macro CALIPTRA_AXI_ID_WIDTH. | | cptra_ss_mci_s_axi_if | 8 | caliptra_ss_top.sv | ID_WIDTH value is derived from the width of AxID signals in the connected AXI interface. | | cptra_ss_i3c_s_axi_if | 8 | i3c_defines.svh | Default value of 8 is controlled using the macro AXI_ID_WIDTH. | | cptra_ss_lc_axi_wr, cptra_ss_lc_axi_rd | 8 | src/tlul/rtl/tlul_pkg.sv | Default value is derived from the macro CALIPTRA_AXI_ID_WIDTH, overrideable using the macro CALIPTRA_SS_TLUL_AXI_ID_WIDTH. | | cptra_ss_otp_core_axi_wr, cptra_ss_otp_core_axi_rd | 8 | src/tlul/rtl/tlul_pkg.sv | Default value is derived from the macro CALIPTRA_AXI_ID_WIDTH, overrideable using the macro CALIPTRA_SS_TLUL_AXI_ID_WIDTH. |

• AXI subordinates in the Subsystem may accept up to 2 Read and 2 Write requests in total, but each request is serviced in order and responses are provided in order. Integrators may configure the interconnect to issue 1 or 2 outstanding transactions, but are recommended to configure only a single outstanding request at a time for area (buffer) optimizations in the interconnect and because there is no significant performance improvement by queueing multiple requests.

• Subordinate Address Map requirements

  • The MCU is configured with several internal address assignments that must not be used when assigning SOC addresses for AXI subordinates on the AXI interconnect. The following table shows these restricted regions:

• Subordinate Address Map (reference only) / List of sub connected to Interconnect

  • The following address map is a suggested address map for subordinates for the subsystem design. It details the memory layout and the connections between different components within the Caliptra subsystem.

• Following are the header files path for the below suggested address map. These files would be useful in defining the address map using the given RDL Files.

  • soc_address_map.h
  • soc_address_map_defines.svh

Caliptra Subsystem Reference Register Map

Caliptra Subsystem Reference Register Map. Please note, any addresses are for the example purpose only.

FW Execution Control Connections

FW Execute Control is typically controlled by Caliptra. This means cptra_ss_cptra_generic_fw_exec_ctrl_2_mcu_o should be looped back and directly connected to cptra_ss_cptra_generic_fw_exec_ctrl_2_mcu_i. If the SOC decided to not use Caliptra Core, the SOC must drive cptra_ss_cptra_generic_fw_exec_ctrl_2_mcu_i the same way Caliptra Core drives this signal.

1. On same reset at MCI
2. Synchronous to MCI clock domain
3. 1 indicates FW patch is valid in the MCU SRAM
4. 0 indicates FW patch is invalid and will request MCU to reset itself See Hitless Update Flow to understand exactly when this signal shall be set/cleared in the hitless FW flow.

Caliptra Core Reset Control

Typically Caliptra reset is directly controlled by MCI. This means cptra_ss_mci_cptra_rst_b_o is directly looped back to cptra_ss_mci_cptra_rst_b_i.

If an SOC wants to keep Caliptra in reset they can tie off cptra_ss_mci_cptra_rst_b_i and not user cptra_ss_mci_cptra_rst_b_o.

If an SOC wants to modify Caliptra reset they can do so by adding additional logic to the above signals.

NOTE: Caliptra SS RDC and CDC are only evaluated when the MCI control is looped back to Caliptra. Any modification to this reset control requires a full RDC and CDC analysis done by the SOC integration team.

MCU Reset Control

Typically MCU reset is directly controlled by MCI. This means cptra_ss_mcu_rst_b_o is directly looped back to cptra_ss_mcu_rst_b_i.

The SOC can choose to delay the MCU reset deassertion. The SOC should be aware that MCU clock enable is based off cptra_ss_mcu_rst_b_o.

If the SOC wants to delay assertion of MCU reset this can be done, but integrators need to be aware the MCU reset counter (MIN_MCU_RST_COUNTER_WIDTH) starts counting when cptra_ss_mcu_rst_b_i asserts. Meaning MCU could be in reset for shorter than expected. To resolve this issue the SOC should implement their own reset counter to delay the reset deassertion.

Arbitrary reset assertions/deassertions should not be done unless the integrator understands exactly what they are doing. This can cause RDC issues within Caliptra SS.

NOTE: Caliptra SS RDC and CDC are only evaluated when MCU reset is looped back. Any modification to this reset control requires a full RDC and CDC analysis done by the SOC integration team.

SRAM implementation

Overview

SRAMs are instantiated at the SoC level. Caliptra Subsystem provides the interface to export SRAMs from internal components. Components that export SRAMs include:

• Caliptra Core (see Caliptra Core integration specification)
• MCU (RISC-V core)
• MCI (Mailbox SRAM and MCU SRAM)

SRAM repair logic (for example, BIST) and its associated fuses, which is proprietary to companies and their methodologies, is implemented external to the Caliptra Subsystem boundary.

SRAMs must NOT go through BIST or repair flows across a “warm reset”. SoC shall perform SRAM repair during a powergood cycling event ("cold reset") and only prior to deasserting cptra_ss_rst_b_i. During powergood cycling events, SoC shall also initialize all entries in the SRAM to a 0 value prior to deasserting cptra_ss_rst_b_i. This requirement can not be completed by MCU (or any other components in Subsystem) because it is a function of the proprietary SRAM management logic.

MCU mailbox and executable SRAMs are implemented with ECC protection. Data width for the mailbox is 32-bits, with 7 parity bits for a Hamming-based SECDED (single-bit error correction and double-bit error detection).

RISC-V internal memory export

To support synthesis flexibility and ease memory integration to various fabrication processes, all SRAM blocks inside the RISC-V cores (Caliptra Core and MCU) are exported to an external location in the testbench. A single unified interface connects these memory blocks to their parent logic within the RISC-V core. Any memory implementation may be used to provide SRAM functionality in the external location in the testbench, provided the implementation adheres to the interface requirements connected to control logic inside the processor. Memories behind the interface are expected to be implemented as multiple banks of SRAM, from which the RISC-V processor selects the target using an enable vector. The I-Cache has multiple ways, each containing multiple banks of memory, and SOC SRAM implementations for I-Cache must be compatible with the exported interface.

The following memories are exported:

• Instruction Closely-Coupled Memory (ICCM) (Caliptra Core only)
• Data Closely Coupled Memory (DCCM) (Caliptra Core and MCU)
• Instruction Cache (I-Cache) (MCU only)

SRAM timing behavior

• [Writes] SRAM input wren signal is asserted simultaneously with input data and address. Input data is stored at the input address 1 clock cycle later.
• [Reads] SRAM input clock enable signal is asserted simultaneously with input address. Output data is available 1 clock cycle later from a flip-flop register stage.

The following figure shows the SRAM interface timing.

Figure: SRAM interface timing

SRAM parameterization

Parameterization for ICCM/DCCM/I-Cache memories is derived from the configuration of the VeeR RISC-V core that has been selected for Caliptra Subsystem integration. Parameters defined in the VeeR core determine signal dimensions at the Subsystem top-level interface and drive requirements for SRAM layout. For details about interface parameterization, see the Interfaces & Signals section.

Example SRAM machine check reliability integration

This section describes an example implementation of integrator machine check reliability.

This example is applicable to scenarios where an integrator may need control of or visibility into SRAM errors for purposes of reliability or functional safety. In such cases, integrators may introduce additional layers of error injection, detection, and correction logic surrounding SRAMs. The addition of such logic is transparent to the correct function of Caliptra Subsystem, and removes integrator dependency on Caliptra Subsystem components for error logging or injection.

Note that the example assumes that data and ECC codes are in non-deterministic bit-position in the exposed SRAM interface bus. Accordingly, redundant correction coding is shown in the integrator level logic (i.e., integrator_ecc(caliptra_data, caliptra_ecc)). If the Caliptra Subsystem data and ECC are deterministically separable at the Caliptra Subsystem interface, the integrator would have discretion to store the ECC codes directly and calculate integrator ECC codes for the data alone.

Figure: Example machine check reliability implementation

Error detection and logging

1. Caliptra Subsystem IP shall interface to ECC protected memories.
2. Caliptra Subsystem IP calculates and applies its own ECC code, which produces a total of 39-bit data written to external or INTEGRATOR instantiated SRAMs.
3. Each 39-bit bank memory internally calculates 8-bit ECC on a write and stores 47 bits of data with ECC into SRAM.
4. On read access syndrome is calculated based on 39-bit data.
5. If parity error is detected and syndrome is valid, then the error is deemed single-bit and correctable.
6. If no parity error is detected but syndrome == 0 or the syndrome is invalid, the error is deemed uncorrectable.
7. On both single and double errors, the read data is modified before being returned to Caliptra Subsystem.
8. Since single-bit errors shall be corrected through INTEGRATOR instantiated logic, Caliptra Subsystem never sees single-bit errors from SRAM.
9. Double-bit or uncorrectable errors would cause unpredictable data to be returned to Caliptra Subsystem. Since this condition shall be detected and reported to MCRIP, there is no concern or expectation that Caliptra Subsystem will operate correctly after a double error.
10. On detection, single errors are reported as transparent to MCRIP, double errors are reported as fatal.
11. Along with error severity, MCRIP logs physical location of the error.
12. After MCRIP logs an error, it has a choice to send out in-band notification to an external agent.
13. MCRIP logs can be queried by SoC software.

Error injection

1. MCRIP supports two error injection modes: intrusive and non-intrusive.
2. Intrusive error injection:
   1. Can force a single or double error to be injected, which would result in incorrect data to be returned on read access.
   2. The intrusive error injection mode is disabled in Production fused parts via Security State signal.
3. Non-intrusive error injection:
   1. Allows external software to write into MCRIP error log registers.
   2. The non-intrusive error injection does not interfere with the operation of memories.
   3. The non-intrusive error injection is functional in Production fused parts.

Caliptra Subsystem error handling flow

1. Any implementation of error and recovery flows must adhere to the error handling requirements specified in Caliptra.md
2. See MCI error handling for more details on MCI error infrastructure and error handling in Caliptra Subsystem.
3. SoC level reporting and handling of fatal & non-fatal errors is product-specific architecture, outside the scope of Caliptra Subsystem definition. For example, a CPU and a PCIe device may handle fatal and non-fatal errors differently.

Programming interface

There are two primary programming avenues to interface with the Caliptra Subsystem:

1. MCU Firmware

   • Description: This method involves programming the Microcontroller Unit (MCU) to execute firmware.
   • Details: For more information on how to program the MCU and execute firmware via the MCU, please refer to the MCU Programming Interface documentation.

2. Caliptra Firmware

   • Description: This method involves programming the Caliptra Core to execute firmware.
   • Details: For more information on how to program and execute Caliptra Core firmware, please refer to the Caliptra Core References and Related Specifications.

Sequences

Reset Sequence:

• De-assert cptra_ss_rst_b_i after the primary clock (clk_i) stabilizes.

How to test

Reference tests are available at caliptra-ss\src\integration\test_suites

Caliptra Core

Follow the link for Caliptra Core Integration Specification

MCU (Manufacturer Control Unit)

Overview

MCU is encapsulates VeeR EL2 core that includes an iCache, a dedicated DCCM, and AXI interfaces with separate AXI USER IDs to ROM and MCI. For more details refer to RISCV VeeR-EL2 Overview

Parameters & Defines

The VeeR EL2 core instance used for MCU has been configured with these options:

• DCCM size: 16KiB (see MCU DCCM SRAM Sizing)
• I-Cache depth: 16KiB
• ICCM: Disabled
• External Interrupt Vectors: 255

The following files from the Caliptra Subsystem repository contain the MCU configuration. Review these files for comprehensive list of MCU capabilities.
src/riscv_core/veer_el2/rtl/defines/css_mcu0_common_defines.vh
src/riscv_core/veer_el2/rtl/defines/css_mcu0_el2_param.vh
src/riscv_core/veer_el2/rtl/defines/css_mcu0_el2_pdef.vh
src/riscv_core/veer_el2/rtl/defines/defines.h

MCU Integration Requirements

• Ensure Proper Memory Mapping

  • The memory layout must match the physical memory configuration of the SoC.
  • If modifications are required, update the base addresses and section placements accordingly.
  • The address regions assigned to PIC and DCCM must not include any other AXI subordinates on the interconnect.

• Enabling Programming interface.

  • Please refer to section MCU Programming Interface for details on reference linker file for the MCU bringup.

MCU Core Configuration Customization

The MCU VeeR-EL2 core can be customized by integrators to optimize for specific SoC requirements.

Common Use Cases:

• Memory Architecture: Modify ICCM/DCCM addresses and sizes for SoC memory integration
• Power/Area Optimization: Remove or modify features (caching, number of interrupts)
• Performance Tuning: Adjust cache sizes and pipeline configurations for application workloads

Configuration Instructions:

Refer to the MCU Veer-EL2 Core Configuration section in the project README for complete step-by-step procedures.

Validation:

Execute the full regression test suite documented in How to test after any configuration changes to ensure system compatibility.

MCU DCCM SRAM Sizing

MCU's DCCM SRAM should be sized large enough to accommodate FW's stack and heap. If it is undersized, the MCU would have to rely on the MCU SRAM (accessed via AXI) for the stack/heap which has much lower performance.

MCU SRAM MRAC Considerations

The MCU's Memory Region Access Control (MRAC) regions are hard coded to 256MB boundaries. Each 256MB region is configured with uniform attributes - everything within a region is labeled as either "side effect" or "cacheable". This affects how MCU SRAM and MCU MBOX SRAM (both located within MCI) should be integrated into the SoC memory map, as different components within MCI may require different access attributes.

Split Memory Mapping

Integrators have two main approaches for handling MCI memory mapping:

Option 1: Contiguous MCI Address Region - If integrators don't care about the MRAC limitations described in the following sections, they can use a standard contiguous MCI address map where all MCI components (including MCU SRAM and MCU MBOX SRAM) reside within a single 256MB region.

Option 2: Split Memory Mapping - Integrators can optionally split MCU SRAM and MCU MBOX SRAMs into their own dedicated 256MB regions, separate from other MCI components. This allows firmware to enable caching or disable side effects for these specific SRAMs.

Side Effect Considerations

When MCU SRAM and MCU MBOX SRAM remain within the main MCI address space (not split off), integrators should consider the following access limitations:

DWORD Access Requirement: MCI peripherals (MCI CSRs, MCU trace buffer CSRs, etc) require "side effect" attribute enabled. When "side effect" is enabled dword-aligned accesses are required. Unaligned accesses, like accessing a uint8_t, are not permitted and will result in a read fault error in the MCU.

If you want to avoid these DWORD alignment limitations and allow more flexible access patterns, you can choose to implement the Split Memory Mapping (Option 2) in your AXI interconnect for MCU SRAM and/or MCU MBOX SRAM. This allows the SRAMs to be placed in regions without the side effect attribute.

iCache Considerations

When MCU SRAM remains within the main MCI address space (not split off), integrators should consider the following caching limitations:

iCache Enablement Requirement: To enable MCU iCache, everything within the 256MB boundary containing MCU SRAM must be cacheable. Since not all regions of MCI are cacheable, MCU iCache cannot be enabled when using a contiguous MCI address map.

If you want to enable MCU iCache functionality, you must implement the Split Memory Mapping (Option 2) in your AXI interconnect. This allows MCU SRAM to be placed in a dedicated cacheable region separate from other MCI components.

MCU Programming interface

MCU Linker Script Integration

This linker script defines the memory layout for the MCU firmware. It specifies the placement of various sections, ensuring proper memory mapping and execution flow.

Example Linker File can be found at : integration/test_suite/libs/riscv_hw_if/link.ld

By following this linker script configuration, the validation firmware can be correctly mapped and executed within the Caliptra Subsystem. Memory mapping for the validation firmware follows these principles:

• Instructions are stored in ROM for initial boot (.text)
• Read-only data is stored in ROM
• Stack and data sections are allocated to DCCM
• MCU SRAM is used for any combination of instructions and data to demonstrate program execution, data storage and persistence, streaming boot operations, and region protections that are enforced by MCI. Test firmware and corresponding linker scripts may be found in the repository test suites directory.

MCU External Interrupt Connections

Fuse Controller

Overview

The Fuse Controller is a core component in the secure infrastructure of the system, responsible for managing the fuses and ensuring the integrity, consistency, and secure storage of sensitive data. It provides essential interfaces for direct fuse programming. The Fuse Controller interacts closely with the Lifecycle Controller (LC), FUSE macros, MCI, and Caliptra Core.

For an in-depth understanding of the Fuse Controller's functionality, including its programming flow, refer to Caliptra Subsystem Hardware Specification Document.

Parameters & Defines

Interface

Fuse Macro Memory Map and Fuse Controller CSR Address Map

The Caliptra Subsystem fuse controller supports a flexible and extensible memory map for storing one-time programmable (OTP) data. This structure is documented in the following files: See Fuse Controller Register Map for registers. See Fuse Macor Memory Map for fuse partition map.

The current fuse memory map consists of three main architectural segments: Caliptra-Core (prefix: CALIPTRA_CORE), Caliptra-Subsystem (prefix: CALIPTRA_SS), SoC/Vendor-Specific.

This structure enables separation of responsibilities and flexibility in SoC integration. While the Caliptra-Core fuse items are mandatory and must adhere to the Caliptra Fuse Map Specification, Caliptra-Subsystem fuses are required only when the subsystem is instantiated with Caliptra Subsystem. These Caliptra Subsystem fuses can also be configured based on SoC requirements. The SoC/Vendor-specific items can be customized based on integrator needs and product requirements. Therefore, the fields under SoC-specific categories can be resized or eliminated if unused.

SOC_SPECIFIC_IDEVID_CERTIFICATE Usage

This field defaults to 4 bytes but can be extended to accommodate storage of a full IDevID hybrid certificate (e.g., ML-DSA + ECC) if desired. Integrators must adjust its size in the YAML config used by the generation script.

FC Integration Requirements

Connectivity, Clock & Reset, Constraints & Violations

1. Connectivity:

   • The Fuse Controller must interface seamlessly with the Fuse Macros, ensuring proper ECC support during programming and read operations.
   • All AXI interfaces (core_axi_wr_req, core_axi_rd_req) must follow the protocol specifications.
   • Inputs like lc_otp_program_i and pwr_otp_i should connect properly to the Lifecycle Controller (LC) and MCI respectively.
   • Alerts must propagate correctly to the system's alert manager for error handling.

2. Constraints & Violations:

   • Any access to fuses must be gated by the FUSE_CTRL_DIRECT_ACCESS_REGWEN bit to prevent unauthorized writes.
   • There are some fuses that can be programmed only by Caliptra Core. Therefore, each AXI write should follow the access permission rule defined by access_control_table in src/fuse_ctrl/rtl/otp_ctrl_pkg.sv.
   • Timeout conditions during consistency checks (FUSE_CTRL_CHECK_TIMEOUT) should trigger appropriate alerts.
   • Errors like invalid data, ECC failures, or access violations should raise alerts via the alerts signal.

3. Scan Path Exclusions:

   • Ensure that secret fuse fields (UDS and Field-Entropy) and their corresponding flip-flops are not a parth of the scan path. Specifically, in this version, there are five OTP partitions that contain secrets that must not be leaked:
     • SECRET_MANUF_PARTITION: that contains the UDS seed, and
     • SECRET_PROD_PARTITION_{0,1,2,3}: that each contain field entropy. These fuse partitions are "Buffered" partitions, meaning they are sensed at power-on and buffered in flip-flops until the next reset. During SoC integration it is vital to exclude the buffering flops that hold sensitive secret data from the scan chain to avoid leaks. These buffering flops may be excluded from the scan chain by excluding the following hierarchies: **::u_otp_ctrl::u_part_buf::u_otp_ctrl_ecc_reg::gen_partitions[X]::gen_buffered::u_part_buf::u_otp_ctrl_ecc_reg::**, for all values of X in 1–5, since indices 1–5 map to the sensitive partitions mentioned above (defined in the PartInfo localparam in otp_ctrl_part_pkg.sv, autogenerated from the OTP memory map HJSON). Additionally, these secrets are broadcasted with this input port: otp_broadcast_o. Therefore, this port, its propagated signals, and its driver signals must also not be scannable.

• Since Fuse Controller scrambles secret partition with PRESENT chipher, this chiper keys, autogenerated from the OTP memory map HJSON, must be excluded from the scan path. Although these values are parameters defined in otp_ctrl_part_pkg.sv, the registers driven by these parameters must be excluded from the scan path.
• Note, the LC token partitions are not considered secret as only the cSHAKE128 hashes of each token are stored, not the raw tokens themselves.

Direct Access Interface

Fuse macros has to be programmed via the Direct Access Interface, which is comprised of the following CSRs:

Initialization

The OTP controller initializes automatically upon power-up and is fully operational by the time the processor boots. The only initialization steps that SW should perform are:

1. Check that the OTP controller has successfully initialized by reading STATUS. I.e., make sure that none of the ERROR bits are set, and that the DAI is idle (STATUS.DAI_IDLE).
   • Choose whether the periodic background checks shall be subject to a timeout by programming a nonzero timeout cycle count to CHECK_TIMEOUT. In this case, the CHECK_TIMEOUT register must be set before the INTEGRITY_CHECK_PERIOD and CONSISTENCY_CHECK_PERIOD registers (see next point).
   • Enable periodic background checks by programming nonzero mask values to INTEGRITY_CHECK_PERIOD and CONSISTENCY_CHECK_PERIOD.
   • It is recommended to lock down the background check registers via CHECK_REGWEN, once the background checks have been set up

If needed, one-off integrity and consistency checks can be triggered via CHECK_TRIGGER. If this functionality is not needed, it is recommended to lock down the trigger register via CHECK_TRIGGER_REGWEN.

Programming interface

The Fuse Controller (FC) programming interface is designed to manage lifecycle states, handle fuses with ECC support, and ensure secure interactions with the fuse macros. A key component in this architecture is the Fuse Controller Filter RTL. This module intercepts and verifies the fuse programming sequence by checking that all parts of the transaction originate from the same authorized source. In doing so, the filter guarantees that fuse provisioning is performed in an atomic manner.

Atomic fuse provisioning means that only one entity can initiate the programming sequence at a time. The entire sequence—data write, address write, and command write—must complete successfully. If any phase fails or if an inconsistency is detected (for example, if the AXI user ID changes between phases), the operation is aborted, and a cold reset is required before any new programming attempt can be made.

The access control table, which defines allowed fuse address ranges along with the corresponding authorized AXI user IDs. See access_control_table in src/fuse_ctrl/rtl/otp_ctrl_pkg.sv.

Below are the key operations supported by the programming interface:

1. Direct Access Interface (DAI):

   • Registers:
     • FUSE_CTRL_DIRECT_ACCESS_CMD: Specifies the operation (FUSE_CTRL_CMD_DAI_WRITE for write, FUSE_CTRL_CMD_DAI_READ for read).
     • FUSE_CTRL_DIRECT_ACCESS_ADDRESS: Specifies the fuse memory address to access.
     • FUSE_CTRL_DIRECT_ACCESS_WDATA_0: Write data (32-bit granularity).
     • FUSE_CTRL_DIRECT_ACCESS_WDATA_1: Write data for 64-bit operations.
     • FUSE_CTRL_DIRECT_ACCESS_RDATA_0: Read data (32-bit granularity).
     • FUSE_CTRL_DIRECT_ACCESS_RDATA_1: Read data for 64-bit operations.
   • Procedure:
     • Write the address to FUSE_CTRL_DIRECT_ACCESS_ADDRESS.
     • For write operations:
       • Populate FUSE_CTRL_DIRECT_ACCESS_WDATA_0 (and FUSE_CTRL_DIRECT_ACCESS_WDATA_1 for 64-bit operations).
     • Set the command in FUSE_CTRL_DIRECT_ACCESS_CMD.
     • Wait for the operation to complete by polling the DAI_IDLE bit in FUSE_CTRL_STATUS.
   • ECC Support:
     • ECC is automatically applied during programming to ensure data integrity.

2. Digest Calculation:

   • Used to lock a partition after programming is complete.
   • Registers:
     • FUSE_CTRL_DIRECT_ACCESS_CMD: Use command 0x4 for digest calculation.
     • FUSE_CTRL_DIRECT_ACCESS_ADDRESS: Partition base address.
   • Procedure:
     • Write the partition base address to FUSE_CTRL_DIRECT_ACCESS_ADDRESS.
     • Trigger the digest calculation command (0x4) in FUSE_CTRL_DIRECT_ACCESS_CMD.
     • Poll the DAI_IDLE bit in FUSE_CTRL_STATUS to confirm the operation is complete.

Readout Sequence

A typical readout sequence looks as follows:

• Check whether the DAI is idle by reading the STATUS register.
• Write the byte address for the access to DIRECT_ACCESS_ADDRESS. Note that the address is aligned with the granule, meaning that either 2 or 3 LSBs of the address are ignored, depending on whether the access granule is 32 or 64bit.
• Trigger a read command by writing 0x1 to DIRECT_ACCESS_CMD.
• Poll the STATUS until the DAI state goes back to idle. Alternatively, the otp_operation_done interrupt can be enabled up to notify the processor once an access has completed.
• If the status register flags a DAI error, additional handling is required.
• If the region accessed has a 32bit access granule, the 32bit chunk of read data can be read from DIRECT_ACCESS_RDATA_0. If the region accessed has a 64bit access granule, the 64bit chunk of read data can be read from the DIRECT_ACCESS_RDATA_0 and DIRECT_ACCESS_RDATA_1 registers.
• Go back to the first step and repeat until all data has been read.

The hardware will set DIRECT_ACCESS_REGWEN to 0x0 while an operation is pending in order to temporarily lock write access to the CSRs registers.

Sequences: Reset, Boot

1. Reset Sequence:

   • De-assert rst_ni after the primary clock (clk_i) stabilizes.
   • Verify reset state by reading FUSE_CTRL_STATUS. All errors in the status register should be 0.
   • Ensure Fuse Macros are in their default state after reset.

2. Boot Sequence:

   • Initialize Fuse Macros by programming essential fuses using the programming interface.
   • Perform a full integrity check by triggering FUSE_CTRL_CHECK_TRIGGER and ensure the system is error-free before proceeding.
   • Validate readiness by checking the FUSE_CTRL_STATUS register.

How to test : Smoke & more

The smoke test focuses on ensuring basic functionality and connectivity of the FC & LCC. TODO More details will be provided once FC is ready to test.

Generating the Fuse Partitions

The configurable parts of the fuse_ctrl, specifically the fuse map and register interface, are bootstrapped through a separate script ./tools/scripts/fuse_ctrl_script/gen_fuse_ctrl_partitions.py. For a detailed breakdown of the design rationale behind the script as well as execution instructions, refer to Fuse Map Generation Script.

Fuse Controller Macro

The following integration section is based on the Generalized Open-source Interface with modifications to match the Caliptra implementation.

Overview

The Fuse Controller Macro implements a generalized open-source interface for functional operation (described below). Any OTP redundancy mechanism like per-word ECC is assumed to be handled inside the wrapper, which means that the word width exposed as part of the generalized interface is the effective word width.

Paramteres & Defines

FC Macro Integration Requirements

The generalized open-source interface is a simple command interface with a ready / valid handshake that makes it possible to introduce back pressure if the OTP macro is not able to accept a command due to an ongoing operation.

In order to facilitate the scrambling and digest operations, the data width has been sized such that data blocks up to the PRESENT block size (64bit) can be transferred across the generalized interface. The actual size of a transfer is determined via the size_i field. Transfer sizes are specified in multiples of the native OTP block size, as listed below.

Responses are returned in-order via an unidirectional response interface (i.e., without back pressure capability). Downstream logic must be able to sink the response in any case. The response optionally carries read data, depending on whether the operation that took place was a read or not. Also, an error signal returns a non-zero error code in case an error occurred while carrying out the OTP command.

The signals pertaining to the generalized open-source interface are listed below. The signals are exposed as cptra_ss_fuse_macro_outputs_i and cptra_ss_fuse_macro_inputs_o at the top level.

The write raw and read raw command instructs the Fuse Controller Macro wrapper to store / read the data in raw format without generating nor checking integrity information. That means that the wrapper must return the raw, uncorrected data and no integrity errors.

The Fuse Controller Macro wrapper implements the error codes (0x0 - 0x4).

The timing diagram below illustrates the timing of a command. Note that both read and write commands return a response, and each command is independent of the previously issued commands. The latency from accepting a command to returning a response depends on the underlying OTP IP and is typically larger than 10 cycles. The returned values depend on the command type and whether an error occurred or not.

Note that the default configuration of the Fuse Controller allows up to two outstanding OTP commands, meaning that it is permissible to acknowledge an incoming command and start working on it while the results of the last command are still in the process of being output (e.g., due to an output register stage).

The Fuse Controller Macro uses the following signals to interface with the Fuse Controller.

Generic Strap Port Usage for FC Register Locations

To support flexible integration across varying fuse partition generations, Caliptra ROM uses two generic strap ports to locate fuse controller registers.

Why These Straps Are Needed

Each fuse partition generation introduces new error bits into the status register. This causes the idle bit to shift leftward, changing its position within the SOC_OTP_CTRL_STATUS register. Similarly, the CMD register may shift downward in memory if new fuse partition definitions introduce additional registers like ADDR, WDATA0, RDATA0, etc.

Because of these dynamic shifts:

• The idle bit location cannot be hardcoded.
• The CMD register address must be explicitly provided, even though the other fuse controller registers are laid out consecutively.

Strap Definitions

• cptra_ss_strap_generic_0_i A 32-bit input strap that encodes:

  • Upper 16 bits: Bit index of the idle status bit (IDLE_BIT_STATUS) within SOC_OTP_CTRL_STATUS.
  • Lower 16 bits: Offset address of SOC_OTP_CTRL_STATUS within the SOC_IFC_REG space, relative to SOC_OTP_CTRL_BASE_ADDR.

  This allows the ROM to accurately monitor the fuse controller's idle state regardless of partition-induced shifts.

• cptra_ss_strap_generic_1_i A 32-bit input strap that provides the address of the CMD register. Since the fuse controller registers are laid out consecutively, specifying the CMD register is sufficient for the ROM to infer the locations of adjacent registers like ADDR, WDATA0, and RDATA0.

FC Macro Test Interface

The Fuse Controller Macro requires a test interface to be able to access the underlying OTP debug access interface and power manager controller. During early manufacturing, the test interface can be used to run BIST and repair flows before performing a non-volatile raw unlock operation.

For security reasons, it must be ensured that it is not possible to read / program arbitrary OTP memory locations through the test interface. Only specific, pre-defined test locations shall be readable and programmable. Access to debug access interface must also be disabled once the device is in mission mode (i.e. PROD life cycle state).

Life Cycle Controller

Overview

The LC Controller (Lifecycle Controller) is a critical component of the Caliptra Subsystem, responsible for securely managing the lifecycle states of the chip. The LC Controller interacts with other subsystems such as the Fuse Controller, MCI, AXI interconnect, and JTAG TAP to enforce secure transitions, validate tokens, and generate error conditions. Additionally, it implements escalation mechanisms to respond to security breaches, enabling the chip to enter secure states like SCRAP.

For a detailed description of the Lifecycle Controller's architecture, design, and operational flow, refer to Caliptra Subsystem Hardware Specification Document.

Parameters & Defines

Interface

Fuse Macro Memory Map / Fuse Controller CSR Address Map

See Life-cycle Controller Register Map.

LC Integration Requirements

Connectivity, Clock & Reset, Constraints & Violations

1. Connectivity:

   • Ensure proper routing of all signals to avoid conflicts with other modules.
   • Interfaces like jtag and axi must adhere to the defined protocol specifications.
   • Escalation signals (esc_scrap_state0 and esc_scrap_state1) brings LC controller into temporal SCRAP mode (Escalation state) and therefore needs to be connected to a dedicated controller.
   • Allow_RMA_or_SCRAP_on_PPD needs to be tied 0 if it is not being used. Otherwise, it might break LC controller's internal FSM.
   • Avoid glitches on Allow_RMA_or_SCRAP_on_PPD and escalation inputs (esc_scrap_state0, esc_scrap_state1) that could cause unintended transitions.
   • Verify that all output signals, including alerts, remain within the expected ranges under normal operation.

2. IMPORTANT SOC REQUIREMENT:

   • Life cycle controller allows you to switch from internal to external clock on a request from SOC over JTAG or AXI (As explained in other sections, this is typically used for Fuse programming scenarios when a stable clock is not yet available within the SOC). When the request arrives, life cycle controller requests the SOC to do the clock switch. When such a request is made, SOC MUST respond with an acknowledgement within 2 clock cycles of the internal clock. If this condition is not met, OTP controller will assert "program error" and the SOC must go through a reset cycle and redo the above steps. This must be verified by the SOC as a part of Caliptra subsystem integration checks.

   To protect from clock stretching attacks Caliptra mandates using a clock source that is constructed within the SOC (eg. PLL, Calibrated Ring Oscillator, etc). For such a clock source, a SOC may require fuses to be programmed. TP programming demands a reliable and deterministic clock signal to ensure correct fuse write operations; which SOC may not have during the early phases of manufacturing flow due to above constraints. In order to overcome this issue, this external clock can be used typically in the manufacturing phase of a SOC; and for such SOCs this external clock is supplied from a platform (e.g an ATE). Since the Caliptra subsystem includes only one clock input (cptra_ss_clk_i), the SoC integrator is responsible for ensuring that this input can be switched to a stable source.

   • The life-cycle controller exposes an LC_STATE register that carries the life-cycle controller state, which the SoC can read to determine the current life-cycle state. In addition, the Caliptra Subsystem top level provides the caliptra_ss_life_cycle_steady_state_o and caliptra_ss_otp_state_valid_o signals, which are broadcast from the fuse controller. Whenever caliptra_ss_otp_state_valid_o is asserted, caliptra_ss_life_cycle_steady_state_o reflects the latest life-cycle state stored in the fuse macro. Because the fuse controller is initialized earlier than the life-cycle controller, these broadcast state signals are derived from the fuse controller. Note that caliptra_ss_otp_state_valid_o is driven low by the fuse controller if a fatal error occurs in the fuse controller or if an escalation signal is asserted by the life-cycle controller. In contrast, LC_STATE provides the life-cycle controller’s own view of the state, independent of the fuse controller’s errors such as entering SCRAP state.

   Volatile-unlock state transitions are not reflected by the fuse controller, and therefore caliptra_ss_life_cycle_steady_state_o and caliptra_ss_otp_state_valid_o do not capture state transitions granted exclusively by the life-cycle controller. To cover this case, the Caliptra Subsystem also broadcasts caliptra_ss_volatile_raw_unlock_success_o, which is asserted by the life-cycle controller to indicate that the volatile-unlock state has been granted.

3. Scan Path Exclusions:

   • Ensure that the RAW_UNLOCK token is excluded from the scan chain. This token is different from other LC transition tokens as it is stored in the plaintext in gates, not in hashed form. To exclude it from scan, the following hierarchies must be excluded: *::lc_ctrl_fsm::hashed_tokens_{higher, lower}[RawUnlockTokenIdx] and *::lc_ctrl_fsm::hashed_token_mux.

4. RAW Unlock Token:

   • The cptra_ss_raw_unlock_token_hashed_i top-level input defines the hashed value of the RAW unlock token. The hashed value is generated from the unhashed RAW unlock token, which the integrator must obtain from a cryptographically secure random number generator. Both the hashed and the unhashed token must be kept secret. To generate the hashed token (and optionally also the unhashed token), tools/scripts/lc_ctrl_script/gen_lc_ctrl_token.py can be used.
   • The unhashed RAW unlock token is required in SW that performs a non-volatile RAW unlock.
   • The hashed RAW unlock token is stored in HW (see first bullet point) and required in SW that performs a volatile RAW unlock.

Programming Interface

The LC Controller's programming interface facilitates lifecycle state transitions, secure token authentication, and system initialization. Below are the key programming steps:

1. Initialization:

   • Ensure the LC Controller is ready by polling the LC_CTRL_STATUS_OFFSET register for the READY_MASK bit.
   • Verify initialization is complete using the INIT_MASK bit in the same register.
   • Corresponding fuse partitions need to be provisioned in order to perform state transitions

2. Lifecycle State Transitions:

   • Claim the transition mutex by writing 0x96 (MuBi8True) to LC_CTRL_CLAIM_TRANSITION_IF_OFFSET and polling until the value is correctly latched.
   • Set the desired next lifecycle state by writing to LC_CTRL_TRANSITION_TARGET_OFFSET.
   • Write the 128-bit transition token (if required) into the LC_CTRL_TRANSITION_TOKEN_*_OFFSET registers.
   • Trigger the state transition by writing 0x1 to LC_CTRL_TRANSITION_CMD_OFFSET.
   • Poll the LC_CTRL_STATUS_OFFSET register to monitor for successful state transition or detect errors such as token errors, OTP errors, or RMA strap violations.
   • Each TEST_UNLOCKED state has its own TOKEN (see See Fuse Memory Map).
   • During a state transition, an asserted reset or zeorization command can cause permanent life-cycle state corruption.

3. Token Validation:

   • For conditional state transitions, provide the transition token before the transition request.
   • Toke Format is illustrated with a python implementation:

# value = 0x318372c87790628a05f493b472f04808
# data = value.to_bytes(16, byteorder='little')
# custom = 'LC_CTRL'.encode('UTF-8')
# shake = cSHAKE128.new(data=data, custom=custom)
# shake output is 0x4c9ca068a68474d526e7d8a0233d5aad

# To unlock a state having the shake condition above, the LCC needs
# to get the following input set:
TOKEN_write(LC_CTRL_TRANSITION_TOKEN_3_OFFSET, 0x318372c8)
TOKEN_write(LC_CTRL_TRANSITION_TOKEN_1_OFFSET, 0x7790628a)
TOKEN_write(LC_CTRL_TRANSITION_TOKEN_2_OFFSET, 0x05f493b4)
TOKEN_write(LC_CTRL_TRANSITION_TOKEN_0_OFFSET, 0x72f04808)

4. RMA and SCRAP Strap Handling:
   • Ensure the Allow_RMA_or_SCRAP_on_PPD GPIO strap is asserted for RMA or SCRAP transitions. Transitions without this strap will fail with an appropriate status in the LC_CTRL_STATUS_OFFSET register.

Sequences: Reset, Boot

1. Reset Sequence:

   • Bring the LC Controller out of reset by asserting and de-asserting rst_ni after clock stabilization.
   • Perform a reset sequence after each state transition routine

2. Boot Sequence:

   • Enable MCI that intilaize the LC controller.
   • Verify successful initialization by reading LC_CTRL_STATUS_OFFSET.

3. Error Scenarios:

   • Test scenarios where invalid tokens, Fuse errors, or missing RMA straps are injected to validate error handling and system recovery mechanisms.

How to Test: Smoke & More

Smoke Test

1. Basic Connectivity:

   • Verify the LC Controller responds to read and write operations on key registers (e.g., LC_CTRL_STATUS_OFFSET, LC_CTRL_CLAIM_TRANSITION_IF_OFFSET).

2. Basic Initialization:

   • Check that the READY_MASK and INIT_MASK bits in LC_CTRL_STATUS_OFFSET transition to the expected values during initialization.

3. Lifecycle Transition:

   • Perform a single state transition (e.g., RAW to TEST_UNLOCKED0)

Functional Tests

1. Full Lifecycle Sequence:

   • Run all lifecycle transition functions and validate each transition step via the status register and debug messages.

2. Error Injection:

   • Test token errors by providing invalid tokens during a transition request.
   • Simulate OTP errors by corrupting OTP data or configuration.
   • Test RMA transitions with and without the Allow_RMA_or_SCRAP_on_PPD GPIO strap.
   • Test SCRAP transitions with and without the Allow_RMA_or_SCRAP_on_PPD GPIO strap.

3. Boundary Testing:

   • Verify correct operation under boundary conditions, such as repeated transitions, simultaneous requests, or rapid reset sequences.

Advanced Tests

1. Stress Test:

   • Perform rapid transitions through multiple lifecycle states to validate system robustness.
   • Simulate power interruptions during critical operations.

2. Integration Tests:

   • Verify interaction with other modules such as the fuse controller and MCI during state transitions.

MCI

Overview

Manufacturer Control Interface provides the following features for Caliptra SS:

• Boot Sequencer for the SS

  • FC Init

  • LCC Init

  • MCU Reset

    • Hitless Update Capability

• Caliptra Reset

• MCU SRAM

• MCU Trace Buffer

• MCU watchdog timer

• Mailboxes

• LCC State Translator for Caliptra Core

• Error Aggregation

• Register Bank for MCU/SOC

The Boot Sequence is what brings the subsystem up. It will do fuse controller and life cycle controller initialization. It then brings up MCU and Caliptra based on the breakpoint and no rom config input pins. Once MCI has done the subsystem bring up, it provides other functionality like the MCU SRAM, DAM for MCU, Error aggregation for the SS and more.

If there is an issue within MCI whether it be the Boot Sequencer or another component. The SOC can utilize the breakpoint and DMI capability to halt the Boot Sequencer before bring up the MCU and do targeted register accesses via the DMI port which is connected to the MCU.

MCI Block Diagram:

Parameters & Defines

Note: Additional parameter limitations can be seen in the Requirements section

Table: AXI Integration Parameters

Table: MCU SRAM Integration Parameters

Table: MCI Boot Sequencer Integration Parameters

Table: MCI MBOX Integration Parameters

Table: MCI Integration Definitions

Interface

Note: Additional interface connection requirements/guidance can be seen in the Requirements section

Note: Any port listed as “STATIC” must be stable before mci_pwrgood is asserted. If the signal changes value after mci_pwrgood assertion will cause functional issues in MCI

Note: Internal means the signal is not directly exposed to the SOC. External means it is directly exposed for SOC to consume and connect.

Note: If a signal (like the clock) is combined with other IPs it is still listed as Ext.

Note: If a signal stays in the SS but will need SOC connection (AXI interfaces) due to the SS not instantiating a component (like an AXI interconnect) it is listed as Ext because the SOC will need to connect.

Note: Any port with known internal and external connections (i.e. agg_error_fatal) will have External/Internal with note in a different section on which ports are reserved for internal vs external use.

Table: MCI Clocks

Table: MCI Resets

Table: MCI AXI Interface

Table: MCI Straps

Table: MCI CG Controls

Table: MCI MISC Interface

Table: MCI MCU Interface

Table: MCI Errors and Interrupts Interface

Table: MCI LCC Bring Up Interface

Table: MCI FC Bring Up Interface

Table: MCU SRAM Interface

Table: MCI LCC Gasket Interface

Memory Map / Address map

Top Level Memory Map

MCU SRAM Memory Map

MCU SRAM is split into 2 sections:

1. Updatable Execution Region
2. Protected Data Region

The two regions have different access protection. The size of the regions is dynamically changed via the FW_SRAM_EXEC_REGION_SIZE register in 4KB increments.

Table: MCU SRAM Regions

NOTE: FW_SRAM_EXEC_REGION_SIZE is base 0 meaning the minimum size for the Updatable Execution Region is 4KB.

NOTE: If FW_SRAM_EXEC_REGION_SIZE is the size of the SRAM, there is no protected Region.

MCI Integration Requirements

• Connectivity, Clock & Reset, Constraints & Violations etc

  • AXI Parameters and AXI Interface Parameter Alignment

    Due to SystemVerilog limitations MCI exposed both AXI parameters and AXI interfaces that are parameterized. Parameters between all AXI interface and the MCI AXI parameters must be consistent.

  • AXI DATA_WIDTH Limitation

    MCI DATA_WIDTH was only verified with a value of 32. If a different width is required the user will have to make internal MCI changes and no functionality is guaranteed.

  • AXI ADDR_WIDTH Limitation

    AXI ADDR_WIDTH must be wide enough to fully address the MCI address space.

  • MCI Base Address Requirement

    The base address assigned to MCI must align to the MCI total addressable space. This can be calculated based off of the MCU SRAM size since it is the last block in the MCI memory map.

    To calculate the base address alignment use the following calculation:

    bits = $clog2(MCU_SRAM_OFFSET + ((MCU_SRAM_SIZE_KB * 1024) - 1))
    

    MCU_SRAM_OFFSET can be found in the MCI’s Top Level Memory Map.

    Example:

    MCU_SRAM_OFFSET = 0xC00000 (12582912 decimal)
    
    MCU_SRAM_SIZE_KB = 512 (512KB)
    
    bits = $clog2(12582912 + ((512 * 1024) - 1))
    
    bits = 24
    
    MCI base address would need to align to 0x80_0000
    

  • Reset Synchronization

    MCI does not synchronize any resets inside the IP. It is expected all reset inputs are properly synchronized to the MCI clock domain before being passed to MCI.

    All MCI reset outputs are synchronous to the MCI clock domain and if they are used in a different clock domain they shall be properly synchronized outside of MCI.

  • DFT Reset Control

    MCI input resets do not have any built-in DFT reset control for scan. It is the integrator’s responsibility to add any DFT controls outside of MCI before the reset is connected to MCI.

    Simlar to Caliptra core - When scan_mode is set the MCI generated resets will be directly controlled by mci_rst_b. This gives DFT complete control of these resets within Caliptra SS.

  • Integrator RTL modification requirements

    MCI reused synchronizer modules from Caliptra Core like caliptra_2ff_syn.sv. Integrators are required to replace these modules with technology-specific sync cells.

    MCI does not itself contain modules that need to be directly modified by the integrator.

  • Late Binding interface signals

    The interface signals mci_generic_input_wires and mci_generic_output_wires are placeholders on the SoC interface reserved for late binding features. This may include any feature that is required for correct operation of the design in the final integrated SoC and that may not be accommodated through existing interface signaling (such as the mailbox).

    Each wire connects to a register in the MCI register bank through which communication to the MCU may be facilitated. Each of the generic wire signals is 64 bits in size.These signals are considered ASYNC and each of the 64 bits are considered separate adhoc signals. Meaning there is no bus synchronization which means the connections to this port need to be thoroughly thought through to ensure the MCU doesn’t drop any requests.

    Activity on any bit of the mci_generic_input_wires triggers a notification interrupt to the microcontroller indicating a bit toggle.

    The following tables describe the allocation of functionality on mci_generic_input_wires and mci_generic_output_wires. Bits not assigned to a function can be used by the SOC for their own needs. These generic wires could be reserved by CHIPS Alliance in future Caliptra drops. Any unused inputs shall be tied off to 0 and outputs left unconnected.

    Table: MCI Generic Input Allocation

**Table: MCI Generic Output Allocation**

Error Aggregation Connectivity Requirements

MCI aggregates all fatal and non-fatal errors for Caliptra SS via two ports agg_error_fatal and agg_error_non_fatal. These errors are:

1. Sent to MCU via interrupt
2. Sent to SOC via all_error_fatal or all_error_non_fatal MCI output ports

Errors connected to this infrastructure are required to be level signals. Pulses are not permitted.

MCU has the ability to independently mask these aggregated interrupts to its own interrupt and to the all_error_fatal and all_error_non_fatal output ports.

Aggregate error connections can be see in Caliptra SS HW Spec: MCI Error Handling.

Subsystem Internal Fuse Controller Initialization Connectivity Requirements

During Caliptra SS bring up the MCI handshakes with the FC to do initialization. The flow is:

1. MCI: Assert lc_init
2. FC: Assert lc_done

Connections between MCI and FC are shown in the table below:

Table: MCI to FC Init Connections

Subsystem Internal Life Cycle Controller Initialization Connectivity Requirements

During Caliptra SS bring up the MCI handshakes with the LCC to do initialization. The flow is:

3. MCI: Assert fc_opt_init
4. FC: Assert fc_opt_done

Connections between MCI and LCC are shown in the table below:

Table: MCI to LCC Init Connections

MCI MCU Connectivity Requirements

The table below shows connections between MCI and MCU that are not part of other features:

Table: MCI to MCU Connections

MCI Caliptra Core Connectivity Requirements

The table below shows connections between MCI and Caliptra Core that are not part of other features:

Table: MCI to Caliptra Core Connections

LCC Gasket Connectivity Requirements

Below are the connections needed between MCI and LCC for the Gasket functionality

Table: LCC Gasket - MCI to LCC Connections

Table: LCC Gasket - MCI to Caliptra Core Connections

Table: LCC Gasket - MCI to Caliptra SS Port Connections

Table: Fuse Zeroization Signals - Caliptra SS Port Connections to MCI to FC

MCU SRAM Sizing Requirements

MCU SRAM size is set via the MCU_SRAM_SIZE_KB parameter.

The minimum size supported is 4KBs.

The maximum size supported is 2MBs.

It is suggested the size is on a 4KB boundary since the split between the execution region and secure region is done via MCI CSR in 4KB increments.

Standard size is 512KB.

The size of the SRAM should be determined based on:

1. MCU runtime image size
2. STACK
3. Large data structures or persistent logs maintained by MCU
4. .data/.bss sections
5. Any other data MCU plans on storing the the MCU SRAM.

Storage guidance for Execution vs Protected region are as follows:

• Execution
  • Executable Runtime Instructions for MCU
  • .data/.bss sections
  • STACK
• Protected
  • STACK
  • Incorruptible data structures
  • Persistent logs maintained by MCU

Access to MCU SRAM Execution Region is controlled by mcu_sram_fw_exec_region_lock. Before MCU is brought out of reset for a hitless patch this signal must be asserted giving access to the MCU. Failure to do so will trigger an AXI access error since Caliptra will be the only entity allowed to access the SRAM until this signal is asserted.

MCU MBOX SRAM Sizing Requirements

MCU MBOX SRAM size is set via MCU_MBOX0_SIZE_KB and MCU_MBOX1_SIZE_KB parameters

The MCU can be configured to implement up to 2 independent mailboxes with maximum fully addressable SRAM. sizes of up to 2 MB. If they are configured sizes of 0, they will not be instantiated.

Size should be determined by:

1. Max MCU FW image size
2. Max size of other FW images Caliptra SS will handle

Programming interface

MCI Register Spec

MCI Register Spec

MCU Mailbox

Each mailbox can be used for secure and restricted communication between external SoC entities, the MCU, and Caliptra core. This communication channel is essential for exchanging control messages, status updates, and other critical information that the MCU will use to monitor system boot, firmware updates, and security critical operations. Mailboxes are designed to ensure that only authorized entities can access and communicate through it, preserving the integrity and security of the SoC operations.

The mailboxes are generic with some specific protocols and legal operations/accesses to ensure their secured and restricted aspect. The command, statuses, and data that are intepreted by the MCU microcontroller (uC), Caliptra uC or other SoC agent are not defined or enforced in this specification.

Since the MCU uC has root access to the mailboxes (even when the mailbox is locked), it can function as an intermediary and facilitate communication between 2 agents (such as Caliptra uC and other SoC agents).

The Caliptra SS HW MCU Mailbox Spec has more details about the specific registers and interrupts used in the mailbox flows.

MCU Mailbox Limited Trusted AXI users

If build-time integration straps are not used for configuring the trusted MBOX AXI users, then trusted users will need to configured with the following lockable MCI registers before MBOX can be used by SOC agents:

• MBOX*_VALID_AXI_USER
• MBOX*_AXI_USER_LOCK

See Caliptra SS MCU Trusted AXI Users for more details.

Reset

The mailboxes start locked by MCU to prevent any data leaks across warm reset. MCU shall set MBOX_DLEN to MBOX SRAM size and write 0 to MBOX_EXECUTE to release the MBOX and wipe the MBOX SRAM. This should be done before using or allowing use of the mailboxes.

MCU Mailbox Doorbell Command DLEN

An MBOX doorbell command has no data. When MBOX_DLEN = 0 and MBOX_EXECUTION is cleared, the clearing logic erases the entire MBOX SRAM. To avoid long delays caused by this clearing, firmware should set MBOX_DLEN = 1 when issuing doorbell commands.

MCI Debug Lock Status

MCI exposed the debug state of the chip to MCU via an interrupt notif_debug_locked_sts and a status register SECURITY_STATE.debug_locked. There is no defined use case for this feature at subsystem level, unlike in Caliptra where security assets are cleared when entering debug locked state. Therefore, it is recommended this interrupt remains disabled using notif_debug_locked_en.

If there is a need to use debug state the recommened flow to avoid missing a debug locked transition is:

1. Out of reset MCU W1C notif_debug_locked_sts
2. MCU reads SECURITY_STATE.debug_locked and acts on the value seen
3. MCU enables the interrupt using notif_debug_locked_en

MCU to SOC Receiver Flow

1. MCU attempts to lock mailbox by reading MBOX_LOCK register

• If read returns 0, LOCK is granted and will be set to 1
• If read returns 1, MBOX is locked for another agent

2. MCU writes data to MBOX_SRAM
3. MCU writes data length in bytes to MBOX_DLEN
4. MCU writes command to MBOX_CMD register
5. MCU sets MBOX_TARGET_USER to SOC Receiver AXI and sets MBOX_TARGET_USER_VALID to 1
6. MCU writes 1 to MBOX_EXECUTE register (which asserts cptra_ss_soc_mcu_mbox*_data_avail output)
7. MCU can directly inform receiver depending on receiver capabilities OR receiver could use cptra_ss_soc_mcu_mbox*_data_avail wire to directly generate an interrupt
8. Receiver processes command and data in mailbox
9. Receiver updates MBOX_SRAM and MBOX_DLEN (if there is data to return).
10. Reciever updates status in MBOX_TARGET_STATUS.STATUS and sets MBOX_TARGET_STATUS.DONE

• This generates interrupt MBOX*_TARGET_DONE to MCU

10. MCU (in response to MBOX*_TARGET_DONE interrupt) will write 0 to MBOX_EXECUTE to release the MBOX
11. MCI clears MBOX CSRs and zeros out data from 0 to the max DLEN set during the whole lock session in MBOX_SRAM

• Mailbox lock cannot be re-acquired until zeroization is complete

SOC Sender to MCU Flow

1. Sender attempts to lock mailbox by reading MBOX_LOCK register

• If read returns 0, LOCK is granted and will be set to 1
• If read returns 1, MBOX is locked for another agent

2. Sender writes data to MBOX_SRAM
3. Sender writes data length in bytes to MBOX_DLEN
4. Sender writes command to MBOX_CMD register
5. Sender writes 1 to MBOX_EXECUTE register

• This generates MBOX*_CMD_AVAIL interrupt to MCU

6. MCU processes command and data in mailbox
7. MCU updates MBOX_SRAM and MBOX_DLEN (if there is data to return).
8. MCU update MBOX_CMD_STATUS with desired status code
9. Sender writes 0 to MBOX_EXECUTE to release the MBOX
10. MCI clears MBOX CSRs and zeros out data from 0 to the max DLEN set during the whole lock session in MBOX_SRAM

• Mailbox lock cannot be re-acquired until zeroization is complete

SOC Sender to SOC Receiver Communication Flow (MCU as intermediary)

1. Sender attempts to lock mailbox by reading MBOX_LOCK register

• If read returns 0, LOCK is granted and will be set to 1
• If read returns 1, MBOX is locked for another agent

2. Sender writes data to MBOX_SRAM
3. Sender writes data length in bytes to MBOX_DLEN
4. Sender writes command to MBOX_CMD register
5. Sender writes 1 to MBOX_EXECUTE register

• This generates MBOX*_CMD_AVAIL interrupt to MCU

6. Sender reads/polls MBOX_CMD_STATUS for desired completion/ready status
7. MCU (in response to MBOX*_CMD_AVAIL interrupt) processes command and data
8. MCU sets MBOX_TARGET_USER to SOC Receiver AXI and sets MBOX_TARGET_USER_VALID to 1
9. MCU notifies SOC Receiver they can access MBOX (method depends on SOC Receiver capabilities)
10. Receiver reads MBOX and processes command and/or data
11. Receiver potentially updates data in MBOX_SRAM and MBOX_DLEN
12. Reciever updates status in MBOX_TARGET_STATUS.STATUS and sets MBOX_TARGET_STATUS.DONE

• This generates interrupt MBOX*_TARGET_DONE to MCU

13. MCU (in response to MBOX*_TARGET_DONE interrupt) will update MBOX_CMD_STATUS with final status
14. Sender sees final desired MBOX_CMD_STATUS
15. Sender writes 0 to MBOX_EXECUTE to release the MBOX
16. MCI clears MBOX CSRs and zeros out data from 0 to the max DLEN set during the whole lock session in MBOX_SRAM

• Mailbox lock cannot be re-acquired until zeroization is complete

MCU JTAG/DMI Access

MCI provides access JTAG security for MCU. Detailed debug architecture can be found in MCI debug spec. Some notes about MCI debug arcitecture:

1. MCI registers are accessed via the MCU DMI uncore address space.
2. Limited MCU JTAG access is provided to MCI DMI registers by setting cptra_ss_debug_intent_i
3. Full access to MCU core and uncore DMI registers is restricted to LCC unlocked mode.

MCU SRAM JTAG Access

MCU SRAM is fully accessable via MCU JTAG. MCU must be halted before accessing MCU SRAM via JTAG otherwise collisions between AXI and JTAG will result in errors and corrupted data.

MCU Trace Buffer

MCI hosts the MCU trace buffer. The full trace buffer spec is here. High level notes about trace buffer:

1. It can only be accessed when debug unlocked
2. It can be accessed via AXI or DMI
3. Traces can be disabled via a RISC-V control register
4. Traces are sticky and persist through warm reset
5. The trace buffer can hold a total of 64 traces

MCU Halt Ack Interface

Caliptra SS exposed the MCU halt ack handshake to enable MCU No Rom Config.

If the SOC does not support MCU No Rom Config Caliptra SS requires the signals to be looped back.

If the SOC supports MCU No Rom Config the SOC must drive the halt_ack/status during the first Caliptra SS boot out of Cold Reset since MCU is still in reset. It shall give control back to MCU after it has completed the initial halt handshake as specified in MCU No ROM Config flow. The recommended connections if MCU No Rom Config is supported:

Sequences : Reset, Boot,

MCI Boot Sequencer

The MCI is responsible for bringing up the Caliptra SS. This is done via the MCI Boot Sequencer. The primary job of this FSM is to:

1. Initialize the fuse controller
2. Initialize the life cycle controller
3. Allow a breakpoint for debug intervention before MCU or Caliptra are out of reset
4. Bring MCU out of reset
5. Bring Caliptra out of reset
6. Control MCU reset for hitless updates

Breakpoint Flow

The SOC can halt the MCI Boot Sequencer via the mcu_boot_seq_brkpoint port. When set to 1 it will cause the MCI Boot Sequence to halt after it has initialized both FC and LCC.

This port shall be set and stable before mcu_rst_b is deasserted. Failure to do so will mean the breakpoint might be missed by MCI Boot Sequencer.

Once in BOOT_BREAKPOINT a user can use MCU JTAG to configure MCI other components within the Caliptra SS for debug.

One known usecase for the breakpoint is to bypass the ROM and jump to a debug image in MCU SRAM.

To proceed after a breakpoint the SOC must write the MCI_BOOTFSM_GO.go register via AXI or MCI DMI port.

MCU No ROM Config

Caliptra SS supports booting without a MCU ROM. To enable this configuration the SOC must:

1. cptra_ss_mcu_no_rom_config_i set to 1
2. cptra_ss_strap_mci_soc_config_axi_user_i set to a trusted user other than MCU
3. cptra_ss_mcu_halt_status_i connected to cptra_ss_mcu_halt_status_o ORed with SOC control
4. cptra_ss_mcu_halt_ack_i connected to cptra_ss_mcu_halt_ack_o ORed with SOC control
5. (optional) cptra_ss_strap_mcu_reset_vector_i set to known starting address in MCU SRAM

The expected boot sequence is:

1. MCI brought out of reset
2. MCI boot FSM progresses to WAIT_FOR_CPTRA_BOOT_GO
3. Trusted SOC agent does configuration MCU ROM typically executes. See CSS HW spec
4. Trusted SOC agent sets CPTRA_BOOT_GO.go bringing Caliptra out of reset
5. Trusted SOC agent executes MCU FW Boot Update with Caliptra

• When SOC agent sees notif_cptra_mcu_reset_req_sts set by Caliptra, SOC will see cptra_ss_mcu_halt_req_o asserted by MCI Boot FSM. SOC must assert cptra_ss_mcu_halt_status_i and cptra_ss_mcu_halt_ack_i back to MCI. When SOC sees cptra_ss_mcu_halt_req_o deassert SOC shall give full control of these signals back to MCU.
• See MCU Halt Ack Interface for recommended connections.

During step 5 MCU will be brought out of reset and start executing from MCU SRAM.

No Caliptra Core Config

If an SOC does not need Caliptra and wants to use a different entity to service MCU FW updates the SOC can:

1. Tie cptra_ss_rst_b_i to 0
2. Leave cptra_ss_rst_b_o unused
3. Set cptra_ss_strap_mcu_sram_config_axi_user_i to a trusted user
   • Gives SOC agent access to MCU SRAM allowing it to populate it with a FW image.
4. cptra_ss_cptra_generic_fw_exec_ctrl_2_mcu_i controlled by the trusted user instead of Caliptra
   • Gives SOC agent reset request control of MCU.
5. Leave cptra_ss_cptra_generic_fw_exec_ctrl_2_mcu_o unused

Connectivity requirements can be found in FW Execution Control Connections and Caliptra Core Reset Control

Reset Ordering

The following table defines the order in which resets can get asserted. A ">>" in a cell at row X and column Y indicates that if the reset in row X is asserted, the reset in row Y is also asserted. For the rest of the cells (in which symbol ">>" is not present) the preceding assumption is not true and so the paths between those resets are potential RDC violations. The "N/A" cells are ignored because they are between the same resets.

Table: MCI Reset Ordering

MCU FW Update Flows

The hitless flow is described in full in Caliptra Top Spec. The Caliptra SS HW Spec spec gives details about the registers used in theese flow. This section is meant to elaborate on how to use the given HW to meet the architectual spec.

Registers relevant to these flows:

• Caliptra
  • SS_GENERIC_FW_EXEC_CTRL[0].go[2]
• MCI
  • RESET_STATUS.mcu
  • MCU_RESET_REQ
  • RESET_REASON
  • notif_cptra_mcu_reset_req_sts

MCU FW Boot Update

First MCU FW Update after a Cold Reset.

1. Out of Cold Boot Caliptra has access to MCU SRAM since FW_EXEC_CTRL[2] is reset to 0.
2. MCU ROM should use notif_cptra_mcu_reset_req_sts interrupt to know when Caliptra has a FW image for MCU. MCU ROM can either poll or enable the interrupt.
3. Caliptra sets MCI's RESET_REASON.FW_BOOT_UPD_RESET and Caliptra's FW_EXEC_CTRL[2] indicating a FW image is ready for MCU in MCU SRAM.
4. MCU sees request from Caliptra and shall clear the interrupt status.
5. MCU sets RESET_REQUEST.mcu_req in MCI to request a reset.
6. MCI does an MCU halt req/ack handshake to ensure the MCU is idle
7. MCI asserts MCU reset (min reset time for MCU is until MIN_MCU_RST_COUNTER overflows)
8. MCU is brought out of reset and checks MCI's RESET_REASON
9. MCU jumps to MCU SRAM

MCU Hitless FW Update

Subsequent MCU FW Update after FW Boot Update.

1. MCU FW should use notif_cptra_mcu_reset_req_sts interrupt to know when Caliptra has a FW image for MCU. MCU FW can either poll or enable the interrupt.
2. Caliptra clears FW_EXEC_CTRL[2] indicating a FW image is ready for MCU.
3. MCU sees request from Caliptra and shall clear the interrupt status.
4. MCU sets RESET_REQUEST.mcu_req in MCI to request a reset.
5. MCI does an MCU halt req/ack handshake to ensure the MCU is idle
6. MCI asserts MCU reset (min reset time for MCU is until MIN_MCU_RST_COUNTER overflows)
7. Caliptra will wait until RESET_STATUS.MCU_RESET_STS is set to indicate that reset is complete.
8. Caliptra will then have access to MCU SRAM Updatable Execution Region and update the FW image.
9. Caliptra sets RESET_REASON.FW_HITLESS_UPD_RESET
10. Caliptra sets FW_EXEC_CTRL[2]
11. MCU is brought out of reset and checks MCI's RESET_REASON
12. MCU jumps to MCU SRAM

MCU Warm Reset FW Update

Caliptra SS reset toggle without powergood toggle.

IMPORTANT - Can only happen after both Caliptra Core and MCU have loaded mutable firmware. Otherwise only Cold Reset is allowed.

1. MCU ROM comes out of reset and sees WARM_RESET. It cannot jump to MCU SRAM since it is locked and needs Caliptra to unlock.
2. MCU ROM brings Caliptra out of reset
3. Caliptra sees Warm Reset and starts executing from its ICCM (SRAM image)
4. Caliptra clears MCI's RESET_REASON.WARM_RESET and sets RESET_REASON.FW_BOOT_UPD_RESET
5. Caliptra sets FW_EXEC_CTRL[2]
6. MCU sees request from Caliptra and shall clear the interrupt status.
7. MCU sets RESET_REQUEST.mcu_req in MCI to request a reset.
8. MCI does an MCU halt req/ack handshake to ensure the MCU is idle
9. MCI asserts MCU reset (min reset time for MCU is until MIN_MCU_RST_COUNTER overflows)
10. MCU is brought out of reset and checks MCI's RESET_REASON
11. MCU jumps to MCU SRAM

Error Flows

• Example all_error_fatal Flow

Below is an example flow an SOC can follow that would properly clear all interrupts for all_error_fatal:

Setup assumes all interrupts to MCU and all_error_fatal are enabled via MCI CSRs

1. agg_error_fatal bit 0 is asserted by an IP
   1. error_agg_error_fatal0_sts for MCU will be asserted
   2. agg_error_fatal0 for SOC all_error_fatal will be asserted
2. MCU:
   1. Interrupted via mci_intr
   2. Takes action on error
      1. This could just be a loop waiting for a reset as fatal errors typically need a system wide reset.
   3. Waits for interrupt source to be cleared see SOC steps
   4. W1C error_agg_error_fatal0_sts to clear the interrupt
3. SOC:
   1. Interrupted via all_error_fatal
   2. Takes action on error
      1. Could be logging or resetting of the SOC
   3. Clears the source of the error causing agg_error_fatal[0] to be cleared
   4. W1C agg_error_fatal0
4. At this point all interrupt registers within MCI register bank are cleared but all_error_fatal is still asserted.
5. Reset MCI via mci_rst_b
   1. Clears the all_error_fatal output port

• Example all_error_non_fatal Flow

Below is an example flow an SOC can follow that would properly clear all interrupts for all_non_error_fatal:

Setup assumes all interrupts to MCU and all_error_non_fatal are enabled via MCI CSRs

1. agg_error_fatal bit 0 is asserted by an IP
   1. notif_agg_error_fatal0_sts for MCU will be asserted
   2. agg_error_non_fatal0 for SOC all_error_non_fatal will be asserted
2. MCU:
   1. Interrupted via mci_intr
   2. Takes action on error
      1. Could just be a logging of the non-fatal error
   3. Waits for interrupt source to be cleared see SOC steps
   4. W1C notif_agg_error_fatal0_sts to clear the interrupt
3. SOC:
   1. Interrupted via all_error_non_fatal
   2. Takes action on error
      1. Could be logging or resetting of the SOC
   3. Clears the source of the error causing agg_error_non_fatal[0] to be cleared
   4. W1C agg_error_non_fatal0
4. Once MCU and SOC have finished their flows all interrupts will be cleared

See MCI error handling for more details on MCI error infrastructure.

Other requirements

I3C core

Overview

The I3C core in the Caliptra Subsystem is an I3C target composed of two separate I3C targets:

1. Main target : Main target is responsible for any flows other than recovery or streaming boot.
2. Recovery target : Recovery target is dedicated to streaming boot / recovery interface.

• This I3C code integrates with an AXI interconnect, allowing AXI read and write transactions to access I3C registers. For details on the core’s internal registers and functionality, see:
  • I3C Core Documentation
  • Caliptra Subsystem Hardware Specification Document
  • I3C Core Registers

Integration Considerations

• Connections
  • Connection to AXI interface
  • GPIO connection to I3C Host (VIP or RTL)

Parameters and defines

Interface

I3C Integration Requirements

1. Connect the cptra_ss_i3c_s_axi_if with AXI interconnect.
2. Follow the programming sequence described in Programming Sequence from AXI Side Point#1 to initialize the I3C targets.
3. Follow the programming sequence described in Programming Sequence from AXI Side Point#2 to set both I3C target device with static addresses. Note, this is not required if I3C Host device is using the CCC ENTDAA for initializing the dynamic address to both targets.
4. If no external I3C connect cptra_ss_i3c_recovery_image_activated_o directly to cptra_ss_i3c_recovery_image_activated_i. If there is an external I3C cptra_ss_i3c_recovery_image_activated_o can be combined with or completely replaced with SOC logic and connected to cptra_ss_i3c_recovery_image_activated_i.
5. If no external I3C connect cptra_ss_i3c_recovery_payload_available_o directly to cptra_ss_i3c_recovery_payload_available_i. If there is an external I3C cptra_ss_i3c_recovery_payload_available_o can be combined with or completely replaced with SOC logic and connected to cptra_ss_i3c_recovery_payload_available_i.

Programming Sequence

Programming Sequence from AXI Side

1. Initialize the Device:

   • Write to the necessary AXI registers to configure the I3C core.
   • Ensure that the AXI interface is properly set up for communication.
   • Refer to I3C register documentation at I3C Core Registers for more details.

   // Reference Code to Initialize the I3C core (Target Mode)
   // This code initialized I3C core for default settings.
   uint32_t i3c_reg_data;
   i3c_reg_data = 0x00000000;
   
   i3c_reg_data = lsu_read_32(SOC_I3CCSR_I3C_EC_STDBYCTRLMODE_STBY_CR_CONTROL);
   i3c_reg_data = (2 << I3CCSR_I3C_EC_STDBYCTRLMODE_STBY_CR_CONTROL_STBY_CR_ENABLE_INIT_LOW) | i3c_reg_data;
   i3c_reg_data = (1 << I3CCSR_I3C_EC_STDBYCTRLMODE_STBY_CR_CONTROL_TARGET_XACT_ENABLE_LOW) | i3c_reg_data;
   lsu_write_32(SOC_I3CCSR_I3C_EC_STDBYCTRLMODE_STBY_CR_CONTROL, i3c_reg_data);
   
   i3c_reg_data = lsu_read_32(SOC_I3CCSR_I3CBASE_HC_CONTROL);
   i3c_reg_data = (1 << I3CCSR_I3CBASE_HC_CONTROL_BUS_ENABLE_LOW) | i3c_reg_data;
   lsu_write_32(SOC_I3CCSR_I3CBASE_HC_CONTROL, i3c_reg_data);
   

2. Program I3C core targets with unique static addresses:

   • Write to the necessary AXI registers to configure the I3C core with unique static target address.
   • Ensure that the AXI interface is properly set up for communication.
   • Refer to I3C register documentation at I3C Core Registers for more details.

   // Reference Code to Program Unique Static Address for I3C Core
   uint32_t i3c_reg_data;
   i3c_reg_data = 0x00000000;
   //setting device address to 0x5A
   i3c_reg_data = 0x00000000;
   i3c_reg_data = 90 << 0  | i3c_reg_data;
   i3c_reg_data = 1  << 15 | i3c_reg_data;
   lsu_write_32( SOC_I3CCSR_I3C_EC_STDBYCTRLMODE_STBY_CR_DEVICE_ADDR, i3c_reg_data);
   
   //setting virtual device address to 0x5B
   i3c_reg_data = 0x00000000;
   i3c_reg_data = 91 << 0  | i3c_reg_data; //0x5B
   i3c_reg_data = 1  << 15 | i3c_reg_data;
   lsu_write_32 ( SOC_I3CCSR_I3C_EC_STDBYCTRLMODE_STBY_CR_VIRT_DEVICE_ADDR, i3c_reg_data);
   

Programming Sequence from GPIO Side

1. Program Dynamic Address for Both Targets:

   • Use CCC (Common Command Code) commands to assign dynamic addresses to both I3C targets.
   • Ensure that each target is programmed with a unique dynamic address.

2. Read the Dynamic Address for Each Target:

   • Verify the dynamic addresses assigned to each target by reading back the addresses.
   • Ensure that the addresses are correctly programmed and accessible.

How to test : Smoke & more

• Basic Connectivity

  • CCC command execution for programming Dynamic Address
  • Program & Read Recovery interface registers
  • Write and read TTI interface from each side.

• Recovery Sequence

  • Test transfers the recovery image
  • Boots the device using the recovery image

• MCTP Test seqeunce

  • MCTP Test send random 68 bytes of data and PEC to RX queue
  • MCU reads and compares the data with expected data

CDC analysis and constraints

Clock Domain Crossing (CDC) analysis is performed on Caliptra Subsystem. The following are the results and recommended constraints for integrators using standard CDC analysis EDA tools.

In an unconstrained environment, several CDC violations are anticipated. CDC analysis requires the addition of constraints to identify valid synchronization mechanisms and/or static/pseudo-static signals.

Known Issues

Will not affect complete solution.

• Suppressible error in Line 235 of entropy_src.sv
  • Occurs in stub code. Comment out to proceed
• Function definition in Line 45 of caliptra_prim_sparse_fsm_flop.sv may cause CDC tool to quit compilation
  • CALIPTRA_INC_ASSERT not defined by default
  • Comment out code under if condition for CDC analysis

Analysis of missing synchronizers

• All of the signals, whether single-bit or multi-bit, originate from the CaliptraClockDomain clock and their endpoint is the RISCV JTAG clock domain in both Caliptra Core and MCU.
• The violations occur on the read path to the JTAG.
• We only need to synchronize the controlling signal for this interface.
• Inside the dmi_wrapper, the dmi_reg_en and dmi_reg_rd_en comes from dmi_jtag_to_core_sync, which is a 2FF synchronizer.

The following code snippets and schematic diagrams illustrate the CDC violations that end at the JTAG interface.

Figure: Code snippet showing JTAG-originating CDC violations

el2_dbg.sv

rvdffe #(32) dmi_rddata_reg (.din(dmi_reg_rdata_din[31:0]), .dout(dmi_reg_rdata[31:0]), .en(dmi_reg_en), .rst_l(dbg_dm_rst_l), .clk(clk), .*);

soc_ifc_top.sv

cptra_uncore_dmi_reg_rdata <= cptra_uncore_dmi_unlocked_reg_en ? cptra_uncore_dmi_unlocked_reg_rdata_in : 
                              cptra_uncore_dmi_locked_reg_en   ? cptra_uncore_dmi_locked_reg_rdata_in : cptra_uncore_dmi_reg_rdata;

dmi_mux.v

// Read mux
assign dmi_rdata = is_uncore_aperture ? dmi_uncore_rdata : dmi_core_rdata;

Figure: Schematic diagram showing JTAG-originating CDC violations

CDC analysis conclusions

• Missing synchronizers appear to be the result of “inferred” and/or only 2-FF instantiated synchronizers.
  • dmi_jtag_to_core_sync.v contains inferred 2FF synchronizers on the control signals “dmi_reg_wr_en” and “dmi_reg_rd_en”.
  • 2FF synchronizer inferences are considered non-compliant and should be replaced by an explicitly instantiated synchronization module, which is intended to be substituted on a per-integrator basis.
    • cdc report scheme two_dff -severity violation
• Multi-bit signals are effectively pseudo-static and are qualified by synchronized control qualifiers.
  • Pseudo-static: wr_data, wr_addr
    • cdc signal reg_wr_data -module dmi_wrapper -stable
    • cdc signal reg_wr_addr -module dmi_wrapper -stable
• The core clock frequency must be at least twice the TCK clock frequency of each TAP EPs for the JTAG data to pass correctly through the synchronizers.

CDC constraints

• cdc report scheme two_dff -severity violation
• cdc signal reg_wr_data -module dmi_wrapper -stable
• cdc signal reg_wr_addr -module dmi_wrapper -stable
• cdc signal rd_data -module dmi_wrapper -stable
• cdc signal reg_wr_data -module css_mcu0_dmi_wrapper -stable
• cdc signal reg_wr_addr -module css_mcu0_dmi_wrapper -stable
• cdc signal rd_data -module css_mcu0_dmi_wrapper -stable
• cdc signal jtag_dmi_req_i -module dmi_cdc -stable
• cdc signal jtag_dmi_resp_o -module dmi_cdc -stable
• cdc signal core_dmi_req_o -module dmi_cdc -stable
• cdc signal core_dmi_resp_i -module dmi_cdc -stable

Reset Domain Crossing

Reset Architecture

The below diagram illustrates the internal reset architecture of Caliptra SS.

The reset block diagram below illustrates the RTL implemenation of various resets.

The below diagram illustrates how various internal blocks are connected to either primary resets or internally generated resets.

Similar to Caliptra Core, we solve the problem of RDC using gated clocks which are gated during reset assertion. Below diagram illustrates the clock connections of various sub-modules.

Reset Domain Stamping and Constraints

The Below table illustrates various reset domains that we have in the design. We assume that all resets are asserted at timestamp 5, and the constrained signal is held high or low around that time (for instance, from timestamp 2 to timestamp 8).

The current analysis only focuses on RDC crossing which are internal to Caliptra SS. Any RDC crossings with external flops need to be handled by integrators.

Reset Sequencing

The below waveform illustrates how various resets of Caliptra SS and Caliptra Core are sequenced in the design.

The red and blue line indicates that the input Caliptra SS warm reset (cptra_ss_rst_b_i) needs to be asserted for atleast 32 clock cycles for the reset assertion to propagate through various levels of hierarhcy.

RDC Waivers

All Caliptra Core waivers are applicable at SS level as well. On top of those, we have the following waivers.

create_view_criteria \
    -name otp_broadcast_ss_rst_caliptra_core \
    -rule {E_RST_METASTABILITY} \
    -comment "waiver_for otp_broadcast related paths" \
    -criteria { ((ResetFlop =~ "*.u_caliptra_ss.u_otp_ctrl.otp_broadcast_o.secret_prod_partition_0_data.*")  ||  \
                 (ResetFlop =~ "*.u_caliptra_ss.u_otp_ctrl.otp_broadcast_o.valid*") ) &&  \
                 ((MetaStableFlop =~ "*.u_caliptra_ss.caliptra_top_dut.soc_ifc_top1.i_soc_ifc_reg.field_storage.fuse_field_entropy*") || \
                  (MetaStableFlop =~ "*.u_caliptra_ss.caliptra_top_dut.soc_ifc_top1.i_soc_ifc_reg.field_storage.fuse_uds_seed*") ) } \
    -replace
set_rule_status -use_view_criteria otp_broadcast_ss_rst_caliptra_core -status Waived -weakmatchfullgroup

create_view_criteria \
    -name path_ending_at_2ff_sync \
    -rule {E_RST_METASTABILITY} \
    -comment "wavier for 2ff sync" \
    -criteria { ((MetaStableFlop =~ "*.u_sync_1.gen_generic.u_impl_generic.*") || \
                  (MetaStableFlop =~ "*.i_rst_window_sync.*") ) } \
    -replace
set_rule_status -use_view_criteria path_ending_at_2ff_sync -status Waived -weakmatchfullgroup

create_view_criteria \
    -name no_axi_bus_active \
    -rule {E_RDC_METASTABILITY} \
    -comment "Before warm reset assertion, it is sure that is transaction pending on axi bus" \
    -criteria {  (ResetFlop      =~ "*.caliptra_top_dut.s_axi_active[2:0]") && \
                 (MetaStableFlop =~ "*cg.user_soc_ifc_icg.clk_slcg_0_generated_icg.p_clkgate.vudpi0.q")  } \
    -replace
set_rule_status -use_view_criteria no_axi_bus_active -status Waived -weakmatchfullgroup

Synthesis

Synthesis has been performed at CALIPTRA_SS_WRAPPER level which encompasses the following :-

• caliptra_ss_top
• Memories instantiated outside using tech specific macros

Design converges at 400MHz 0.72V using an industry standard, advanced technology node as of 2025 April.

Recommended LINT rules

A standardized set of lint rules is used to sign off on each release. The lint policy may be provided directly to integrators upon request to ensure lint is clean in the SoC.

Known Lint Issue

The following lint violations are known and expected in the current implementation:

Signal Width Mismatches

Undriven signals

These are undriven signals and deemed to be OK. If exposed to SOC leave unconnected when integrating.

Terminology