Changes to Subsystem Integration Specification

Comparing version 2.1 to 2.0
+97 additions -31 deletions
@@ -1,5 +1,5 @@
11 <div style="font-size: 0.85em; color: #656d76; margin-bottom: 1em; padding: 0.5em; background: #f6f8fa; border-radius: 4px;">
2-đź“„ Source: <a href="https://github.com/chipsalliance/caliptra-ss/blob/9022fc2a57bb9af2f3ebc2376b98a807812e2e0f/docs/CaliptraSSIntegrationSpecification.md" target="_blank">chipsalliance/caliptra-ss/docs/CaliptraSSIntegrationSpecification.md</a> @ <code>9022fc2</code>
2+đź“„ Source: <a href="https://github.com/chipsalliance/caliptra-ss/blob/2041523f977f5b24453464eda02008b1bd0f4f66/docs/CaliptraSSIntegrationSpecification.md" target="_blank">chipsalliance/caliptra-ss/docs/CaliptraSSIntegrationSpecification.md</a> @ <code>2041523</code>
33 </div>
44
55 <div align="center">
@@ -7,7 +7,7 @@
77 </div>
88
99 <h1 align="center"> Caliptra Subsystem Integration Specification </h1>
10-<h3 align="center"> Version 2.0.1 </h3>
10+<h3 align="center"> Version 2p1 </h3>
1111
1212 - [Scope](#scope)
1313 - [Document Version](#document-version)
@@ -71,6 +71,9 @@
7171 - [Programming interface](#programming-interface-1)
7272 - [Readout Sequence](#readout-sequence)
7373 - [Sequences: Reset, Boot](#sequences-reset-boot)
74+ - [UDS \& Field Entropy FIPS Zeroization Sequence](#uds--field-entropy-fips-zeroization-sequence)
75+ - [FIPS Zeroization Sequence For ECC](#fips-zeroization-sequence-for-ecc)
76+ - [Miscellanious Fuse Integration Guidelines](#miscellanious-fuse-integration-guidelines)
7477 - [How to test : Smoke \& more](#how-to-test--smoke--more)
7578 - [Generating the Fuse Partitions](#generating-the-fuse-partitions)
7679 - [Fuse Controller Macro](#fuse-controller-macro)
@@ -81,6 +84,7 @@
8184 - [Why These Straps Are Needed](#why-these-straps-are-needed)
8285 - [Strap Definitions](#strap-definitions)
8386 - [FC Macro Test Interface](#fc-macro-test-interface)
87+ - [Life Cycle OTP Programming Behavior and Integrator Responsibilities](#life-cycle-otp-programming-behavior-and-integrator-responsibilities)
8488 - [Life Cycle Controller](#life-cycle-controller)
8589 - [Overview](#overview-5)
8690 - [Parameters \& Defines](#parameters--defines-3)
@@ -174,6 +178,7 @@
174178 | ----------------- | -------------------- | ------------------- |
175179 | Jan 31st, 2025 | v0p8 | Work in progress |
176180 | Apr 30th, 2025 | v1p0-rc1 | Initial release candidate of Caliptra Gen 2.0 Subsystem Documents.<br>Specifcations updated with:<br> - Detail on usage of all Subsystem flows such as Streaming Boot, Mailbox operation, and Debug Unlock<br> - Details on design connectivity with top-level ports<br> - Requirements and recommendations for integrators when adding Caliptra Subsystem to SoC designs |
181+| Oct 12th, 2025 | v2p1 | Final release of Caliptra Subsystem 2.1 |
177182
178183
179184 </div>
@@ -298,6 +303,7 @@
298303 | External | input | 64 | `cptra_ss_strap_caliptra_base_addr_i` | Caliptra base address strap input |
299304 | External | input | 64 | `cptra_ss_strap_mci_base_addr_i` | MCI base address strap input |
300305 | External | input | 64 | `cptra_ss_strap_recovery_ifc_base_addr_i` | Recovery interface base address strap input |
306+| External | input | 64 | `cptra_ss_strap_external_staging_area_base_addr_i` | External staging area base address input |
301307 | External | input | 64 | `cptra_ss_strap_otp_fc_base_addr_i` | OTP FC base address strap input |
302308 | External | input | 64 | `cptra_ss_strap_uds_seed_base_addr_i` | UDS seed base address strap input |
303309 | External | input | 32 | `cptra_ss_strap_prod_debug_unlock_auth_pk_hash_reg_bank_offset_i` | Prod debug unlock auth PK hash reg bank offset input |
@@ -307,6 +313,11 @@
307313 | External | input | 32 | `cptra_ss_strap_generic_2_i` | Generic strap input 2 |
308314 | External | input | 32 | `cptra_ss_strap_generic_3_i` | Generic strap input 3 |
309315 | External | input | 1 | `cptra_ss_debug_intent_i` | Physical presence bit required to initiate the debug unlock flow. For more details, refer to the [Production Debug Unlock Flow](CaliptraSSHardwareSpecification.md#production-debug-unlock-architecture) and [How does Caliptra Subsystem enable manufacturing debug mode?](CaliptraSSHardwareSpecification.md#how-does-caliptra-subsystem-enable-manufacturing-debug-mode). For SOCs that choose to use these features, this port should be connected to a GPIO |
316+| External | input | 16 | `cptra_ss_strap_key_release_key_size_i` | OCP L.O.C.K. MEK byte size. Expected to be 0x40. |
317+| External | input | 64 | `cptra_ss_strap_key_release_base_addr_i` | OCP L.O.C.K. MEK release base address. |
318+| External | input | 1 | `cptra_ss_strap_ocp_lock_en_i` | OCP L.O.C.K. enable. Allows OCP L.O.C.K. in progress to be set enabling hardware features specific to OCP L.O.C.K. such as AES Keyvault write path, Keyvault filtering rules, and Key Release via AXI DMA. Must be driven with a constant value 0 or 1. |
319+| External | input | 64 | `cptra_ss_strap_external_staging_area_base_addr_i` | Base AXI address for the external staging area used by Caliptra Core FW to stage FW images due to reduced MBOX SRAM size. See [Caliptra External Staging Area](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraIntegrationSpecification.md#external-staging-area) for more details. |
320+
310321
311322
312323 ### AXI Interface (axi_if)
@@ -446,7 +457,8 @@
446457 | External | input | 1 | `cptra_ss_cptra_core_itrng_valid_i` | Internal TRNG valid input |
447458 | External | interface | na | `cptra_ss_mci_mcu_sram_req_if` | MCI MCU SRAM request interface |
448459 | External | interface | na | `cptra_ss_mci_mbox0_sram_req_if` | MCI mailbox 0 SRAM request interface |
449-| External | interface | na | `cptra_ss_mci_mbox1_sram_req_if` | MCI mailbox 1 SRAM request interface |
460+
461+| External | interface | na | `cptra_ss_mci_mbox1_sram_req_if` | MCI mailbox 1 SRAM request interface |har
450462 | External | output | 1 | `cptra_ss_soc_mcu_mbox0_data_avail` | MCU Mailbox0 data available output |
451463 | External | output | 1 | `cptra_ss_soc_mcu_mbox1_data_avail` | MCU Mailbox1 data available output |
452464 | External | interface | na | `cptra_ss_mcu0_el2_mem_export` | MCU0 EL2 memory export interface |
@@ -455,11 +467,14 @@
455467 | External | input | 1 | `cptra_ss_mci_boot_seq_brkpoint_i` | MCI boot sequence breakpoint input |
456468 | External | input | 1 | `cptra_ss_lc_Allow_RMA_or_SCRAP_on_PPD_i` | Allow RMA or SCRAP on PPD input |
457469 | External | input | 1 | `cptra_ss_FIPS_ZEROIZATION_PPD_i` | Zeroization request with PPD input. If FIPS zeroization flow is required, it shall be set before Caliptra SS is out of reset. |
470+| External | input | 1 | `cptra_ss_lc_sec_volatile_raw_unlock_en_i` | Enables Volatile TEST_UNLOCKED0 state transition infra (see [Volatile-Unlock](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSHardwareSpecification.md#exception-non-volatile-debugging-infrastructure-and-initial-raw-state-operations)) |
458471 | External | output | 1 | `cptra_ss_dbg_manuf_enable_o` | Indication that the debug is unlocked for manufacturing state and this is set by Caliptra Core |
459472 | External | output | 64 | `cptra_ss_cptra_core_soc_prod_dbg_unlock_level_o` | Indication that the debug is unlocked for production state. Each bit represents a debug level. Currently, 8-bit is supported with Caliptra ROM |
460473 | External | output | na | `caliptra_ss_life_cycle_steady_state_o` | Life-cycle state broadcasted by fuse macro for any additional SOC specific use cases |
461474 | External | output | 1 | `caliptra_ss_otp_state_valid_o` | One-bit valid indicator for the broadcast life-cycle state (`caliptra_ss_life_cycle_steady_state_o`). |
462475 | External | output | 1 | `caliptra_ss_volatile_raw_unlock_success_o` | Asserted when the life-cycle controller grants the volatile-unlock state and remains asserted until the next power-cycle. This transition bypasses the fuse macro, so `caliptra_ss_life_cycle_steady_state_o` and `caliptra_ss_otp_state_valid_o` do not reflect it. |
476+| External | output | na | `cptra_ss_lc_escalate_en_o` | Life-cycle controller signal indicating that escalation is enabled at LCC and FC |
477+| External | output | na | `cptra_ss_lc_check_byp_en_o` | Life-cycle controller signal indicating that external clock is accepted |
463478 | External | output | 64 | `cptra_ss_mci_generic_output_wires_o` | Generic output wires for MCI |
464479 | External | input | 1 | `cptra_ss_mcu_jtag_tck_i` | MCU JTAG clock input |
465480 | External | input | 1 | `cptra_ss_mcu_jtag_tms_i` | MCU JTAG TMS input |
@@ -499,6 +514,7 @@
499514 - **Signal Name** `cptra_ss_clk_i`
500515 - **Required Frequency** 333* MHz to 400 MHz
501516 - I3C core imposes requirement for minimum operating clock frequency set to 333 MHz or higher to meet 12ns tSCO timing.
517+ - 333 MHz was calculated assuming SCL PAD -> D and SDA Q -> PAD timing is 0. SOCs with large timing delays might need to run at a faster clock frequency to meet tSCO timing of 12ns.
502518 - SoCs that run Caliptra lower than 333 MHz will limit the max I3C SCL frequency. See [I3C Phy Spec](https://chipsalliance.github.io/i3c-core/phy.html#clock-synchronization-5-1-7) for more details.
503519 - This was changed from 170 MHz floor due to CDC issue found in I3C core:
504520 - [I3C Repo CDC Issue](https://github.com/chipsalliance/i3c-core/issues/72)
@@ -520,8 +536,8 @@
520536 3. Clock gating controlled by `cptra_ss_warm_reset_rdc_clk_dis_o`.
521537 4. Any SOC logic on a deeper reset domain than CSS can use this clock to resolve RDC issues.
522538
523-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.
524-
539+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.
540+
525541 - **Signal Name** `cptra_ss_mcu_clk_cg_o`
526542 - **Required Frequency** Same as `cptra_ss_clk_i`.
527543 - **Clock Source** Caliptra SS MCI clock gater
@@ -542,7 +558,7 @@
542558 - If the reset source is asynchronous, a synchronizer circuit must be used before connecting to the subsystem.
543559 - During SoC initialization, assert this reset signal until all subsystem clocks and required power domains are stable.
544560 - 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.
545- - 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.
561+ - 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.
546562
547563 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.
548564
@@ -662,7 +678,7 @@
662678
663679 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`.
664680
665-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.
681+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.
666682
667683 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.
668684
@@ -848,7 +864,7 @@
848864
849865 ## MCU SRAM MRAC Considerations
850866
851-The MCU's [Memory Region Access Control (MRAC)](https://chipsalliance.github.io/Cores-VeeR-EL2/html/main/docs_rendered/html/memory-map.html#region-access-control-register-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.
867+The MCU's [Memory Region Access Control (MRAC)](https://chipsalliance.github.io/Cores-VeeR-EL2/html/main/docs_rendered/html/memory-map.html#region-access-control-register-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 "cachable". 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.
852868
853869 ### Split Memory Mapping
854870
@@ -870,9 +886,9 @@
870886
871887 When MCU SRAM remains within the main MCI address space (not split off), integrators should consider the following caching limitations:
872888
873-**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.
874-
875-If you want to enable MCU iCache functionality, you must implement the [Split Memory Mapping](#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.
889+**iCache Enablement Requirement**: To enable MCU iCache, everything within the 256MB boundary containing MCU SRAM must be cachable. Since not all regions of MCI are cachable, **MCU iCache cannot be enabled** when using a contiguous MCI address map.
890+
891+If you want to enable MCU iCache functionality, you must implement the [Split Memory Mapping](#split-memory-mapping) (Option 2) in your AXI interconnect. This allows MCU SRAM to be placed in a dedicated cachable region separate from other MCI components.
876892
877893 ## MCU Programming interface
878894
@@ -920,7 +936,7 @@
920936 | ------------ | ------------ | ------- | ------------------------------- | ----------------------------------- | -------------------------------------------------------- |
921937 | External | Input | 1 | `clk_i` | `cptra_ss_clk_i` | Fuse Controller clock input. |
922938 | External | Input | 1 | `rst_ni` | `cptra_ss_rst_b_i` | Reset signal input, active low. |
923-| Internal | Input | 1 | `FIPS_ZEROIZATION_CMD_i` || Fuse Zeroization signal controlled by MCI |
939+| Internal | Input | 1 | `FIPS_ZEROIZATION_CMD_i` || Fuse Zeroization request sampled on MCI reset deassertion. |
924940 | External | interface | 1 | `core_axi_wr_req` | `cptra_ss_otp_core_axi_wr_req_i` | AXI write request. |
925941 | External | interface | 1 | `core_axi_wr_rsp` | `cptra_ss_otp_core_axi_wr_rsp_o` | AXI write response. |
926942 | External | interface | 1 | `core_axi_rd_req` | `cptra_ss_otp_core_axi_rd_req_i` | AXI read request. |
@@ -945,12 +961,12 @@
945961 ## Fuse Macro Memory Map and Fuse Controller CSR Address Map
946962
947963 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:
948-See [Fuse Controller Register Map](https://github.com/chipsalliance/caliptra-ss/blob/9022fc2a57bb9af2f3ebc2376b98a807812e2e0f/src/fuse_ctrl/doc/otp_ctrl_registers.md) for registers.
949-See [Fuse Macor Memory Map](https://github.com/chipsalliance/caliptra-ss/blob/9022fc2a57bb9af2f3ebc2376b98a807812e2e0f/src/fuse_ctrl/doc/otp_ctrl_mmap.md) for fuse partition map.
964+ - [Fuse Controller Register Map](https://github.com/chipsalliance/caliptra-ss/blob/2041523f977f5b24453464eda02008b1bd0f4f66/src/fuse_ctrl/doc/otp_ctrl_registers.md) for registers.
965+ - [Fuse Macro Memory Map](https://github.com/chipsalliance/caliptra-ss/blob/2041523f977f5b24453464eda02008b1bd0f4f66/src/fuse_ctrl/doc/otp_ctrl_mmap.md) for fuse partition map.
950966
951967 The current fuse memory map consists of **three main architectural segments**: **Caliptra-Core** (prefix: `CALIPTRA_CORE`), **Caliptra-Subsystem** (prefix: `CALIPTRA_SS`), **SoC/Vendor-Specific**.
952968
953-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](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#fuse-map), **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.
969+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](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#fuse-map), **Caliptra-Subsystem** fuses are required only when Caliptra 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.
954970
955971
956972 ### **SOC_SPECIFIC_IDEVID_CERTIFICATE Usage**
@@ -1082,7 +1098,34 @@
10821098 - Perform a full integrity check by triggering `FUSE_CTRL_CHECK_TRIGGER` and ensure the system is error-free before proceeding.
10831099 - Validate readiness by checking the `FUSE_CTRL_STATUS` register.
10841100
1085-
1101+## UDS & Field Entropy FIPS Zeroization Sequence
1102+This sequence follows the "theory of operation" stated in this ['fuse-zeroization-programmer's-guide'](https://github.com/chipsalliance/caliptra-ss/blob/main/src/fuse_ctrl/doc/fuse_ctrl_zeroization_programmers_guide.md)
1103+
1104+Follow these steps in order to correctly zeroize the fuses and verify the operation for any partition that requires FIPS zeroization to be set (determined by zeroizable flag when a partition is generated).
1105+1. Assert Physical Presence: Set the FIPS_zeroization_PPD pin high before taking the Caliptra subsystem out of reset. This confirms physical presence and authorizes the zeroization. When this signal is asserted, it triggers preemptive zeroization of secret FUSEs. The **MCU ROM** samples `cptra_ss_FIPS_ZEROIZATION_PPD_i` by reading the corresponding register storing its value in MCI. If `cptra_ss_FIPS_ZEROIZATION_PPD_i == HIGH`, the MCU ROM writes `32'hFFFF_FFFF` to the `ss_soc_MCU_ROM_zeroization_mask_reg` register of **MCI**. If this mask register is not set by MCU, the zeroization request is aborted by the fuse controller.
1106+2. Issue Zeroization Commands: Trigger zeroization by sending a zeroization command to Caliptra core. Caliptra core will send a sequence of DAI (Direct Access Commands) commands to the fuse controller to perform the zeroization. The recommended order is:
1107+ - Clear the Partition Zeroization Flag: First, send a DAI command to clear this 64-bit flag within the target partition. Executing this step first is critical, as it masks potential ECC or integrity errors if the process is interrupted by a power failure.
1108+ - Zeroize Data Words: Send DAI zeroization commands for all data words within the partition.
1109+ - Clear the Partition Digest: Finally, send a DAI command to clear the partition's digest.
1110+6. Power Cycle the SOC (including Caliptra SS): Apply a cold reset to the Caliptra subsystem. FIPS_zeroization_PPD pin should now be cleared (set low).
1111+8. Verify the Operation: From the main MCU, read the partition's digest value from the associated fuse_ctrl digest registers.
1112+ - Success: If the register returns the expected zeroized digest value, the operation is complete.
1113+ - Failure: If the digest does not match the zeroized value, repeat the entire sequence starting from Step 1.
1114+
1115+## FIPS Zeroization Sequence For ECC
1116+Zeroization is implemented within the fuse controller RTL module. It is therefore the integrator’s responsibility to ensure that the ECC bits in the corresponding fuse partition are also zeroized when a zeroization command is issued to the fuse macro. To achieve this, the integrator must provide a dedicated implementation in the fuse macro wrapper to handle zeroization of the ECC bits.
1117+
1118+## Miscellanious Fuse Integration Guidelines
1119+- If there is a provisioning step where SW (non-secret) and secret partitions need to be programmed within the same reset/power cycle of a SOC, then SW partition needs to be programmed first
1120+- Whenever a secret partition is programmed, it requires a FC reset, implying it requires a SOC reset
1121+- ECC bits inside fuse macros MUST be zeroized per FIPS guidelines. Since these bits are implemented by SOC a a part of OTP gasket, SOC should also implement FIPS zeroization of the ECC for UDS, FE, Ratchet Seeds (OCP lock), any vendor secrets (if required by FIPS).
1122+- FIPS zeroization of the ECC bits of a given partition must be done after the FIPS zeroization of the partition data, zeroization marker and digest.
1123+- UDS & FE MUST ONLY be FIPS zeroized by Caliptra Core (by Subsystem default design construction doesnt allow anyone else to do this operation).
1124+ - DAI Command Error Checking: The Caliptra core is responsible for checking the result of each DAI zeroization command to ensure it completed successfully. Any errors must be handled appropriately.
1125+ - Partitions 0-5 should not be changed by SOC. Don’t add or remove any fields, re-adjust sizes of these partitions as Caliptra ROM may expect them to be of a fixed size.
1126+- Fuse Macro Wrapper Requirements: The fuse_ctrl macro wrapper must implement a retry mechanism for the zeroization process. To prevent damage to the fuses, the wrapper must also avoid double writes to bits that have already been programmed. Please follow the specific integration guidelines provided by your fuse macro vendor.
1127+- OCP Lock ratchet seeds can be FIPS zeroized by MCU
1128+- If FIPS zeroization is required for Vendor Secret Partitions, then SOC shall generate the partition with zeroization flag, validate that the zeroization sequence documented above works as expected and uses MCU to do the FIPS zeroization. Any additional physical security protection of this partition is SOC's responsibility since the use cases are SOC defined.
10861129
10871130 ## How to test : Smoke & more
10881131 The smoke test focuses on ensuring basic functionality and connectivity of the FC & LCC.
@@ -1156,7 +1199,7 @@
11561199 ----------------------------------------------|--------|-----------------------|---------------
11571200 `cptra_ss_fuse_macro_inputs_o.valid_i` | Input | 1 | Valid signal for the command handshake.
11581201 `cptra_ss_fuse_macro_inputs_o.size_i` | Input | [`SizeWidth`-1:0] | Number of native OTP words to transfer, minus one: `2'b00 = 1 native word` ... `2'b11 = 4 native words`.
1159-`cptra_ss_fuse_macro_inputs_o.cmd_i` | Input | [`CmdWidth`-1:0] | OTP command: `7'b1000101 = read`, `7'b0110111 = write`, `7'b1111001 = read raw`, `7'b1100010 = write raw`, `7'b0101100 = initialize`
1202+`cptra_ss_fuse_macro_inputs_o.cmd_i` | Input | [`CmdWidth`-1:0] | OTP command: `7'b1111010 = read`, `7'b1001001 = write`, `7'b1010100 = read raw`, `7'b1100111 = write raw`, `7'b0100000 = initialize`, `7'b0111101 = zeroize`
11601203 `cptra_ss_fuse_macro_inputs_o.addr_i` | Input | [`$clog2(Depth)`-1:0] | OTP word address.
11611204 `cptra_ss_fuse_macro_inputs_o.wdata_i` | Input | [`IfWidth`-1:0] | Write data for write commands.
11621205 `cptra_ss_fuse_macro_outputs_i.fatal_alert_o` | Output | 1 | Fatal alert output from the FC macro. This is connected to a separate alert channel in the instantiating IP. The instantiating IP latches the alert indication and continuously outputs alert events until reset.
@@ -1170,6 +1213,10 @@
11701213 wrapper to store / read the data in raw format without generating nor checking
11711214 integrity information. That means that the wrapper must return the raw,
11721215 uncorrected data and no integrity errors.
1216+
1217+The `zeroize` command instructs the Fuse Macro wrapper to "erase" the addressed
1218+value. As fuses cannot be unset, the typical erase behavior is to set all fuses
1219+of the addressed value to `1`, ideally including the ECC bits.
11731220
11741221 The Fuse Controller Macro wrapper implements the error codes (0x0 - 0x4).
11751222
@@ -1240,16 +1287,17 @@
12401287 - The **CMD register address** must be explicitly provided, even though the other fuse controller registers are laid out consecutively.
12411288
12421289 #### Strap Definitions
1243-- **`cptra_ss_strap_generic_0_i`**
1290+- **`cptra_ss_strap_generic_0_i`**
12441291 A 32-bit input strap that encodes:
12451292 - **Upper 16 bits**: Bit index of the idle status bit (`IDLE_BIT_STATUS`) within `SOC_OTP_CTRL_STATUS`.
12461293 - **Lower 16 bits**: Offset address of `SOC_OTP_CTRL_STATUS` within the `SOC_IFC_REG` space, relative to `SOC_OTP_CTRL_BASE_ADDR`.
12471294
12481295 This allows the ROM to accurately monitor the fuse controller's idle state regardless of partition-induced shifts.
12491296
1250-- **`cptra_ss_strap_generic_1_i`**
1251- A 32-bit input strap that provides the address of the **CMD register**.
1297+- **`cptra_ss_strap_generic_1_i`**
1298+ A 32-bit input strap that provides the address of the **CMD register**.
12521299 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`.
1300+
12531301
12541302 ## FC Macro Test Interface
12551303
@@ -1263,6 +1311,12 @@
12631311 specific, pre-defined test locations shall be readable and programmable. Access
12641312 to debug access interface must also be disabled once the device is in
12651313 mission mode (i.e. PROD life cycle state).
1314+
1315+## Life Cycle OTP Programming Behavior and Integrator Responsibilities
1316+During a life‑cycle transition, the Caliptra Life Cycle Controller performs two OTP write operations to the transition‑counter and life‑cycle‑state fields. This behavior is architecturally defined and required for secure, fault‑resistant state progression. Although only one field changes in each phase, both fields reside within the same OTP word, so the macro receives two programming operations that may include writing some bits to the same value they already hold. This programming pattern is expected and safe for OTP implementations that correctly support word‑level writes, including rewriting a bit with the same value (1 -> 1).
1317+
1318+Integrators must ensure that their OTP macro or wrapper supports rewriting fields without generating errors, and that the macro’s burn semantics align with Caliptra’s assumption that “burn” corresponds to writing a logical 1. If an OTP vendor interprets 0 as a burn operation or cannot tolerate 1 -> 1 writes, the integrator must adapt their wrapper—for example, by inverting the encoding or using per‑bit write‑enable—to ensure compatibility.
1319+
12661320
12671321 # Life Cycle Controller
12681322
@@ -1283,7 +1337,6 @@
12831337 `RndCnstLcKeymgrDivDev` | (see RTL) | Diversification value used for the DEV life cycle state.
12841338 `RndCnstLcKeymgrDivProduction` | (see RTL) | Diversification value used for the PROD/PROD_END life cycle states.
12851339 `RndCnstLcKeymgrDivRma` | (see RTL) | Diversification value used for the RMA life cycle state.
1286-`SecVolatileRawUnlockEn` | 1'b1 | Enables Volatile TEST_UNLOCKED0 state transition infra
12871340
12881341 ## Interface
12891342
@@ -1292,6 +1345,7 @@
12921345 ------------|:-----------|:-------|:----------------------|:------------------------------------|:------- |
12931346 External |input | 1 | `clk_i` | `cptra_ss_clk_i` | clock |
12941347 External |input | 1 | `rst_ni` | `cptra_ss_rst_b_i` | LC controller reset input, active low|
1348+External |input | 1 | `lc_sec_volatile_raw_unlock_en_i` | `cptra_ss_lc_sec_volatile_raw_unlock_en_i` | Enables Volatile TEST_UNLOCKED0 state transition infra|
12951349 External |input | 1 | `raw_unlock_token_hashed_i` | `cptra_ss_raw_unlock_token_hashed_i` | Hashed token for RAW unlock |
12961350 External |input | 1 | `Allow_RMA_or_SCRAP_on_PPD` | `cptra_ss_lc_Allow_RMA_or_SCRAP_on_PPD_i` | This is GPIO strap pin. This pin should be high until LC completes its state transition to RMA or SCRAP.|
12971351 External |interface | 1 | `axi_wr_req` | `cptra_ss_lc_axi_wr_req_i` | LC controller AXI write request input |
@@ -1313,8 +1367,8 @@
13131367 Internal |struct | 1 | `otp_lc_data_i` | | Broadcasted values from the fuse controller |
13141368 Internal |output | 1 | `lc_dft_en_o` | | DFT enable to MCI |
13151369 Internal |output | 1 | `lc_hw_debug_en_o` | | CLTAP enable to MCI |
1316-Internal |output | 1 | `lc_escalate_en_o` | | Broadcast signal to promote esclation in SoC |
1317-Internal |output | 1 | `lc_check_byp_en_o` | | External clock status delivery signal to fuse controller |
1370+Internal |output | 1 | `lc_escalate_en_o` | `cptra_ss_lc_escalate_en_o` | Broadcast signal to promote esclation in SoC |
1371+Internal |output | 1 | `lc_check_byp_en_o` | `cptra_ss_lc_check_byp_en_o` | External clock status delivery signal to fuse controller |
13181372 External |output | 1 | `lc_clk_byp_req_o` | `cptra_ss_lc_clk_byp_req_o` | A request port to swtich from LCC clock to external clock |
13191373 External |input | 1 | `lc_clk_byp_ack_i` | `cptra_ss_lc_clk_byp_ack_i` | Acknowledgment signal to indicate external clock request is accepted |
13201374 Internal |input | 1 | `otp_device_id_i` | | Unused port |
@@ -1343,12 +1397,14 @@
13431397
13441398 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.
13451399
1346- - 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.
1347-
1400+ The Life-cycle Controller requires a token to execute conditional state transitions. All tokens reside within a single partition, which the integrator can lock only once. Therefore, if any required tokens are not programmed before the partition is locked, they will remain at their default value of 0 and cannot be updated afterward.
1401+
1402+ - 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 in the following cycle. 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.
1403+
13481404 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.
13491405
13501406 3. **Scan Path Exclusions**:
1351- - 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.
1407+ - 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 in gates but in a hashed form as other tokens. It is recommended to exclude since it is not provisioned through fuse macro as other tokens.
13521408 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`.
13531409
13541410 4. **RAW Unlock Token**:
@@ -1377,7 +1433,7 @@
13771433 - Write the 128-bit transition token (if required) into the `LC_CTRL_TRANSITION_TOKEN_*_OFFSET` registers.
13781434 - Trigger the state transition by writing `0x1` to `LC_CTRL_TRANSITION_CMD_OFFSET`.
13791435 - 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.
1380- - Each TEST_UNLOCKED state has its own TOKEN (see See [Fuse Memory Map](https://github.com/chipsalliance/caliptra-ss/blob/9022fc2a57bb9af2f3ebc2376b98a807812e2e0f/src/fuse_ctrl/doc/otp_ctrl_mmap.md)).
1436+ - Each TEST_UNLOCKED state has its own TOKEN (see See [Fuse Memory Map](https://github.com/chipsalliance/caliptra-ss/blob/2041523f977f5b24453464eda02008b1bd0f4f66/src/fuse_ctrl/doc/otp_ctrl_mmap.md)).
13811437 - During a state transition, an asserted reset or zeorization command can cause permanent life-cycle state corruption.
13821438
13831439 3. **Token Validation**:
@@ -1414,6 +1470,11 @@
14141470
14151471 4. **Error Scenarios**:
14161472 - Test scenarios where invalid tokens, Fuse errors, or missing RMA straps are injected to validate error handling and system recovery mechanisms.
1473+
1474+5. **MCI Masking Registers for LCC Decoding Signals**:
1475+ - The MCI provides a set of masking registers that allow the SoC integrator to explicitly masks Caliptra Core–debug level, SOC_DFT_EN and SOC_HW_DEBUG_EN. Caliptra Core expresses its debug grant through the `ss_soc_dbg_unlock_level_i` vector, where each bit represents a distinct debug unlock level. These requests are not acted upon directly; instead, they are first AND-masked with SoC-programmed MCI registers to ensure that only integrator-approved debug levels can be enabled.
1476+ - For production debug unlock, the integrator must program `MCI_REG_SOC_PROD_DEBUG_STATE_0` and `MCI_REG_SOC_PROD_DEBUG_STATE_1` MCI registers. Together, these registers form a 64-bit mask that gates `ss_soc_dbg_unlock_level_i`. A debug level is considered enabled only if the corresponding bit is set both in Caliptra Core’s unlock request vector and in the SoC-programmed mask. For example, if Caliptra Core asserts the fifth debug level by setting `ss_soc_dbg_unlock_level_i[4]`, the integrator must also set bit of `MCI_REG_SOC_PROD_DEBUG_STATE[1:0][4]` for that level to take effect.
1477+ - The same masking mechanism applies to SOC_DFT_EN enable and SOC_HW_DEBUG_EN. For these, MCI offers `MCI_REG_SOC_DFT_EN_0`, `MCI_REG_SOC_DFT_EN_1` and `MCI_REG_SOC_HW_DEBUG_EN_0`, `MCI_REG_SOC_HW_DEBUG_EN_1` mask registers. These are also masked with `ss_soc_dbg_unlock_level_i`. If this masking (AND operation) results in a value that has `1` in it. The corresponding enable signal is set to high.
14171478
14181479 ## How to Test: Smoke & More
14191480
@@ -1804,8 +1865,7 @@
18041865
18051866 | Bits | Name | Description |
18061867 | :---- | :---- | :---- |
1807-| 63:1 | RESERVED | No allocated function |
1808-| 0 | FIPS_ZEROIZATION_PPD_i | [FIPS zeroization](CaliptraSSHardwareSpecification.md#zeroization-flow-for-secret-fuses) request sampled by MCU ROM. If FIPS zeroization is required, this signal shall be set before Caliptra SS is out of reset. If set, MCU ROM will set MASK register triggering FIPS zeroization flow. If this signal is toggled at runtime it shall be ignored. |
1868+| 63:0 | RESERVED | No allocated function |
18091869
18101870
18111871 **Table: MCI Generic Output Allocation**
@@ -2332,10 +2392,16 @@
23322392 1. **Main target** : Main target is responsible for any flows other than recovery or streaming boot.
23332393 2. **Recovery target** : Recovery target is dedicated to streaming boot / recovery interface.
23342394
2335-- 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:
2395+The I3C core 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:
23362396 - [I3C Core Documentation](https://chipsalliance.github.io/i3c-core/)
23372397 - [Caliptra Subsystem Hardware Specification Document](CaliptraSSHardwareSpecification.md)
23382398 - [I3C Core Registers](https://github.com/chipsalliance/i3c-core/tree/main/src/rdl)
2399+
2400+The I3C core can be configured as an [AXI Recovery interface](CaliptraSSHardwareSpecification.md#axi-streaming-boot-recovery-interface). In this mode, the I3C endpoint is disabled as all internal FIFOs are repurposed for the recovery stream.
2401+
2402+**IMPORTANT**:
2403+- **Static Configuration**: The I3C core must be statically configured during the MCU boot flow as either an I3C Target or an AXI Recovery Interface. This selection is mutually exclusive and cannot be changed dynamically.
2404+- **Dual-Functionality**: If the SoC requires both AXI Recovery and standard I3C Target functionality, a second I3C core must be instantiated outside of Caliptra SS.
23392405
23402406 ## Integration Considerations
23412407
@@ -2607,7 +2673,7 @@
26072673 | CPTRA_SS_PRIM_RST | Primary reset input corresponding to SOC Warm Reset | cptra_ss_rst_b_i | caliptra_top_dut.soc_ifc_top1.soc_ifc_reg_hwif_out.CPTRA_FUSE_WR_DONE.done.value -> HIGH <br> i3c.i3c.xrecovery_handler.xrecovery_executor.image_activated_o -> LOW <br> i3c.i3c.xrecovery_handler.xrecovery_executor.payload_available_q -> LOW | CPTRA_SS_PRIM_RST -> CPTRA_CORE_UC_RST <br> CPTRA_SS_PRIM_RST -> CPTRA_CORE_NON_CORE_RST <br> CPTRA_SS_PRIM_RST -> CPTRA_SS_RST <br> CPTRA_SS_PRIM_RST -> CPTRA_SS_MCU_RST |
26082674 | CPTRA_SS_RST | Caliptra SS MCI Boot Sequencer generated reset used by various other SS level logic blocks and Caliptra Core | cptra_ss_mci_cptra_rst_b_i <br> mci_top_i.i_boot_seqr.cptra_ss_rst_b_o | mci_top_i.i_boot_seqr.rdc_clk_dis -> HIGH <br> mci_top_i.i_boot_seqr.early_warm_reset_warn -> HIGH <br> mci_top_i.i_boot_seqr.boot_fsm[3:0] = BOOT_IDLE <br> i3c.i3c.xrecovery_handler.xrecovery_executor.image_activated_o -> LOW <br> i3c.i3c.xrecovery_handler.xrecovery_executor.payload_available_q -> LOW <br> caliptra_top_dut.soc_ifc_top1.soc_ifc_reg_hwif_out.CPTRA_FUSE_WR_DONE.done.value -> HIGH | CPTRA_SS_RST -> CPTRA_SS_PRIM_RST <br> CPTRA_SS_RST -> CPTRA_CORE_NON_CORE_RST <br> CPTRA_SS_RST -> CPTRA_CORE_UC_RST <br> CPTRA_SS_RST -> CPTRA_SS_MCU_RST <br> CPTRA_SS_RST -> CPTRA_DMI_NON_CORE_RST |
26092675 | CPTRA_CORE_NON_CORE_RST | Caliptra Core Boot FSM generated reset used by various other Caliptra Core logics | caliptra_top_dut.soc_ifc_top1.i_soc_ifc_boot_fsm.cptra_noncore_rst_b | caliptra_top_dut.soc_ifc_top1.i_soc_ifc_boot_fsm.rdc_clk_dis -> HIGH <br> caliptra_top_dut.soc_ifc_top1.i_soc_ifc_boot_fsm.arc_IDLE -> HIGH <br> mci_top_i.i_boot_seqr.rdc_clk_dis -> HIGH | CPTRA_CORE_NON_CORE_RST -> CPTRA_SS_RST <br> CPTRA_CORE_NON_CORE_RST -> CPTRA_SS_PRIM_RST <br> CPTRA_CORE_NON_CORE_RST -> CPTRA_CORE_UC_RST <br> CPTRA_CORE_NON_CORE_RST -> CPTRA_SS_MCU_RST |
2610-| CPTRA_CORE_UC_RST | Caliptra Core Boot FSM generated microcontroller reset for Caliptra Core RISCV | caliptra_top_dut.soc_ifc_top1.i_soc_ifc_boot_fsm.cptra_uc_rst_b | caliptra_top_dut.soc_ifc_top1.i_soc_ifc_boot_fsm.fw_update_rst_window -> HIGH <br> caliptra_top_dut.aes_inst.aes_inst.u_aes_core.u_aes_control.gen_fsm[0].gen_fsm_p.u_aes_control_fsm_i.u_aes_control_fsm.aes_ctrl_cs[5:0] -> 6'b001001 ||
2676+| CPTRA_CORE_UC_RST | Caliptra Core Boot FSM generated microcontroller reset for Caliptra Core RISCV | caliptra_top_dut.soc_ifc_top1.i_soc_ifc_boot_fsm.cptra_uc_rst_b | caliptra_top_dut.soc_ifc_top1.i_soc_ifc_boot_fsm.fw_update_rst_window -> HIGH <br> caliptra_top_dut.aes_inst.aes_inst.u_aes_core.u_aes_control.gen_fsm[0].gen_fsm_p.u_aes_control_fsm_i.u_aes_control_fsm.aes_ctrl_cs[5:0] -> 6'b001001 <br> caliptra_top_dut.sha3.hsel_i -> LOW <br> caliptra_top_dut.aes_inst.aes_cif_req_dv -> LOW ||
26112677 | CPTRA_SS_MCU_RST | Caliptra SS MCI Boot Sequencer generated microcontroller reset for Caliptra SS RISCV | mci_top_i.i_boot_seqr.mcu_rst_b | mci_top_i.i_boot_seqr.fw_update_rst_window -> HIGH <br> mci_top_i.i_mci_mcu_trace_buffer.mcu_trace_rv_i_valid_ip -> LOW ||
26122678
26132679