Changes to Subsystem Hardware Specification

Comparing version 2.1 to 2.0
+364 additions -269 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/CaliptraSSHardwareSpecification.md" target="_blank">chipsalliance/caliptra-ss/docs/CaliptraSSHardwareSpecification.md</a> @ <code>9022fc2</code>
2+đź“„ Source: <a href="https://github.com/chipsalliance/caliptra-ss/blob/2041523f977f5b24453464eda02008b1bd0f4f66/docs/CaliptraSSHardwareSpecification.md" target="_blank">chipsalliance/caliptra-ss/docs/CaliptraSSHardwareSpecification.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 Hardware 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)
@@ -36,10 +36,15 @@
3636 - [I3C Streaming Boot (Recovery) Flow](#i3c-streaming-boot-recovery-flow)
3737 - [Caliptra ROM Requirements for OCP Streaming Boot](#caliptra-rom-requirements-for-ocp-streaming-boot)
3838 - [I3C and Caliptra-AXI Interactions](#i3c-and-caliptra-axi-interactions)
39+- [AXI Streaming Boot (Recovery) Interface](#axi-streaming-boot-recovery-interface)
40+ - [AXI Streaming Boot Flow implementation](#axi-streaming-boot-flow-implementation)
41+ - [AXI Streaming Boot Handler](#axi-streaming-boot-handler)
42+ - [AXI Streaming Boot CSRs](#axi-streaming-boot-csrs)
3943 - [Caliptra Core AXI Manager \& DMA assist](#caliptra-core-axi-manager--dma-assist)
4044 - [AXI Feature Support](#axi-feature-support)
4145 - [Routes](#routes)
4246 - [OCP Streaming Boot Payloads](#ocp-streaming-boot-payloads)
47+ - [AES Mode](#aes-mode)
4348 - [Programming Flowchart {#programming-flowchart}](#programming-flowchart-programming-flowchart)
4449 - [Descriptor](#descriptor)
4550 - [Caliptra Subsystem Fuse Controller](#caliptra-subsystem-fuse-controller)
@@ -51,10 +56,6 @@
5156 - [Locking the Validated Public Key Partition](#locking-the-validated-public-key-partition)
5257 - [Hardware Integrity Checker](#hardware-integrity-checker)
5358 - [Purpose](#purpose)
54- - [Zeroization Flow for Secret FUSEs](#zeroization-flow-for-secret-fuses)
55- - [Conditions for Zeroization](#conditions-for-zeroization)
56- - [Zeroization Process](#zeroization-process)
57- - [Cold Reset and Final Zeroization](#cold-reset-and-final-zeroization)
5859 - [Notes](#notes)
5960 - [General Guidance](#general-guidance)
6061 - [Reset Considerations](#reset-considerations)
@@ -66,7 +67,7 @@
6667 - [LCC State and State Decoder Output Ports](#lcc-state-and-state-decoder-output-ports)
6768 - [TAP Pin Muxing](#tap-pin-muxing)
6869 - [How does Caliptra Subsystem enable manufacturing debug mode?](#how-does-caliptra-subsystem-enable-manufacturing-debug-mode)
69- - [Flow Explanation:](#flow-explanation)
70+ - [Flow Explanation](#flow-explanation)
7071 - [Production Debug Unlock Architecture](#production-debug-unlock-architecture)
7172 - [Overview of Debug Unlock Initiation](#overview-of-debug-unlock-initiation)
7273 - [Secure Debug Unlock Protocol](#secure-debug-unlock-protocol)
@@ -121,33 +122,36 @@
121122 - [MCI Design for Test (DFT)](#mci-design-for-test-dft)
122123 - [Reset Controls](#reset-controls)
123124
124-
125125 # Scope
126126
127127 This document defines technical specifications for a subsystem design utilizing Caliptra RoT in Subystem Mode. This document, along with [Caliptra Hardware Specification](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraHardwareSpecification.md), shall comprise the Caliptra Subsystem technical specification.
128128
129129 ## Document Version
130+
130131 <div align="center">
131132
132133 | Date | Document Version | Description |
133134 | ----------------- | -------------------- | ------------------- |
134135 | Jan 31st, 2025 | v0p8 | Work in progress |
135-| Apr 30th, 2025 | v1p0-rc1 | Initial release candidate of Caliptra Gen 2.0 Subsystem Documents.<br>Specifications updated with:<br> - Updated details on component features (MCU mailbox, MCU trace buffer, MCI error aggregation, FC fuse zeroization)<br> - Details on design connectivity with top-level ports<br> - Port and register updates |
136-| Oct 29th, 2025 | v2.0.1 | Patch release of 2.0.1 with clarifications on several doc sections |
136+| Apr 30th, 2025 | v1p0-rc1 | Initial release candidate of Caliptra Gen 2.0 Subsystem Documents.<br>Specifcations updated with:<br> - Updated details on component features (MCU mailbox, MCU trace buffer, MCI error aggregation, FC fuse zeroization)<br> - Details on design connectivity with top-level ports<br> - Port and register updates |
137+| Oct 12th, 2025 | v2p1 | Final release of Caliptra Subsystem 2.1 |
137138
138139
139140 </div>
140141
141142 # Caliptra Subsystem Requirements
143+
142144 ## Definitions
143-* RA: Recovery Agent / Streaming boot Agent
144-* MCI: Manufacturer Control Interface
145-* MCU: Manufacturer Control Unit
146-
145+- RA: Recovery Agent / Streaming boot Agent
146+- MCI: Manufacturer Control Interface
147+- MCU: Manufacturer Control Unit
148+
147149 ## Caliptra-Passive-Mode (Legacy)
150+
148151 SOC manages boot media peripherals and Caliptra is used as Root of trust for measurements.
149152
150-## Caliptra-subsystem-mode
153+## Caliptra-subsystem-mode
154+
151155 Caliptra owns the recovery interface (peripheral independent) and Caliptra is THE RoT of the SoC. Any SOC specific variables that needs to be stored and retrieved securely from NV storage is handled using Caliptra.
152156
153157 ## Caliptra Subsystem Architectural Requirements
@@ -156,7 +160,9 @@
156160 2. MCU will use Caliptra RT FW to auth/measure/load all of the FW belonging to the SOC.
157161 3. MCU ROM/FW on MCU should be capable of performing SOC specific initialization.
158162 4. MCU ROM/FW should be able to perform SoC management functions including performing reset control, SoC specific security policy enforcement, SOC initial configuration (eg. any GPIO programming, glitch detection circuits, reading/moving non-secret fuses etc.).
159- * Note: Widgets that toggle the reset or other wires that set security permissions are SOC specific implementations.
163+
164+- Note: Widgets that toggle the reset or other wires that set security permissions are SOC specific implementations.
165+
160166 6. Fuse controller for provisioning Caliptra fuses -> IFP (In-field programmable) fusing is performed by MCU RT; SW partition fuses in fuse controller are managed by MCU (ROM or RT); Caliptra HW is responsible for reading the secret fuses (Caliptra ROM, MCU ROM or any other SOC ROM or any RT FW should NOT have access to read the secret fuses in production).
161167 7. Recovery stack must be implemented. Please refer to I3C recovery section for more details and references.
162168 OCP Recovery registers implemented in I3C must follow the security filtering requirements specified in the recovery implementation spec (eg. MCU can ONLY access subset of the recovery registers as defined by the recovery implementation).
@@ -173,30 +179,35 @@
173179 ## Caliptra Subsystem HW Requirements
174180
175181 ### Caliptra 2.0 HW requirements (Subsystem Support)
182+
176183 1. Full AXI read/write channels (aka AXI manager) for subsystem (for MCU and Caliptra)
177184 a. For backward compatibility, AXI mgr. interface can be a no-connect and that configuration is validated.
178185 2. HW logic/Programmable DMA
179- * Read MMIO space for variable length.
180- * Data returned from the above read can be exposed directly to the FW OR allow it to be written to a subsystem/SOC destination as programmed by ROM/FW.
181- * Programmable logic to allow for SOC directed writes (from FW or from the above route back) to be sent through the SHA accelerator.
182- * (Future open/stretch goal): If AES engine accelerator is integrated into Caliptra, then implement decryption before sending the writes back to the destination programmed by the ROM/FW.
183- * This widget should have accessibility in manufacturing and debug mode over JTAG (can be exposed using the same JTAG interface as Caliptra 1.0). Ensure through validation that no asset can be read using this widget in those modes.
186+
187+- Read MMIO space for variable length.
188+- Data returned from the above read can be exposed directly to the FW OR allow it to be written to a subsystem/SOC destination as programmed by ROM/FW.
189+- Programmable logic to allow for SOC directed writes (from FW or from the above route back) to be sent through the SHA accelerator.
190+- (Future open/stretch goal): If AES engine accelerator is integrated into Caliptra, then implement decryption before sending the writes back to the destination programmed by the ROM/FW.
191+- This widget should have accessibility in manufacturing and debug mode over JTAG (can be exposed using the same JTAG interface as Caliptra 1.0). Ensure through validation that no asset can be read using this widget in those modes.
192+
184193 3. Expand manuf flow register to include UDS programming request steps
185194 4. SOC Key Release HW (Required for OCP Lock flow too)
186- * Separate SOC Key Vault must be implemented (it is a separate structure from the current Caliptra KV).
187- * In at least one configuration, the SOC KV must be implemented as an SRAM that is external and configurable by the SOC OR or an internal configurable SOC KV structure. If this is achievable within the Caliptra 2.0 milestone, only one of these would be the chosen implementation and configuration. This will be a design decision based on effort & schedule.
188- * If implemented as a SRAM, data written and read into the SOC KV SRAM is decrypted & encrypted so that SOC DFT or other side channels cannot exfilterate the data.
189- * Caliptra FW will indicate to the SOC KV Release HW to release the key by supplying the key handle to read from.
190- * Destination address to which the key must be written to is programmed by the Caliptra FW into AXI MGR DMA HW.
191- * SOC KV must have the same attributes as Caliptra internal KV. Additionally, it must also have an attribute of read-once and clear.
195+
196+- Separate SOC Key Vault must be implemented (it is a separate structure from the current Caliptra KV).
197+- In at least one configuration, the SOC KV must be implemented as an SRAM that is external and configurable by the SOC OR or an internal configurable SOC KV structure. If this is achievable within the Caliptra 2.0 milestone, only one of these would be the chosen implementation and configuration. This will be a design decision based on effort & schedule.
198+- If implemented as a SRAM, data written and read into the SOC KV SRAM is decrypted & encrypted so that SOC DFT or other side channels cannot exfilterate the data.
199+- Caliptra FW will indicate to the SOC KV Release HW to release the key by supplying the key handle to read from.
200+- Destination address to which the key must be written to is programmed by the Caliptra FW into AXI MGR DMA HW.
201+- SOC KV must have the same attributes as Caliptra internal KV. Additionally, it must also have an attribute of read-once and clear.
192202
193203 ### Caliptra 2.0 HW requirements (Not subsystem related)
204+
194205 1. Ability to use two or more cryptos concurrently
195206 2. Change APB -> AXI-Sub with the same capabilities (AXI USERID filtering replaces PAUSER based filtering, multiple targets for SHA acc, mailbox, fuses, registers etc. all)
196207 3. Future/Stretch Goal: Parity support on AXI-SUB & MGR
197208
198-
199209 ### MCU HW requirements
210+
200211 1. MCU should not be in the FIPS boundary and must not have any crypto functions. MCU must use Caliptra for any security flows (eg. security policy authorization) or traditional RoT support (eg. SPDM).
201212 2. MCU VeeR must support PMP & User mode.
202213 3. MCU AXI is directly connected to the SOC fabric in a way that allows a MMIO based control of the SoC as required for SOC security, manageability and boot functionality.
@@ -205,17 +216,21 @@
205216 6. MCU uses instruction cache for speed up
206217 7. It is required that all NV read/writes (eg. NV variables in flash) that require a RoT support to securely store/restore must go through Caliptra.
207218 8. NV-storage peripheral shall be built in such a way that it will only accept transactions from MCU.
208-9. Support for MCU first fetch vector to direct towards MCU SRAM post reset
209-
219+9. Support for MCU first fetch vector to direct towards MCU SRAM post reset
210220
211221 ### Subsystem Components HW requirements
222+
212223 #### Fabric
224+
213225 1. AXI Interconnect connects Caliptra, I3C, Fuse Controller, Life Cycle Controller, MCU and its memory components with the rest of the SOC.
214- * **Note:** Because each SOC integration model is different, AXI interconnect is NOT implemented by the subsystem but subsystem must validate using an AXI interconnect VIP to ensure all the components operate per the flows documented in this specification.
215- * For the VIP interconnect configuration, all subtractively decoded transactions are sent towards SoC. AXI interconnect & Subsystem is validated with the assumption that all of them are running on the same clock domain.
226+
227+- **Note:** Because each SOC integration model is different, AXI interconnect is NOT implemented by the subsystem but subsystem must validate using an AXI interconnect VIP to ensure all the components operate per the flows documented in this specification.
228+- For the VIP interconnect configuration, all subtractively decoded transactions are sent towards SoC. AXI interconnect & Subsystem is validated with the assumption that all of them are running on the same clock domain.
229+
216230 2. To be documented: AXI-USERID requirements
217231
218-#### MCU SRAM
232+#### MCU SRAM
233+
219234 1. Since it's used for instruction and data execution – therefore requires AXI Sub with USERID filtering.
220235 2. Provide JTAG accessibility to allow for SRAM to be populated in a secured debug mode at power on time (debug policies will be same as Caliptra)
221236 3. MCU SRAM should have an aperture that can only be unlocked by Caliptra after it loads the image
@@ -223,17 +238,19 @@
223238 5. MCU SRAM supports an aperture to be used as a MCU Mailbox.
224239
225240 #### MCU ROM
226-* MCU ROM also needs to have AXI Sub for any data access from MCU and thereby requires AXI-ID/USERID filtering.
227-
228-#### I3C
241+- MCU ROM also needs to have AXI Sub for any data access from MCU and thereby requires AXI-ID/USERID filtering.
242+
243+#### I3C
244+
229245 1. I3C on AXI interconnect with AXI Subordinate
230246 2. Spec 1.1.1 aligned, but only with optional features that are required per PCIe ECN # <>
231247 3. AXI Sub must be supported.
232248 4. UserID to MCU and Caliptra
233249 5. MCU access lock for I3C recovery and data (FIFO) registers until recovery flow is completed. In other words, MCU ROM must not impact the data flow into Recovery IFC registers.
234-Stretch Goal: DMA data payload back to destination (Caliptra or MCU)
250+Stretch Goal: DMA data payload back to destination (Caliptra or MCU)
235251
236252 #### Fuse Controller
253+
237254 1. AXI sub interface
238255 2. Secrets (separate USERID and access constraints) vs SW partition separation
239256 3. Registers implemented for “Secrets” should follow the same rules as Caliptra (no scan, clear on specific life cycle/security states)
@@ -242,7 +259,7 @@
242259 6. When debug mode is intended to be enabled & when enabled, all secrets/assets as defined should be wiped and provide the indication to SOC for any secrets/assets it may have.
243260
244261 #### MCI
245-* HW logic to move secret fuses from Fuse controller to Caliptra.
262+- HW logic to move secret fuses from Fuse controller to Caliptra.
246263
247264 ## Caliptra Subsystem Hardware Block Diagram
248265
@@ -250,19 +267,22 @@
250267
251268 ![](https://github.com/chipsalliance/Caliptra/blob/main/doc/images/Subsystem.png)
252269
253-
254270 # Caliptra Subsystem Architectural Flows
271+
255272 Please refer to [Caliptra Security Subsystem Specification](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#caliptra-security-subsystem) for more details.
256273
257274 # I3C Streaming Boot (Recovery) Interface
275+
258276 The I3C recovery interface acts as a standalone I3C target device for recovery. It will have a unique address compared to any other I3C endpoint for the device. It will comply with I3C Basic v1.1.1 specification. It will support I3C read and write transfer operations. It must support Max read and write data transfer of 1-256B excluding the command code (1 Byte), length (2 Byte), and PEC (1 Byte), total 4 Byte I3C header. Therefore, max recovery data per transfer will be limited to 256-byte data.
259-
260-I3C recovery interface is responsible for the following list of actions:
277+
278+I3C recovery interface is responsible for the following list of actions:
279+
261280 1. Responding to command sent by Recovery Agent (RA)
262281 2. Updating status registers based on interaction of AC-RoT and other devices
263282 3. Asserting / Deasserting “payload_available” & “image_activated” signals
264283
265284 ## Streaming Boot (Recovery) Interface hard coded logic
285+
266286 Hardware registers size is fixed to multiple of 4 bytes, so that firmware can read or write with word boundary. Address offset will be programmed outside of the I3C device. Register access size must be restricted to individual register space and burst access with higher size must not be allowed.
267287
268288 *Figure: I3C Streaming Boot (Recovery) Interface Logic Block Diagram*
@@ -270,20 +290,24 @@
270290 ![](../images/caliptra-ss/docs/images/I3C-Recovery-IFC.png)
271291
272292 ## Hardware Registers
293+
273294 Hardware registers size is fixed to multiple of 4 bytes, so that firmware can read or write with word boundary. Address offset will be programmed outside of the I3C device. Register access size must be restricted to individual register space and burst access with higher size must not be allowed.
274295
275-**Note:** Accessing the same address for INDIRECT_FIFO_DATA register will write or read the FIFO. It will not be available to access randomly as specified by the specification.
296+**Note:** Accessing the same address for INDIRECT_FIFO_DATA register will write or read the FIFO. It will not be available to access randomly as specified by the specification.
276297
277298 **TODO:** Add a link to rdl -> html file
278299
279300 ## Streaming Boot (Recovery) Interface Wires
280-
301+
281302 1. **Payload available**
282- * The Recovery Interface (I3C target) should receive a write transaction to INDIRECT_FIFO_DATA reg from BMC - 256B + 4B (Header), and wait for each I3C write to finish. Once I3C write transaction to INDIRECT_FIFO_DATA register is completed and PEC verification is successful, then the I3C target must assert "payload_available". DMA assist must wait for "payload_available" before reading. It must read 256B or last read with remaining data.
283- * The "payload_available" signal remains asserted until Recovery Interface receives Read from DMA over AXI for INDIRECT_FIFO_DATA.
303+
304+- The Recovery Interface (I3C target) should receive a write transaction to INDIRECT_FIFO_DATA reg from BMC - 256B + 4B (Header), and wait for each I3C write to finish. Once I3C write transaction to INDIRECT_FIFO_DATA register is completed and PEC verification is successful, then the I3C target must assert "payload_available". DMA assist must wait for "payload_available" before reading. It must read 256B or last read with remaining data.
305+- The "payload_available" signal remains asserted until Recovery Interface receives Read from DMA over AXI for INDIRECT_FIFO_DATA.
306+
284307 2. **Image_activated**
285- * The I3C target will assert "image_activated" signal as soon as write to RECOVERY_CTRL register is received.
286- * ROM will clear “image_activated” bit by writing to RECOVERY_CTRL register via DMA assist after the image is authenticated. As defined in the OCP Recovery Specification, RECOVERY_CTRL, byte 2 is used to specify the image activation control, and is Write-1-Clear. ROM must write 0xFF to this field to clear the image recovery status, which will also result in the Recovery Interface deasserting the “image_activated” signal to Caliptra.
308+
309+- The I3C target will assert "image_activated" signal as soon as write to RECOVERY_CTRL register is received.
310+- ROM will clear “image_activated” bit by writing to RECOVERY_CTRL register via DMA assist after the image is authenticated. As defined in the OCP Recovery Specification, RECOVERY_CTRL, byte 2 is used to specify the image activation control, and is Write-1-Clear. ROM must write 0xFF to this field to clear the image recovery status, which will also result in the Recovery Interface deasserting the “image_activated” signal to Caliptra.
287311
288312 ## I3C Streaming Boot (Recovery) Flow
289313
@@ -293,16 +317,58 @@
293317 ![](../images/caliptra-ss/docs/images/CSS-Recovery-Flow.png)
294318
295319 ## Caliptra ROM Requirements for OCP Streaming Boot
320+
296321 Caliptra firmware must follow these rules when implementing the OCP Streaming Boot flow:
297322 * Caliptra ROM and RT Firmware must wait for "image_activated" signal to assert before processing the image.
298323 * When image is sent to Caliptra Subsystem, Caliptra ROM & RT firmware must program DMA assist according to the rules defined in [OCP Streaming Boot Payloads](#ocp-streaming-boot-payloads).
299324 * Once the image is processed, Caliptra ROM & RT firmware must initiate a write with data 1 via DMA to clear byte 2 “Image_activated” of the RECOVERY_CTRL register. This will allow BMC (or streaming boot initiator) to initiate subsequent image writes.
300325
301326 ## I3C and Caliptra-AXI Interactions
327+
302328 Received transfer data can be obtained by the driver via a read from XFER_DATA_PORT register. Received data threshold is indicated to BMC by the controller with TX_THLD_STAT interrupt if RX_THLD_STAT_EN is set. The RX threshold can be set via RX_BUF_THLD. In case of a read when no RX data is available, the controller shall raise an error on the frontend bus interface (AHB / AXI).
303329
330+# AXI Streaming Boot (Recovery) Interface
331+
332+This feature allows streaming data or firmware by MCU over the AXI bus of the I3C module which is repurposed as a streaming boot interface while disabling I3C usage.
333+
334+## AXI Streaming Boot Flow implementation
335+
336+The AXI Streaming Boot flow reuses the logic already present in the I3C core used in the Caliptra-SS design, with a runtime option essentially bypassing most of the I3C core communication logic (including the I3C recovery flow logic).
337+The loopback functionality is configurable via the [REC_INTF_CFG](https://chipsalliance.github.io/i3c-core/registers.html#rec-intf-cfg-register) CSR which is set to I3C mode by default.
338+Streaming boot CSRs are accessible over AXI.
339+The transactions to the I3C core may be filtered using the AXI ID field.
340+The logic is implemented so that the streaming boot implementation in the Caliptra core (HW & ROM) can operate without any changes.
341+In order to enable setting W1C streaming boot registers, AXI streaming mode introduces an additional register - `REC_INTF_REG_W1C_ACCESS`.
342+
343+## AXI Streaming Boot Handler
344+
345+In the regular (I3C) mode of the core, the Streaming Boot (Recovery) Handler strongly relies on the communication with the I3C Core internal logic by interfacing with TTI Queues.
346+The bypass implementation modifies the I3C Core logic to allow direct access over the AXI bus to the structures specified by the OCP Streaming boot for compliance with the [Caliptra Subsystem Streaming Boot Sequence](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#caliptra-subsystem-streaming-boot-interface-hardware).
347+
348+The default design of the Streaming Boot Handler includes many blocks specifically designed to translate I3C bus traffic into recovery messages.
349+It also automatically responds to the I3C commands by writing transaction descriptors and data for the TTI Queues.
350+
351+*Figure: Streaming Boot (Recovery) Handler in the I3C Core*
352+![](../images/caliptra-ss/docs/images/AXI-Recovery-Handler.png)
353+
354+In order enable the AXI streaming boot mechanism while reusing the existing logic and keeping compliance with Caliptra, the I3C core provides a custom bypass feature allowing direct communication with the Streaming Boot Handler via the AXI bus.
355+The bypass disables the I3C communication logic.
356+Data is routed from the TTI TX Queue to the Recovery Executor block, and written directly to the Indirect Data FIFO.
357+The Caliptra ROM can access the data from the Indirect FIFO over the AXI bus (the same way it does in the regular I3C streaming boot flow).
358+The dataflow in bypass mode (marked with green arrows) is depicted in the diagram below.
359+
360+*Figure: AXI Streaming Boot Handler in I3C Bypass Mode*
361+![](../images/caliptra-ss/docs/images/AXI-Recovery-Handler-Bypass.png)
362+
363+## AXI Streaming Boot CSRs
364+
365+With the bypass feature enabled, the FIFO status CSRs in the Streaming Boot CSR file will be updated by the Streaming Bott Handler module.
366+However, some registers like e.g. `INDIRECT_FIFO_CTRL` which are updated by I3C commands in a standard streaming boot flow, will have to be accessed and configured properly from the software running on the Caliptra MCU via the AXI bus.
367+All configurable registers are writable from software, read only registers provide status information about Streaming Boot Handler internals, e.g. details about size and fill level of the Indirect FIFO.
368+
304369 # Caliptra Core AXI Manager & DMA assist
305-SOC\_IFC includes a hardware-assist block that is capable of initiating DMA transfers to the attached SoC AXI interconnect. The DMA transfers include several modes of operation, including raw transfer between SoC (AXI) addresses, moving data into or out of the SOC\_IFC mailbox, and directly driving data through AHB CSR accesses to datain/dataout registers. One additional operating mode allows the DMA engine to autonomously wait for data availability via the OCP Recovery interface (which will be slowly populated via an I3C or similar interface).
370+
371+SOC\_IFC includes a hardware-assist block that is capable of initiating DMA transfers to the attached SoC AXI interconnect. The DMA transfers include several modes of operation, including raw transfer between SoC (AXI) addresses, moving data into or out of the SOC\_IFC mailbox, directly encrypting/decrypting images with the AES block, and directly driving data through AHB CSR accesses to datain/dataout registers. One additional operating mode allows the DMA engine to autonomously wait for data availability via the OCP Recovery interface (which will be slowly populated via an I3C or similar interface).
306372
307373 Caliptra arms transfers by populating a transaction descriptor to the AXI DMA CSR block via register writes over the internal AHB bus. Once armed, the DMA will autonomously issue AXI transactions to the SoC until the requested data movement is completed. The DMA uses an internal FIFO to buffer transfer data. For any transfer using AXI Writes (Write Route is not disabled), the DMA waits until sufficient data is available in the FIFO before initiating any AXI write requests.
308374
@@ -311,18 +377,19 @@
311377 ![](../images/caliptra-ss/docs/images/Caliptra-AXI-DMA.png)
312378
313379 ## AXI Feature Support
380+
314381 The DMA assist initiates transactions on the AXI manager interface in compliance with the AXI specification. The generated AXI transactions adhere to the following rules:
315-* All address requests will be aligned to the data width of the interface, which is configured as 32-bit in the 2.0 release.
316-* The DMA will not issue Narrow transfers. That is, AxSIZE will always be set to match the data width of the interface (4 bytes).
317-* All data lanes are used on all transfers. That is, the AXI manager Write channel will always set WSTRB to all 1s.
318-* At most, 2 reads and 2 writes will be initiated at any time.
319- * When using a non-zero block\_size for the transfer, in accordance with the [Streaming Boot](#Streaming-Boot-Payloads) feature, at most 1 read and 1 write will be issued concurrently.
320-* All transactions are initiated with AxID = 0, meaning that both reads and writes require in-order responses.
321-* The maximum burst length initiated is constrained by the following parameters:
322- * Any transfer using the INCR burst type is restricted by both the maximum allowable length of an AXI transaction (AxLEN=255 or total byte count of 4KiB, whichever is smaller) and the size of the internal FIFO. In the 2.0 release the internal FIFO is configured with a depth of 512 bytes; the maximum transaction size allowed is 256 bytes, to allow up to 2 transactions to be outstanding at a time. In summary, the transfer size will always be 256 bytes or less (AxLEN = 63), as this is the smallest of (AxLEN = 255 -> 1KiB, 4KiB, and 256 bytes).
323- * Any transfer using the FIXED burst type is restricted by the AXI specification to a burst length of 16.
324- * When the block\_size field is set to a non-zero value when arming the DMA, all transfers are restricted in size to specified block_size, in bytes.
325- * AXI transactions must not cross a 4KiB boundary, per the specification. If the transfer size requires crossing a boundary, the DMA will break it into smaller transactions that will go up to the boundary, then start from the next alignment boundary.
382+- All address requests will be aligned to the data width of the interface, which is configured as 32-bit in the 2.0 release.
383+- The DMA will not issue Narrow transfers. That is, AxSIZE will always be set to match the data width of the interface (4 bytes).
384+- All data lanes are used on all transfers. That is, the AXI manager Write channel will always set WSTRB to all 1s.
385+- At most, 2 reads and 2 writes will be initiated at any time.
386+ - When using a non-zero block\_size for the transfer, in accordance with the [Streaming Boot](#Streaming-Boot-Payloads) feature, at most 1 read and 1 write will be issued concurrently.
387+- All transactions are initiated with AxID = 0, meaning that both reads and writes require in-order responses.
388+- The maximum burst length initiated is constrained by the following parameters:
389+ - Any transfer using the INCR burst type is restricted by both the maximum allowable length of an AXI transaction (AxLEN=255 or total byte count of 4KiB, whichever is smaller) and the size of the internal FIFO. In the 2.0 release the internal FIFO is configured with a depth of 512 bytes; the maximum transaction size allowed is 256 bytes, to allow up to 2 transactions to be outstanding at a time. In summary, the transfer size will always be 256 bytes or less (AxLEN = 63), as this is the smallest of (AxLEN = 255 -> 1KiB, 4KiB, and 256 bytes).
390+ - Any transfer using the FIXED burst type is restricted by the AXI specification to a burst length of 16.
391+ - When the block\_size field is set to a non-zero value when arming the DMA, all transfers are restricted in size to specified block_size, in bytes.
392+ - AXI transactions must not cross a 4KiB boundary, per the specification. If the transfer size requires crossing a boundary, the DMA will break it into smaller transactions that will go up to the boundary, then start from the next alignment boundary.
326393
327394 ## Routes
328395
@@ -344,130 +411,177 @@
344411
345412 ![](../images/caliptra-ss/docs/images/Caliptra-AXI-DMA-RD-WR.png)
346413
347-
348414 ## OCP Streaming Boot Payloads
349415
350-The DMA block supports a special mode of operation that is intended for use in reading Firmware Image Payloads (for Streaming Boot) from the Recovery Interface, present in the Caliptra Subsystem. This operation mode relies on three key control signals: the payload\_available signal input from the recovery interface, the read\_fixed control bit, and the block\_size register (from the DMA control CSR block).
416+The DMA block supports a special mode of operation that is intended for use in reading Firmware Image Payloads (for Streaming Boot) from the Recovery Interface, present in the Caliptra Subsystem. This operation mode relies on three key control signals: the payload\_available signal input from the recovery interface, the read\_fixed control bit, and the block\_size register (from the DMA control CSR block).
351417
352418 This special mode of operation is only used for AXI Reads. To trigger the DMA to operate in this mode, Caliptra Firmware must program the block\_size register to a non-zero value that is a power-of-two. Caliptra Firmware must also program the read\_fixed control bit. Once the “go” bit is set, causing the DMA to begin operation, the DMA control logic will wait for the payload\_available input to trigger. When this occurs, the DMA controller issues a read that has a size equal to (or smaller) than the configured block\_size (the read may be smaller if required by AXI rules). This process repeats until the amount of data indicated in the byte\_size register has been transferred.
353419
354420 When programming an AXI to AXI transfer for a Streaming Boot Payload (e.g., to transfer an SoC Firmware manifest into an AXI-attached SRAM), firmware must also follow these rules:
355-* Programmed value of block\_size must not exceed the largest legal AXI transaction size for a FIXED burst type. The DMA assist has a native data width of 4-bytes, so transaction size is restricted to 64-bytes due to the AXI specification limit of AxLEN == 15 for FIXED transactions.
356-* Destination address must be aligned to the programmed value of block\_size. For example, if block\_size is set to 64-bytes, destination address must be an integer multiple of 0x40.
421+- Programmed value of block\_size must not exceed the largest legal AXI transaction size for a FIXED burst type. The DMA assist has a native data width of 4-bytes, so transaction size is restricted to 64-bytes due to the AXI specification limit of AxLEN == 15 for FIXED transactions.
422+- Destination address must be aligned to the programmed value of block\_size. For example, if block\_size is set to 64-bytes, destination address must be an integer multiple of 0x40.
357423
358424 In all cases other than reading Recovery Interface Payloads, the block\_size register must be programmed to 0\.
359425
426+## AES Mode
427+
428+The DMA block can directly stream images from AXI to AES for decrypt/encrypt, and then stream the processed image over AXI to some SOC storage. This can be done by configuring the AXI DMA as:
429+
430+- AES Mode == 1
431+- (optional) aes_gcm_mode in DMA == 1
432+- Read Route == AXI
433+- Write Route == AXI
434+- Block Size == 0 (OCP Stream Boot Disabled)
435+- Read/Write Fixed == 0
436+- Source Address == Start of image
437+- Destination Address == Start address where processed image should be stored
438+- Configure Byte Count - must be DWORD aligned
439+
440+Other Read/Write Routes and Block sizes are not supported.
441+
442+The AXI DMA AES Mode ONLY streams the image into and out of AES. It is Firmware's responsibility to:
443+
444+1. Fully configure AES before streaming the image via AXI DMA
445+2. Push the IV, AAD header, and any other data into AES before streaming the image via AXI DMA
446+3. Retrieve any tags from AES after the image has been processed.
447+
448+If the input image size is not a multiple of 4 DWORDS, the AES FSM will properly pad the AES input data with 0s. When streaming the image out it reads all 4 DWORDS from the AES, but only writes up to the last DWORD of the image to the destination. If ``aes_gcm_mode`` register is set, at the start of the transfer it updates the GCM shadow byte count and phase registers in AES to the appropriate byte count and GCM_TEXT phase. Before the last block transfer to the AES it will again update the GCM shadow register to the appropriate values.
449+
450+Input images can be in **little endian** or **big endian**. It is FW's responsibility to configure the AES wrapper's ENDIAN_SWAP register.
451+
452+If AXI DMA encounters any errors (AXI or other errors) it will finish the transfer and report an error. It is the Firmware's responsibility to clear the error in the AXI DMA and flush the AES if required.
453+
454+When AXI DMA is using AES Caliptra shall not try to access AES via AHB until AXI DMA has completed.
455+
456+AES is not directly exposed on the AXI bus for external entities, it is protected behind the AXI DMA and can only be accessed via Caliptra uC AHB or the Caliptra DMA.
457+
458+*AES Mode: Read Route \== AXI, Write Route \== AXI, AES Mode \== 1*
459+
460+![](../images/caliptra-ss/docs/images/Caliptra-AXI-DMA-AES.png)
461+
360462 ## Programming Flowchart {#programming-flowchart}
361463
362464 General Rules:
363465
364-1. If either Read or Write route is configured to AXI RD \-\> AXI WR, both routes must be configured as AXI RD \-\> AXI WR.
365-2. Read Route and Write Route must not both be disabled.
366-3. If Read Route is enabled to any configuration other than AXI RD-\> AXI WR, Write route must be disabled.
367-4. If Read Route is disabled, Write route must be enabled to a configuration that is not AXI RD \-\> AXI WR.
368-5. If Read Route is disabled, Read Fixed field is ignored.
369-6. If Write Route is disabled, Write Fixed field is ignored.
466+1. If either Read or Write route is configured to AXI RD \-\> AXI WR, both routes must be configured as AXI RD \-\> AXI WR.
467+2. Read Route and Write Route must not both be disabled.
468+3. If Read Route is enabled to any configuration other than AXI RD-\> AXI WR, Write route must be disabled.
469+4. If Read Route is disabled, Write route must be enabled to a configuration that is not AXI RD \-\> AXI WR.
470+5. If Read Route is disabled, Read Fixed field is ignored.
471+6. If Write Route is disabled, Write Fixed field is ignored.
370472 7. Addresses and Byte Counts must be aligned to AXI data width (1 DWORD).
371-
372473 8. Block Size is used only for reads from the Subsystem Recovery Interface. When block size has a non-zero value, the DMA will only issue AXI read requests when the payload available input signal is set to 1, and will limit the size of read requests to the value of block size. For all other transactions (such as AXI writes, or any single-dword access to a subsystem register via the DMA), block size shall be set to a value of 0 for every transaction.
474+9. AES mode is only valid with Read/Write routes AXI RD -> AXI WR, Read/Write Fixed = 0, and Block Size 0.
373475
374476 Steps:
375477
376-1. Write Byte Count
377-2. Write Block Size
378-3. Write Source Addr (value is ignored if data is from AHB)
379-4. Write Dest Addr (value is ignored if data is to AHB).
380- 1. To perform an accelerated SHA operation on incoming read data, firmware sets the Read/Write route to AXI RD-\> AXI WR, and the destination address to the SoC address for the SHA Acceleration data in aperture.
381-5. Set Interrupt Enables (optional)
382-6. If Mailbox R/W: Acquire Mailbox Lock
383-7. If SHA Acc Op:
384- 1. First acquire Sha Accel Lock via AXI by using this flow (with the AHB-\> AXI WR route) to initiate AXI manager action
385- 2. Initiate Sha Accel streaming operation via AXI by using this flow (with the AHB-\> AXI WR route) to initiate AXI manager action
386- 3. Run this operation with the AXI RD \-\> AXI WR route to move data from SoC location into Sha Accelerator
387-8. Set Control Register
388- 1. Set Read/Write Routes
389- 2. Set Read/Write Fixed=0/1
390- 3. GO
391- 4. (All 3 may be single write or separate, GO must be last bit to set)
392-9. If AHB data: Wait for RD FIFO not empty or WR FIFO not full
393- 1. Push/Pop data (using Rd Data/Wr Data register offsets) until all requested bytes transferred
394- 2. If AHB Error – check status0 for Error, then check for “Command Error”
395-10. Wait for TXN Done Interrupt (or Poll Status0)
396-11. Read Status0, confirm Busy=0, Error=0
478+1. Write Byte Count
479+2. Write Block Size
480+3. Write Source Addr (value is ignored if data is from AHB)
481+4. Write Dest Addr (value is ignored if data is to AHB).
482+ 1. To perform an accelerated SHA operation on incoming read data, firmware sets the Read/Write route to AXI RD-\> AXI WR, and the destination address to the SoC address for the SHA Acceleration data in aperture.
483+5. Set Interrupt Enables (optional)
484+6. If Mailbox R/W: Acquire Mailbox Lock
485+7. If SHA Acc Op:
486+ 1. First acquire Sha Accel Lock via AXI by using this flow (with the AHB-\> AXI WR route) to initiate AXI manager action
487+ 2. Initiate Sha Accel streaming operation via AXI by using this flow (with the AHB-\> AXI WR route) to initiate AXI manager action
488+ 3. Run this operation with the AXI RD \-\> AXI WR route to move data from SoC location into Sha Accelerator
489+8. If AES Mode:
490+ 1. Fully configure AES with IV/KEY see [AES spec for more details](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraHardwareSpecification.md#aes)
491+ 2. Stream in any header info to AES like AAD
492+ 3. Set read/write routes to AXI
493+ 4. Set AES_MODE in DMA
494+ 5. Set aes_gcm_mode in DMA if this is the AES mode
495+9. Set Control Register
496+ 1. Set Read/Write Routes
497+ 2. Set Read/Write Fixed=0/1
498+ 3. GO
499+ 4. (All 3 may be single write or separate, GO must be last bit to set)
500+10. If AHB data: Wait for RD FIFO not empty or WR FIFO not full
501+ 1. Push/Pop data (using Rd Data/Wr Data register offsets) until all requested bytes transferred
502+ 2. If AHB Error – check status0 for Error, then check for “Command Error”
503+11. Wait for TXN Done Interrupt (or Poll Status0)
504+12. Read Status0, confirm Busy=0, Error=0
397505
398506 ## Descriptor
399507
400-https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.axi_dma_reg
508+<https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.axi_dma_reg>
401509
402510 # Caliptra Subsystem Fuse Controller
403511
404-FUSE controller is an RTL module that is responsible for programming and reading the FUSEs. This module has an AXI interface that is connected to Caliptra Subsystem’s AXI interconnect. This module provides the device with one-time programming functionality, resulting in non-volatile programming that cannot be reversed. This functionality is delivered via an open-source FUSE Controller and a proprietary FUSE/OTP Macro. This RTL module manages the following FUSE partition mapping, which can be found in the [Fuse Controller Memory Map](https://github.com/chipsalliance/caliptra-ss/blob/9022fc2a57bb9af2f3ebc2376b98a807812e2e0f/src/fuse_ctrl/doc/otp_ctrl_mmap.md).
405-
512+FUSE controller is an RTL module that is responsible for programming and reading the FUSEs. This module has an AXI interface that is connected to Caliptra Subsystem’s AXI interconnect. This module provides the device with one-time programming functionality, resulting in non-volatile programming that cannot be reversed. This functionality is delivered via an open-source FUSE Controller and a proprietary FUSE/OTP Macro. This RTL module manages the following FUSE partition mapping, which can be found in the [Fuse Controller Memory Map](https://github.com/chipsalliance/caliptra-ss/blob/2041523f977f5b24453464eda02008b1bd0f4f66/src/fuse_ctrl/doc/otp_ctrl_mmap.md).
406513
407514 ## Partition Details
408515
409-The Fuse Controller is configured a total of **16 partitions** (See [Fuse Controller's Fuse Partition Map](https://github.com/chipsalliance/caliptra-ss/blob/9022fc2a57bb9af2f3ebc2376b98a807812e2e0f/src/fuse_ctrl/doc/otp_ctrl_mmap.md)), while it can support different number of partitions based on SoC product requirements. Secret FUSE partitions are prefixed with the word "Secret" and are associated with specific Life Cycle (LC) states, such as "MANUF" or "PROD." This naming convention indicates the LC state required to provision each partition.
410-
411-### Key Characteristics of Secret Partitions:
412-1. **Programming Access:**
516+The Fuse Controller is configured a total of **16 partitions** (See [Fuse Controller's Fuse Partition Map](https://github.com/chipsalliance/caliptra-ss/blob/2041523f977f5b24453464eda02008b1bd0f4f66/src/fuse_ctrl/doc/otp_ctrl_mmap.md)), while it can support different number of partitions based on SoC product requirements. Secret FUSE partitions are prefixed with the word "Secret" and are associated with specific Life Cycle (LC) states, such as "MANUF" or "PROD." This naming convention indicates the LC state required to provision each partition.
517+
518+### Key Characteristics of Secret Partitions
519+
520+1. **Programming Access:**
413521 - `UDS_SEED` and `FIELD_ENTROPY` partitions can only be programmed by the Caliptra Core.
414- - Secret partitions are buffered, meaning they are stored in registers and are erased (temporarily zeroized) if Caliptra-SS enters debug mode.
415-2. **Locking Mechanism:**
416- - Write access to a partition can be permanently locked when no further updates are required.
522+ - Secret partitions are buffered, meaning they are stored in registers and are erased (temporarily zeroized) if Caliptra-SS enters debug mode.
523+2. **Locking Mechanism:**
524+ - Write access to a partition can be permanently locked when no further updates are required.
417525 - To lock a partition, an integrity constant is calculated and programmed alongside the data for that partition.
418526
419527 ## Partition-Specific Behaviors
420528
421529 ### Life Cycle Partition
422-- The life cycle partition remains active across all stages and cannot be locked.
423-- This ensures that the device can transition back to the **RMA** state in case of unexpected failures during production.
530+
531+- The life cycle partition remains active across all stages and cannot be locked.
532+- This ensures that the device can transition back to the **RMA** state in case of unexpected failures during production.
424533
425534 ### Vendor Test Partition
426-- The vendor test partition is used for FUSE programming smoke checks during manufacturing.
535+
536+- The vendor test partition is used for FUSE programming smoke checks during manufacturing.
427537 - Unlike other partitions, ECC uncorrectable errors in this partition do not trigger fatal errors or alerts due to the nature of FUSE smoke checks, which may leave certain FUSE words in inconsistent states.
428538
429-
430539 ## Locking the Validated Public Key Partition
540+
431541 <a name="locking-the-validated-public-key-partition"></a>
432542
433543 During firmware authentication, the ROM validates the vendor public keys provided in the firmware payload. These keys, which support ECC, MLDSA, and LMS algorithms, are individually hashed and compared against stored fuse values (e.g., `CPTRA_CORE_VENDOR_PK_HASH_n`). Once a valid key is identified, the ROM locks that specific public key hash and all higher-order public key hash entries until the next cold reset. This ensures that the validated key’s fuse entry remains immutable. Importantly, the locking mechanism is applied only to the public key hashes. The associated revocation bits, which allow for runtime key revocation, remain unlocked. To support this, the fuse controller (FC) implements two distinct partitions:
434544
435-1. **PK Hash Partition**
436- - **Purpose:**
545+1. **PK Hash Partition**
546+ - **Purpose:**
437547 - Contains the `CPTRA_CORE_VENDOR_PK_HASH[i]` registers for *i* ranging from 1 to N.
438548 - Once a key is validated, the corresponding hash and all higher-order hashes are locked by MCU ROM, making them immutable until a cold reset.
439- - **Layout & Details:**
440- - **Partition Items:** `CPTRA_CORE_VENDOR_PK_HASH[i]` where *i* ranges from 1 to N.
441- - **Default N:** 1
442- - **Maximum N:** 16
443- - **Size:** N Ă— 384 bits (each hash is 384-bit)
444- - **Programming:**
445- - The first key (i=1) is programmed during the manufacturing phase.
549+ - **Layout & Details:**
550+ - **Partition Items:** `CPTRA_CORE_VENDOR_PK_HASH[i]` where *i* ranges from 1 to N.
551+ - **Default N:** 1
552+ - **Maximum N:** 16
553+ - **Size:** N Ă— 384 bits (each hash is 384-bit)
554+ - **Programming:**
555+ - The first key (i=1) is programmed during the manufacturing phase.
446556 - The remaining keys (if any, i.e., N–1) can be programmed during manufacturing or in the field (production).
447557 - **Partition Item:**
448558 - `CPTRA_CORE_VENDOR_PK_HASH_VALID` is used to indicate which of the N keys is valid. Therefore, the length is N to support N-bit hot-encoding.
449-
450-2. **PK Hash Revocation Partition**
451- - **Purpose:**
559+
560+2. **PK Hash Revocation Partition**
561+ - **Purpose:**
452562 This partition stores runtime-updateable revocation bits and PQC type information.
453- - **Layout & Details:**
454- - For each vendor public key (`VENDOR_PK_HASH[i]`), the partition contains:
455- - **ECC Revocation Bits:** 4 bits (e.g., `CPTRA_CORE_ECC_REVOCATION[i]`)
456- - **LMS Revocation Bits:** 32 bits (e.g., `CPTRA_CORE_LMS_REVOCATION[i]`)
457- - **MLDSA Revocation Bits:** 4 bits (e.g., `CPTRA_CORE_MLDSA_REVOCATION[i]`)
563+ - **Layout & Details:**
564+ - For each vendor public key (`VENDOR_PK_HASH[i]`), the partition contains:
565+ - **ECC Revocation Bits:** 4 bits (e.g., `CPTRA_CORE_ECC_REVOCATION[i]`)
566+ - **LMS Revocation Bits:** 32 bits (e.g., `CPTRA_CORE_LMS_REVOCATION[i]`)
567+ - **MLDSA Revocation Bits:** 4 bits (e.g., `CPTRA_CORE_MLDSA_REVOCATION[i]`)
458568 - **PQC Key Type Bits:** 1-bit one-hot encoded selection (e.g., `CPTRA_CORE_PQC_KEY_TYPE[i]`)
459- - **Attributes:**
569+ - **Attributes:**
460570 - This partition is kept separate from the PK hash partition to allow for runtime updates even after the validated public key is locked.
461-3. **Volatile Locking Mechanism**
571+3. **Volatile Locking Mechanism**
572+
462573 - To ensure that the validated public key remains immutable once selected, the FC uses a volatile lock mechanism implemented via the new register `otp_ctrl.VENDOR_PK_HASH_LOCK`.
463574 - Once the ROM determines the valid public key (e.g., the 3rd key is selected), it locks the corresponding fuse entries in the PK hash partition.
464575 - The lock is applied by writing a specific value to `otp_ctrl.VENDOR_PK_HASH_LOCK`.
576+- If the OCP L.O.C.K. is enabled, the same lock mechanism is also applied on `CPTRA_SS_LOCK_HEK_PROD_X` fuse patitions.
465577 - **Example:**
578+
466579 ```c
467580 // Lock the 3rd vendor public key hash and all higher order key hashes
468581 write_register(otp_ctrl.VENDOR_PK_HASH_LOCK, 0xFFF2);
469582 // This operation disables any further write updates to the validated public key fuse region.
470583 ```
584+
471585 - The ROM polls the [`STATUS`](../src/fuse_ctrl/doc/registers.md#status) register until the Direct Access Interface (DAI) returns to idle, confirming the completion of the lock operation. If any errors occur, appropriate error recovery measures are initiated.
472586 - Once locked, the PK hash partition cannot be modified, ensuring that the validated public key remains unchanged, thereby preserving the secure boot chain.
473587 - If there needs to be update or programming sequence in PK_HASH set, it needs to be in ROM execution time based on a valid request. Therefore, requires cold-reset.
@@ -479,57 +593,25 @@
479593
480594 Once partitions are locked, the hardware integrity checker performs two primary integrity checks to ensure the consistency of the volatile buffer registers:
481595
482-1. **ECC Protection:**
596+1. **ECC Protection:**
483597 - All buffered partitions include additional ECC protection (8-bit ECC for each 64-bit block), which is monitored concurrently.
484598
485-2. **Digest Verification:**
599+2. **Digest Verification:**
486600 - The digest of each partition is recomputed at semi-random intervals and compared to the digest stored alongside the partition.
487601
488602 ### Purpose
603+
489604 These integrity checks verify whether the contents of the buffer registers remain consistent with the calculated digest. They do not verify the consistency between storage flops and the FUSE.
490605
491-## Zeroization Flow for Secret FUSEs
492-
493-The secret FUSE partitions are **zeroized** when the Caliptra-SS Life Cycle Controller (LCC) enters the **SCRAP** state. However, due to lifecycle constraints, the zeroization process requires a **transient condition** before the system reaches the **SCRAP** state.
494-
495-### Conditions for Zeroization
496-
497-Zeroization occurs under the following conditions:
498-
499-1. **Persistent Condition:**
500- - The **Life Cycle Controller (LCC)** must be in the **SCRAP** state.
501- - This transition to SCRAP occurs only **after a cold reset** followed by **SCRAP** state transition request.
502-
503-2. **Transient Condition (Before Cold Reset):**
504- - The **`cptra_ss_FIPS_ZEROIZATION_PPD_i`** GPIO pin must be **asserted high**.
505- - MCU ROM support is needed.
506-
507-### Zeroization Process
508-
509-1. A new input port, `cptra_ss_FIPS_ZEROIZATION_PPD_i`, is introduced in the Caliptra Subsystem. SoC integrator needs to connect this signal to MCI generic input wires (see [MCI Generic Input Allocation](./CaliptraSSIntegrationSpecification.md#mci-integration-requirements)).
510-2. When this signal is asserted, it triggers preemptive zeroization of secret FUSEs before the SCRAP state transition.
511-3. The **MCU ROM** samples `cptra_ss_FIPS_ZEROIZATION_PPD_i` by reading the corresponding register storing its value.
512-4. If `cptra_ss_FIPS_ZEROIZATION_PPD_i == HIGH`, the MCU ROM executes a **Life Cycle Controller (LCC) transition request** to switch to the **SCRAP** state.
513-
514-- **Note:** The LCC state transition to SCRAP is completed **only after a cold reset**.
515-
516-
517-### Cold Reset and Final Zeroization
518-
519-- The system remains in a **transient zeroization state** managed by:
520- - `cptra_ss_FIPS_ZEROIZATION_PPD_i`
521- - `ss_soc_MCU_ROM_zeroization_mask_reg`
522-- After the **cold reset**, the **LCC enters SCRAP state**.
523-- All secret FUSEs are permanently zeroized as a direct result of the **SCRAP state transition**.
524-
525606 ---
526607
527608 ## Notes
528-- **Zeroization of Secret Partitions:**
609+
610+- **Zeroization of Secret Partitions:**
529611 Secret partitions are temporarily zeroized when Caliptra-SS enters debug mode to ensure security.
530-- **Locking Requirement:**
612+- **Locking Requirement:**
531613 After the device finishes provisioning and transitions into production, partitions that no longer require updates should be locked to prevent unauthorized modifications.
532-- **Further Information:**
614+- **Further Information:**
533615 For more information about the conditional states, please refer to [OpenTitan open-source silicon Root of Trust (RoT) project](https://opentitan.org/book/hw/ip/lc_ctrl/doc/theory_of_operation.html).
534616
535617 ## General Guidance
@@ -545,11 +627,12 @@
545627 OTP words cannot be programmed twice, and doing so may damage the memory array.
546628 Hence the OTP controller performs a blank check and returns an error if a write operation is issued to an already programmed location.
547629
548-
549630 # Caliptra Subsystem Life Cycle Controller
631+
550632 It is an overview of the architecture of the Life-Cycle Controller (LCC) Module for its use in the Caliptra Subsystem. The LCC is responsible for managing the life-cycle states of the system, ensuring secure transitions between states, and enforcing security policies.
551633
552634 ## Caliptra Subsystem, SOC Debug Architecture Interaction
635+
553636 Figure below shows the Debug Architecture of the Caliptra Subsystem and some important high-level signals routed towards SOC. The table in Key Components and Interfaces section shows all the signals that are available to SOC (outside of Caliptra Subsystem usage).
554637
555638 *Figure: Caliptra Subsystem & SOC Debug Architecture Interaction*
@@ -572,15 +655,14 @@
572655 | TEST_UNLOCKED{N} | FUSE | Transition from RAW state using token stored in FUSE. This state is used for manufacturing and production testing. During this state: CLTAP (chip level TAPs) is enabled; Debug functions are enabled; DFT functions are enabled. It is expected that LCC tokens will be provisioned into FUSE during these states. Once provisioned, these tokens are no longer readable by software. |
573656 | MANUF | FUSE | Transition from TEST_UNLOCKED state using token stored in FUSE. This is a mutually exclusive state to PROD and PROD_END. To enter this state, MANUF_TOKEN is required. This state is used for developing provisioning and mission mode. In this state, UDS and Field Entropy FUSE partitions can be provisioned. During this state: CLTAP (chip level TAPs) is enabled; Debug functions are enabled; DFT functions are disabled |
574657 | PROD | FUSE | Transition from MANUF state using token stored in FUSE. PROD is a mutually exclusive state to MANUF and PROD_END. To enter this state, PROD_TOKEN is required. This state is used both for provisioning and mission mode. During this state: CLTAP is disabled; Debug functions are disabled; DFT functions are disabled; Caliptra Subsytem can grant SoC debug unlock flow if the conditions provided in “SoC Debug Flow and Architecture for Production Mode” section are satisfied. SoC debug unlock overwrites the signals and gives the following cases: CLTAP is enabled; Debug functions are enabled based on the defined debug policy; DFT is enabled but this DFT enable is called SOC_DFT_EN, which has less capabilities than DFT_EN granted in TEST_UNLOCKED. |
575-| PROD_END | FUSE | This state is identical in functionality to PROD, except the device is never allowed to transition to RMA state. To enter this state, a PROD_END token is required. It also means that Caliptra-SS cannot enter debug mode anymore. Only transition to SCRAP mode is allowed. |
658+| PROD_END | FUSE | This state is identical in functionality to PROD, except the device is never allowed to transition to RMA state. To enter this state, a PROD_END token is required. Only transition to SCRAP mode is allowed. |
576659 | RMA | FUSE | Transition from TEST_UNLOCKED / PROD / MANUF using token stored in FUSE. It is not possible to reach this state from PROD_END. If the RMA transition is requested, the request must follow the asserted RMA PPD pin. Without this pin, RMA request is discarded. See `cptra_ss_lc_Allow_RMA_or_SCRAP_on_PPD_i` in [Caliptra Subsystem Integration Specification Document](CaliptraSSIntegrationSpecification.md). When transitioning from PROD or MANUF, an RMA_UNLOCK token is required. When transitioning from TEST_UNLOCKED, no RMA_UNLOCK token is required. During this state: CLTAP is enabled; Debug functions are enabled; DFT functions are enabled |
577660 | SCRAP | FUSE | Transition from any state. If the SCRAP transition is requested, the request must follow the asserted SCRAP PPD pin. Without this pin, SCRAP request is discarded. See `cptra_ss_lc_Allow_RMA_or_SCRAP_on_PPD_i` in [Caliptra Subsystem Integration Specification Document](CaliptraSSIntegrationSpecification.md). During SCRAP state the device is completely dead. All functions, including CPU execution are disabled. The only exception is the TAP of the life cycle controller which is always accessible so that the device state can be read out. No owner consent is required to transition to SCRAP. Note also, SCRAP is meant as an EOL manufacturing state. Transition to this state is always purposeful and persistent, it is NOT part of the device’s native security countermeasure to transition to this state. |
578661 | INVALID | FUSE | Invalid is any combination of FUSE values that do not fall in the categories above. It is the “default” state of life cycle when no other conditions match. Functionally, INVALID is identical to SCRAP in that no functions are allowed and no transitions are allowed. A user is not able to explicitly transition into INVALID (unlike SCRAP), instead, INVALID is meant to cover in-field corruptions, failures or active attacks. |
579662
580663
581664 **Note**
582-* The LCC performs state transitions in a forward-only manner. It begins in the RAW state and follows the sequence: TEST_UNLOCKED and TEST_LOCKED, then MANUF, then PROD, and finally either PROD_END or RMA. After transitioning to TEST_UNLOCKED, the LCC can branch to any of the following states: MANUF, PROD, PROD_END, or RMA. However, once the LCC transitions to PROD, PROD_END, or RMA, it cannot return to the MANUF state. Additionally, note that the LCC cannot branch to RMA from PROD_END.
583-
665+- The LCC performs state transitions in a forward-only manner. It begins in the RAW state and follows the sequence: TEST_UNLOCKED and TEST_LOCKED, then MANUF, then PROD, and finally either PROD_END or RMA. After transitioning to TEST_UNLOCKED, the LCC can branch to any of the following states: MANUF, PROD, PROD_END, or RMA. However, once the LCC transitions to PROD, PROD_END, or RMA, it cannot return to the MANUF state. Additionally, note that the LCC cannot branch to RMA from PROD_END.
584666
585667 ## DFT & DFD Life-cycle States
586668
@@ -595,32 +677,33 @@
595677
596678 In the manufacturing phase, the Caliptra Subsystem asserts SOC_HW_DEBUG_EN high, with the signal being controlled by the LCC. In PROD mode, this signal is low. However, the SoC integrator has the flexibility to enable CLTAP during production debug mode by incorporating additional logic, such as an OR gate, to override the SOC_HW_DEBUG_EN signal, like DFT_EN. This architecture provides a mask register that allows SoC to program/configure this overriding mechanism at integration time or using MCU ROM. This allows the SoC to maintain control over hardware debug access while preserving the intended security protections in production.
597679
598-
599680 *Table: LCC State and State Decoder output ports*
681+
600682 ## LCC State and State Decoder Output Ports
683+
601684 | **LCC State\Decoder Output** | **DFT_EN** | **SOC_DFT_EN** | **SOC_HW_DEBUG_EN** |
602685 | :--------- | :--------- | :--------- | :--------- |
603686 | RAW | Low | Low | Low |
604687 | TEST_LOCKED | Low | Low | Low |
605688 | TEST_UNLOCKED | High | High | High |
606-| MANUF* | Low | Low | High |
689+| MANUF* | Low | TOKEN - CONDITIONED** | High |
607690 | PROD* | Low | TOKEN - CONDITIONED** | TOKEN - CONDITIONED** |
608691 | PROD_END | Low | Low | Low |
692+| PROD_END* | Low | TOKEN - CONDITIONED** | TOKEN - CONDITIONED** |
609693 | RMA | High*** | High | High |
610694 | SCRAP | Low | Low | Low |
611695 | INVALID | Low | Low | Low |
612696 | POST_TRANSITION | Low | Low | Low |
613697
614698
615-
616-
617-*: Caliptra can enter debug mode and update these signals even though LCC is in MANUF or PROD states. This case is explained in “How does Caliptra Subsystem enable manufacturing debug mode?” and “SoC Debug Flow and Architecture for Production Mode”.
699+*: Caliptra can enter debug mode and update these signals even though LCC is in MANUF or PROD, PROD_END states. This case is explained in “How does Caliptra Subsystem enable manufacturing debug mode?” and “SoC Debug Flow and Architecture for Production Mode”.
618700
619701 **: SOC_DFT_EN and SOC_HW_DEBUG_EN can be high if Caliptra SS grants debug mode (either manufacturing or production). This case is explained in “How does Caliptra Subsystem enable manufacturing debug mode?” and “SoC Debug Flow and Architecture for Production Mode”. SOC_HW_DEBUG_EN is set high to open CLTAP and SOC_DFT_EN enables DFT by SoC design support. However, this condition also needs to go through the flow described in “SoC Debug Flow and Architecture for Production Mode”. Caliptra Subsystem state should be set to either the manufacturing mode debug unlock or Level 0 of the production debug unlock.
620702
621-***: RMA state enables DFT_EN but Caliptra Core enters the debug mode when LCC enters RMA state. Thus, Caliptra Core clears UDS and Field Entropy secrets.
703+***: RMA state enables DFT_EN but Caliptra Core enters the debug mode when LCC enters RMA state. Thus, Caliptra Core clears UDS and Field Entropy secrets.
622704
623705 ## TAP Pin Muxing
706+
624707 The LCC includes a TAP interface, which operates on its own dedicated clock and is used for injecting tokens into the LCC. Notably, the LCC TAP interface remains accessible in all life cycle states, providing a consistent entry point for test and debug operations. This TAP interface can be driven by either the TAP GPIO pins or internal chip-level wires, depending on the system's current configuration.
625708
626709 *Figure: Caliptra Subsystem Life Cycle Controller Summary*
@@ -629,14 +712,13 @@
629712
630713 SOC logic incorporates the TAP pin muxing to provide the integration support and manage the connection between the TAP GPIO pins and the Chip-Level TAP (CLTAP). As illustrated in figure above, this muxing logic determines the source that drives the LCC TAP interface. The selection between these two sources is controlled by the SOC_HW_DEBUG_EN signal. When SOC_HW_DEBUG_EN is set to high, control is handed over to the CLTAP, allowing for chip-level debug access through the TAP GPIO pins. Conversely, when SOC_HW_DEBUG_EN is low, the TAP GPIO pins take control, enabling external access to the LCC TAP interface.
631714
632-**[LCC State and State Decoder Output Ports Table](#lcc-state-and-state-decoder-output-ports)** outlines the specific LCC states that enable the SOC_HW_DEBUG_EN signal. These states include TEST_UNLOCK, MANUF, PROD (debug unlocked version only), and RMA. In these states, the LCC allows internal chip-level debug access via CLTAP, thereby facilitating advanced debugging capabilities. This muxing approach ensures that the TAP interface is appropriately secured, and that access is granted only under specific conditions, aligning with the overall security and functional requirements of the Caliptra Subsystem.
715+**[LCC State and State Decoder Output Ports Table](#lcc-state-and-state-decoder-output-ports)** outlines the specific LCC states that enable the SOC_HW_DEBUG_EN signal. These states include TEST_UNLOCK, MANUF, PROD (debug unlocked version only), and RMA. In these states, the LCC allows internal chip-level debug access via CLTAP, thereby facilitating advanced debugging capabilities. This muxing approach ensures that the TAP interface is appropriately secured, and that access is granted only under specific conditions, aligning with the overall security and functional requirements of the Caliptra Subsystem.
633716 **Note:** It is important to note that CLTAP provides access to the TAP interfaces of the LCC, MCU, or Caliptra Core. This functionality is managed by SoC logic, not by Caliptra-SS. Consequently, the SoC integration effort should ideally include an additional mux after CTAP to route the connection to one of the following: the LCC TAP, MCU TAP, or Caliptra Core TAP.
634717
635718 TAP pin muxing also enables routing to Caliptra TAP. This selection happens when DEBUG_INTENT_STRAP is high. This selection is done through the GPIO and indicates that Caliptra will enter debug mode if the secret tokens are provided. Caliptra Subsystem has two debug modes: manufacturing debug and production debug. Entering these debug flows are explained in the following sections:
636-**[How does Caliptra Subsystem enable manufacturing debug mode?](#how-does-caliptra-subsystem-enable-manufacturing-debug-mode),
719+**[How does Caliptra Subsystem enable manufacturing debug mode?](#how-does-caliptra-subsystem-enable-manufacturing-debug-mode),
637720 [SoC Debug Flow and Architecture for Production Mode](#soc-debug-flow-and-architecture-for-production-mode) and
638721 [Masking Logic for Debugging Features in Production Debug Mode](#masking-logic-for-debugging-features-in-production-debug-mode)**
639-
640722
641723 **Note:** The Caliptra TAP can run exact flow with AXI, targeting the mailbox and SOC provides that interface to platform.
642724
@@ -648,7 +730,7 @@
648730 ![](../images/caliptra-ss/docs/images/Manuf-Debug-LifeCycle.png)
649731 **Note:** The flow diagram on the right side shows the LCC states (grey boxes) and their transitions, while the flow diagram on the left illustrates Caliptra SS’s enhancements to the LCC for the manufacturing phase. Specifically, the flow on the left depicts the routine for entering manufacturing debug mode.
650732
651-#### Flow Explanation:
733+#### Flow Explanation
652734
653735 1. **(Platform) Assert BootFSMBrk :** Temporarily halting the Caliptra HW bootfsm boot process to allow for secure operations like token injection and verification.
654736 2. **(Platform) Assert DEBUG_INTENT_STRAP:** If Caliptra core HW samples this pin as high and sees that LCC is in MANUF mode, it prepares itself for entering debug mode. Once the DEBUG_INTENT_STRAP is detected, Caliptra HW immediately wipes out its secret assets, including the Unique Device Secret (UDS) and Field entropy, ensuring that no sensitive data remains accessible. If this Pin is not high, Caliptra continues always in non-debug mode without taking any further action listed with the following states.
@@ -666,20 +748,24 @@
666748
667749 The Caliptra Subsystem includes SoC debugger logic that supports Caliptra’s production debug mode. This debugger logic extends the capabilities of the Lifecycle Controller (LCC) by providing a production debug mode architecture that the LCC does not inherently support, except in the RMA state. This architecture manages the initiation and handling of the production debug mode separately from the LCC's lifecycle states.
668750
669-The process of enabling production debug mode begins when the DEBUG_INTENT_STRAP pin is asserted high via the SoC’s GPIO. This pin signals Caliptra to start the debug mode when the LCC is in the PROD state. Before the debug unlock flow, the MCU reads all hashed public keys from the fuse macros and writes them to the `SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK` registers. Additionally, the MCU sets the number of public keys used for production debug unlock by writing to the `SS_NUM_OF_PROD_DEBUG_UNLOCK_AUTH_PK_HASHES` register. The value `DEBUG_AUTH_PK_HASH_REG_BANK_OFFSET` represents an address offset, while `NUM_OF_DEBUG_AUTH_PK_HASHES` defines how many public keys are available for reading. These two values establish the debug policy depth for different debugging levels.
751+The process of enabling production debug mode begins when the DEBUG_INTENT_STRAP pin is asserted high via the SoC’s GPIO. This pin signals Caliptra to start the debug mode when the LCC is in the PROD and PROD_END states. Before the debug unlock flow, the MCU reads all hashed public keys from the fuse macros and writes them to the `SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK` registers. Additionally, the MCU sets the number of public keys used for production debug unlock by writing to the `SS_NUM_OF_PROD_DEBUG_UNLOCK_AUTH_PK_HASHES` register. The value `DEBUG_AUTH_PK_HASH_REG_BANK_OFFSET` represents an address offset, while `NUM_OF_DEBUG_AUTH_PK_HASHES` defines how many public keys are available for reading. These two values establish the debug policy depth for different debugging levels.
670752
671753 ### Overview of Debug Unlock Initiation
672754
673755 The process begins when the platform sets three conditions:
756+
674757 - The `DEBUG_INTENT` field in the `SS_DEBUG_INTENT` register.
675758 - The `PROD_DEBUG_UNLOCK_REQ` bit in the `SS_DBG_MANUF_SERVICE_REG_REQ` register.
676-- The `BOOTFSM_GO_ADDR` to allow Caliptra Core to continue its execution.
759+- The `CPTRA_BOOT_GO` allows Caliptra Core to continue its execution.
677760 On reset, the Caliptra ROM checks these two signals. If both are asserted, the ROM begins the production debug unlock process.
678761 Upon detecting a valid debug intent:
679762 - Caliptra hardware erases its secret assets, including the Unique Device Secret (UDS) and Field Entropy, before exposing any debug interfaces, ensuring sensitive data is irreversibly destroyed.
680763 - Caliptra ROM sets the `TAP_MAILBOX_AVAILABLE` and `PROD_DBG_UNLOCK_IN_PROGRESS` bits in the `SS_DBG_MANUF_SERVICE_REG_RSP` register.
681764
765+**Note:** Similar to the manufacturing debug flow, BootFSMBrk must be asserted to halt Caliptra ROM execution. Otherwise, the ROM may advance past the debug request before `PROD_DEBUG_UNLOCK_REQ` is populated. BootFSMBrk is a prerequisite for entering the debug flow ONLY if Caliptra core ROM needs to be debugged; for run-time injection of prod debug unlock token, setting BootFSMBrk is not required.
766+
682767 ### Secure Debug Unlock Protocol
768+
683769 - The production debug unlock flow uses a challenge-response authentication model involving public key verification and hybrid cryptography (ECC and MLDSA). The flow includes the following steps:
684770 - AUTH_DEBUG_UNLOCK_REQ Command: Caliptra ROM polls the Mailbox interface, awaiting an `AUTH_DEBUG_UNLOCK_REQ` from the platform.
685771 - The request payload includes:
@@ -701,6 +787,7 @@
701787 | Length | 4 | Should be 21 DWORDs. |
702788 | Unique Device Identifier | 32 | Caliptra device identifier. |
703789 | Challenge | 48 | Randomly generated nonce. |
790+
704791
705792 - The platform signs the challenge data and sends an `AUTH_DEBUG_UNLOCK_TOKEN`:
706793
@@ -716,22 +803,26 @@
716803 | ECC Signature | 96 | Signature of challenge message. |
717804 | MLDSA Signature | 4628 | Signature of challenge message. |
718805
719-- Finally, Caliptra ROM reads the expected SHA2-384 public key hash from the corresponding register by using the following equation:
806+
807+- Finally, Caliptra ROM reads the expected SHA2-384 public key hash from the corresponding register by using the following equation:
720808 - SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK_OFFSET + ((Unlock Level - 1) * 48 bytes)
721809 - If hash of `AUTH_DEBUG_UNLOCK_CHALLENGE`'s MLDSA and ECC public keys match with the read value from `SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK_OFFSET`, ROM uses these MLDSA and ECC public keys to perform the authentication.
722-- Upon successful validation:
810+- Upon successful validation:
723811 - Sets the `PROD_DBG_UNLOCK_SUCCESS` bit.
724812 - Writes the `CALIPTRA_SS_SOC_DEBUG_UNLOCK_LEVEL` register granted debug level with a one-hot encoding result (1 << (Unlock Level - 1)).
725813 - Clears the `TAP_MAILBOX_AVAILABLE` bit.
726814 - Clears the `PROD_DBG_UNLOCK_IN_PROGRESS` bit.
727815 - Exits the debug unlock process.
728816
729-
730817 **Granting Production Debug Mode:**
731-* If authentication succeeds, Caliptra ROM does not immediately grant full production debug mode. Instead, the ROM sets the appropriate **"debug level"** signal, which corresponds to the type of debug access being requested.
732-* Caliptra ROM writes CALIPTRA_SS_SOC_DEBUG_UNLOCK_LEVEL register, which will be wired to the specific debug enable signal. This signal is part of an N-wide signal that is mapped to the payload encoding received during the debug request. N is defined by NUM_OF_ DEBUG_AUTH_PK_HASHES. The default version of N is 8. The payload encoding can either be one-hot encoded or a general encoded format, and this signal is passed to the SoC to allow it to make the final decision about the level of debug access that should be granted. In Caliptra’s subsystem-specific implementation, the logic is configured to handle one-hot encoding for these 8 bits. The level 0 bit is routed to both Caliptra and the MCU TAP interface, allowing them to unlock based on this level of debug access. This granular approach ensures that the system can selectively unlock different levels of debugging capability, depending on the payload and the authorization level provided by the debugger.
818+- If authentication succeeds, Caliptra ROM does not immediately grant full production debug mode. Instead, the ROM sets the appropriate **"debug level"** signal, which corresponds to the type of debug access being requested.
819+- Caliptra ROM writes CALIPTRA_SS_SOC_DEBUG_UNLOCK_LEVEL register, which will be wired to the specific debug enable signal. This signal is part of an N-wide signal that is mapped to the payload encoding received during the debug request. N is defined by NUM_OF_DEBUG_AUTH_PK_HASHES. The default version of N is 8. The payload encoding can either be one-hot encoded or a general encoded format, and this signal is passed to the SoC to allow it to make the final decision about the level of debug access that should be granted. In Caliptra’s subsystem-specific implementation, the logic is configured to handle one-hot encoding for these 8 bits. The level 0 bit is routed to both Caliptra and the MCU TAP interface, allowing them to unlock based on this level of debug access. This granular approach ensures that the system can selectively unlock different levels of debugging capability, depending on the payload and the authorization level provided by the debugger.
820+
821+**Granting Production Debug Mode with Caliptra Runtime FW:**
822+Although the flow above describes ROM-based authentication, the same challenge–response mechanism may be executed by Caliptra Runtime Firmware. In this case, RT FW performs the challenge-response authentication steps via mailbox commands, which will be used to update the debug unlock level. **The DEBUG_INTENT_STRAP must still be asserted high before Caliptra subsystem is out of reset.** This ensures that even RT-based debug enablement remains gated by hardware intent and cannot be triggered purely through software.
733823
734824 ## Masking Logic for Debugging Features in Production Debug Mode (MCI)
825+
735826 In the production debug mode, the SoC can enable certain debugging features—such as DFT_EN and SOC_HW_DEBUG_EN—using a masking mechanism implemented within the Manufacturer Control Interface (MCI). This masking infrastructure allows the SoC to selectively control debug features that are normally gated by Caliptra’s internal signals. The masking logic functions as a set of registers, implemented in the MCI, that can be written by the SoC to override or enable specific debugging functionalities in production debug mode.
736827 The masking registers in the MCI act as an OR gate with the existing debug signals. For instance, if DFT_EN is controlled by Caliptra, the SoC can assert the corresponding mask register to enable Design for Test (DFT) capabilities in the SoC, even if Caliptra has not explicitly enabled it. Similarly, the SOC_HW_DEBUG_EN signal can be masked through the MCI registers, giving the SoC the flexibility to unlock TAP interfaces and provide the required debugging in production.
737828
@@ -740,6 +831,7 @@
740831
741832 This mechanism is only authorized when both the LCC and Caliptra core are in the PROD state and operating in production debug mode. The masking logic ensures that these features are enabled securely, in line with the production debug flow described in the "SoC Debug Flow and Architecture for Production Mode" section. By leveraging the MCI’s masking infrastructure, the SoC integrator has greater flexibility to implement custom debugging options during production without compromising the security framework established by Caliptra.
742833
834+**Note: Unlike the production state, the manufacturing state supports only a single debug level. Although it uses the same masking register to override DFT_EN, only the register’s least significant bit is used in manufacturing debug mode.
743835
744836 ## LCC Interpretation for Caliptra “Core” Security States
745837
@@ -757,11 +849,11 @@
757849
758850 **Manufacturing Non-Debug Mode:** This state occurs when the LCC is in the MANUF state, with SOC_HW_DEBUG_EN high and DFT_EN and SOC_DFT_EN low. In this state, the secrets have been programmed into the system, and the Caliptra can generate CSR (Certificate Signing Request) upon request. However, it remains in a secure, non-debug mode to prevent reading secrets through the debugging interfaces.
759851
760-**Manufacturing Debug Mode:** Also occurring in the MANUF state, this mode is enabled when SOC_HW_DEBUG_EN is high. Here, the Caliptra Core provides debugging capabilities while maintaining security measures suitable for manufacturing environments. In this state, DFT_EN is low. However, it is important to note that it is up to SoC integrator if there is a need to enable DFT_EN with another set of mask register since LCC state is reflected to SoC.
852+**Manufacturing Debug Mode:** Also occurring in the MANUF state, this mode is enabled when SOC_HW_DEBUG_EN is high. Here, the Caliptra Core provides debugging capabilities while maintaining security measures suitable for manufacturing environments. In this state, DFT_EN is low. However, SOC_DFT_EN can be set high if LSB of `MCI_REG_SOC_DFT_EN_0` is set to high in MANUF debug state [MCI-LCC-Signal-Masking](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSHardwareSpecification.md#masking-logic-for-debugging-features-in-production-debug-mode-mci).
761853
762854 **Production Non-Debug Mode:** This state is active when the LCC is in the PROD or PROD_END states, with all debug signals (DFT_EN, SOC_HW_DEBUG_EN) set to low. The Caliptra Core operates in a secure mode with no debug access, suitable for fully deployed production environments.
763855
764-**Production Debug Mode:** This state is active when the LCC is in the PROD, with debug DFT_EN, SOC_HW_DEBUG_EN set to low. Caliptra Core provides debugging capabilities while maintaining security measures suitable for manufacturing environments. However, SOC_DFT_EN can be set high and CLTAP can be open if MCI masking logic is used.
856+**Production Debug Mode:** This state is active when the LCC is in the PROD or PROD_END states, with debug DFT_EN, SOC_HW_DEBUG_EN set to low. Caliptra Core provides debugging capabilities while maintaining security measures suitable for manufacturing environments. However, SOC_DFT_EN and SOC_HW_DEBUG_EN can be set high with MCI masking registers [MCI-LCC-Signal-Masking](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSHardwareSpecification.md#masking-logic-for-debugging-features-in-production-debug-mode-mci).
765857
766858 **Production Debug Mode in RMA:** In the RMA state, all debug signals are set high, allowing full debugging access. This state is typically used for end-of-life scenarios where detailed inspection of the system's operation is required.
767859
@@ -775,20 +867,22 @@
775867 | TEST_LOCKED | Low | Low | Low | Prod Non-Debug |
776868 | TEST_UNLOCKED | High | High | High | Unprovisioned Debug |
777869 | MANUF | Low | Low | High | Manuf Non-Debug |
778-| MANUF* | Low | Low | High | Manuf Debug |
870+| MANUF* | Low | High** | High | Manuf Debug |
779871 | PROD | Low | Low | Low | Prod Non-Debug |
780872 | PROD* | Low | High** | High** | Prod Debug |
781873 | PROD_END | Low | Low | Low | Prod Non-Debug |
874+| PROD_END* | Low | High** | High** | Prod Debug |
782875 | RMA | High | High | High | Prod Debug |
783876 | SCRAP | Low | Low | Low | Prod Non-Debug |
784877 | INVALID | Low | Low | Low | Prod Non-Debug |
785878
786879
787880 **Note:** In RAW, TEST_LOCKED, SCRAP and INVALID states, Caliptra “Core” is not brought out of reset.
788-*: These states are Caliptra SS’s extension to LCC. Although the LCC is in either MANUF or PROD states, Caliptra core can grant debug mode through the logics explained in “How does Caliptra Subsystem enable manufacturing debug mode?” and “SoC Debug Flow and Architecture for Production Mode”.
789-**: SOC_HW_DEBUG_EN and DFT_EN can be overridden by SoC support in PROD state.
881+*: These states are Caliptra SS’s extension to LCC. Although the LCC is in either MANUF or PROD, PROD_END states, Caliptra core can grant debug mode through the logics explained in “How does Caliptra Subsystem enable manufacturing debug mode?” and “SoC Debug Flow and Architecture for Production Mode”.
882+**: SOC_HW_DEBUG_EN and DFT_EN can be overridden by SoC support in debug mode of MANUF and PROD, PROD_END states.
790883
791884 ## Exception: Non-Volatile Debugging Infrastructure and Initial RAW State Operations
885+
792886 The Caliptra Subsystem features a non-volatile debugging infrastructure that allows the SoC integrator to utilize a dedicated SRAM for early-stage debugging during the VolatileUnlock state. This SRAM provides a means to store executable content for the MCU, enabling early manufacturing debug operations.
793887
794888 It is important to note that the VolatileUnlock state is not a standard LCC state but rather a temporary state. Unlike other LCC states, the LCC can transition to this state without requiring a power cycle, provided the necessary global VolatileUnlock token is passed. This token is unique in that it is not stored in the FUSE partition but is instead a global netlist secret.
@@ -832,11 +926,10 @@
832926 For conditional transitions, the LCC can also branch different states (TEST_UNLOCK, MANUF, PROD, PROD_EN, RMA) based on the received token through the TAP interface and compared the received tokens against the ones stored in FUSE . This branching is called conditional transitions. For more information about the conditional states, please refer to [OpenTitan open-source silicon Root of Trust (RoT) project](https://opentitan.org/book/hw/ip/lc_ctrl/doc/theory_of_operation.html).
833927
834928 **Notes:**
835-* Some tokens are hardcoded design constants (specifically for RAW to TEST_UNLOCK), while others are stored in FUSE.
836-* Conditional transitions will only be allowed if the FUSE partition holding the corresponding token has been provisioned and locked.
837-* For transition counter limits and token hashing mechanism, please refer to OpenTitan open-source silicon Root of Trust (RoT) project [1].
838-* The LCC enters the post transition handling routine after completing conditional and unconditional transitions. During this routine, the LCC disables all of its decoded outputs and puts the system in an inert state.
839-
929+- Some tokens are hardcoded design constants (specifically for RAW to TEST_UNLOCK), while others are stored in FUSE.
930+- Conditional transitions will only be allowed if the FUSE partition holding the corresponding token has been provisioned and locked.
931+- For transition counter limits and token hashing mechanism, please refer to OpenTitan open-source silicon Root of Trust (RoT) project [1].
932+- The LCC enters the post transition handling routine after completing conditional and unconditional transitions. During this routine, the LCC disables all of its decoded outputs and puts the system in an inert state.
840933
841934 # Manufacturer Control Unit (MCU)
842935
@@ -845,18 +938,21 @@
845938 If the MCU VeeR instance must be regenerated with new configuration, a shell script is available in the Caliptra Subsystem repository. The script is located at `tools/scripts/veer_build_command.sh`.
846939
847940 # Manufacturer Control Interface (MCI)
941+
848942 ## Overview
943+
849944 The Manufacturer Control Interface (MCI) is a critical hardware block designed to supplement the Manufacturer Control Unit (MCU) within a System on Chip (SoC). The primary functions of the MCI include providing an SRAM bank, facilitating restricted communication through a mailbox from external entities, and managing a bank of Control/Status Registers (CSRs). Additionally, the MCI incorporates a Watchdog Timer and a Boot Sequencing Finite State Machine (FSM) to manage timing and control during the SoC boot sequence after power application. This boot sequence encompasses reset deassertion, initialization of the Fuse Controller, initialization of the Lifecycle Controller, and enabling the JTAG block for debugging and manufacturing processes.
850945
851946 The following diagram illustrates the internal components of the MCI.
852947 ![](../images/caliptra-ss/docs/images/MCI-Integ-Block-Diagram.png)
853948
854949 ## MCI Feature Descriptions
950+
855951 ### Control/Status Registers (CSRs)
952+
856953 The Control/Status Registers (CSRs) within the MCI are designed to provide critical control and status monitoring functions for the SoC. These registers include configuration settings, status indicators, and control bits that allow communication and management of the various operations of the MCI. The CSR bank is accessible via the AXI interface and is mapped into the memory space to facilitate straightforward access and manipulation.
857954
858955 [MCI Reg Spec](https://chipsalliance.github.io/caliptra-ss/main/regs/?p=soc.mci_top.mci_reg)
859-
860956
861957 #### MCI CSR Access Restrictions
862958
@@ -871,12 +967,11 @@
871967 2. MCI SOC Config User (MSCU)
872968 3. MCU SRAM Config User (MSRCU)
873969
874-All of these AXI Users come from straps and are not modifiable by SW. MCU is given the highest level of access and is expected to configure MCI registers and lock the configuration with various SS_CONFIG_DONE and LOCK bits. It also has access to certain functionalality like timers that are needed by the SOC but are critical for MCU functionality.
875-
876-The MSCU is meant as a secondary config agent if the MCU is unable to configure MCI. Example when in the no ROM config it is expected the MCSCU can configure and lock down the MCI configuration. MSCU can be **disabled** by setting the strap to 0x0. For debug the MSCU strap can be set to all 1s meaning every access will give this level of privilege.
877-The MCRCU populates the MCU FW update in MCU SRAM. There are a few registers within the MCI register bank it has special access to for facilitating the FW update.
970+All of these AXI Users come from straps and are not modifiable by SW. MCU is given the highest level of access and is expected to configure MCI registers and lock the configuration with various SS_CONFIG_DONE and LOCK bits. It also has access to certain functionalality like timers that are needed by the SOC but are critical for MCU functionality.
971+
972+The MSCU is meant as a secondary config agent if the MCU is unable to configure MCI. Example when in the no ROM config it is expected the MCSCU can configure and lock down the MCI configuration. MSCU can be **disabled** by setting the strap to 0x0. For debug the MSCU strap can be set to all 1s meaning every access will give this level of privilege.
973+The MCRCU populates the MCU FW update in MCU SRAM. There are a few registers within the MCI register bank it has special access to for facilitating the FW update.
878974 The registers can be split up into a few different categories:
879-
880975
881976 | **Write restrictions** | **Description** |
882977 | :--------- | :--------- |
@@ -891,10 +986,9 @@
891986 | MBOX_USER_LOCK | Mailbox specific configuration locked by it's own LOCK bit. Configured afer each arem reset. |
892987
893988
894-
895989 ### MCI Straps
896990
897-All MCI straps shall be static before mci_rst_b is deasserted. Some straps have further restrictions as described below.
991+All MCI straps shall be static before mci_rst_b is deasserted. Some straps have further restrictions as described below.
898992
899993 MCI has the following types of straps:
900994
@@ -903,7 +997,6 @@
903997 | **Non-configurable Direct** | Direct | Used directly by MCI and not sampled at all. These shall be constant non-configurable inputs to CSS/MCI. Inside MCI these are not overridable by SW. |
904998 | **Non-configurable Sampled** | Sampled* | Sampled once per cold boot and not overridable by SW |
905999 | **Configurable Sampled** | Sampled** | Sampled once per warm boot and SW can override via MCI Register Bank until SS_CONFIG_DONE is set. |
906-
9071000
9081001
9091002 *NOTE: Strap sampling occurs when mci_rst_b is deasserted and is typically performed once per cold boot. This process is controlled by the SS_CONFIG_DONE_STICKY register; when set, sampling is skipped. If a warm reset happens before SS_CONFIG_DONE_STICKY is set, the straps will be sampled again, although this is not the usual behavior.
@@ -920,7 +1013,6 @@
9201013 | `ss_debug_intent` | Non-configurable Sampled | Provides some debug access to MCI. Show the intent to put the part in a debug unlocked state. Although not writable by SW via AXI. This is writable via DMI. |
9211014
9221015
923-
9241016 ### Subsystem Boot Finite State Machine (CSS-BootFSM)
9251017
9261018 The Boot Sequencer FSM is responsible for the orderly and controlled boot process of the Caliptra Subsystem. This state machine ensures that all necessary initialization steps are completed in the correct sequence after power application. The boot sequence includes MCU and Caliptra Reset deassertions, Fuse Controller Initialization, and Lifecycle Controller Initialization.
@@ -930,37 +1022,37 @@
9301022 **Note:** SOC may have other HW FSM steps that were done before Caliptra (CSS) is brought out of reset such as locking a PLL or calibrating a CRO, setting up GPIOs, test logic bring up etc. using SOC HW FSM.
9311023
9321024 1. SOC asserts Caliptra SS powergood and desserts Caliptra SS reset to MCI
933-
1025+
9341026 a. SOC may choose to connect the same signals to the AXI fabric or bring it out of reset using a different signals. But the requirement is that before MCU is out of reset, fabric should be operational.
9351027
9361028 2. CSS-BootFSM will sample straps in MCI and will drive its outputs to reset defaults.
937-
1029+
9381030 c. **Note:** In allowed LCC states, MCU TAP will be available when MCI is brought out of reset. Uncore registers in MCI will be available, but Core registers within MCU will only be available when MCU reset is deasserted.
9391031
9401032 3. CSS-BootFSM will go through Caliptra Subsystem Fuse controller (CSS FC) Init Sequence Init Sequence/handshakes
9411033 4. CSS-BootFSM will go through Caliptra Subsystem Life Cycle Controller (CSS LCC) Init Sequence/handshakes
942-
1034+
9431035 a. **SOC Note:** Note that LCC shall start on an SOC generated internal clock to prevent clock stretch attacks
944-
1036+
9451037 b. **SOC Note:** If the life cycle state is in RAW, TEST* or RMA, and if TRANSITION_CTRL.EXT_CLOCK_EN is set to one, the CLK_BYP_REQ signal is asserted in order to switch the main system clock to an external clock signal. This functionality is needed in certain life cycle states where the SOC internal clock source may not be fully calibrated yet, since the FUSE macro requires a stable clock frequency in order to reliably program the fuse array. Note that the TRANSITION_CTRL.EXT_CLOCK_EN register can only be set to one if the transition interface has been claimed via the CLAIM_TRANSITION_IF mutex. This function is not available in production life cycle states.
9461038
9471039 5. If MCU-No-ROM-Config strap is not set, then CSS-BootFSM will bring MCU out of reset and MCU ROM will start executing.
948-
1040+
9491041 a. **Note:** MCU ROM may be used by some SOCs for doing additional SOC specific initializations.An example of such a SoC construction is MCI, MCU, CSS Fabric are running on external clock initially. MCU brings up PLL, some GPIO peripherals, does I3C init sequence etc and then performs clock switch to internal PLL clock domain so that the fabric is running on the internal clock domain before secrets are read on it from the fuse controller.
950-
1042+
9511043 6. If MCU-No-ROM-Config is not set, MCU ROM will bring Caliptra out of reset by writing a MCI register (CPTRA_BOOT_GO)
9521044 7. If MCU-No-ROM-Config is set, CSS-BootFSM waits for a Caliptra GO write from SOC to bring Caliptra out of reset.
953-
1045+
9541046 a. **Note:** MCU Reset Vector will be strapped to the MCU SRAM executable location at integration time.
955-
956- b. **Note:** MCI will allow "MCI SOC CONFIG" AXI User to configure MCI registers MCU typically configures.
957-
1047+
1048+ b. **Note:** MCI will allow "MCI SOC CONFIG" AXI User to configure MCI registers MCU typically configures.
1049+
9581050 b. **Note:** MCI will allow any AXI User to write into SRAM if the LCC & debug state allows. SOC will have flexibility to implement desired logic to write to MCU SRAM to skip MCU ROM and a register bit to bring MCU out of reset. MCU will start executing from the reset vector that was strapped which enables the first fetch vector to access MCI SRAM
9591051 8. Caliptra reset (cptra_rst_b) is deasserted.
9601052 9. Caliptra BootFSM will go through its own boot flow as documented in Caliptra spec, reads secret fuses and sets “ready_for_fuses” to MCI.
9611053
962- **Note:** In MCU-NO-ROM-CONFIG, steps 11 through 14 & steps 16 through 18 are done by a SOC entity. Otherwise, MCU ROM will do the below steps.
963-
1054+ **Note:** In MCU-NO-ROM-CONFIG, steps 11 through 14 & steps 16 through 18 are done by a SOC entity. Otherwise, MCU ROM will do the below steps.
1055+
9641056 10. MCU ROM will be polling for this indication
9651057 11. MCU ROM will now read FC’s SW partition for all the required fuses including its own and also write Caliptra fuses. Note that only non-secret fuses are accessible for MCU ROM by fuse controller construction.
9661058 a. Note: All fuses will be zero if FC is not programmed
@@ -974,6 +1066,7 @@
9741066 ![](../images/caliptra-ss/docs/images/Caliptra-SS-BootFSM.png)
9751067
9761068 ### Watchdog Timer
1069+
9771070 The Watchdog Timer within the MCI is a crucial component designed to enhance the reliability and robustness of the SoC. This timer monitors the operation of the system and can trigger a system reset if it detects that the system is not functioning correctly. The Watchdog Timer is configurable through CSRs and provides various timeout periods and control mechanisms to ensure the system operates within defined parameters.
9781071 The Watchdog timer contains two different timers. These timers can be configured in two different modes:
9791072
@@ -986,7 +1079,7 @@
9861079 2. Timer 2 will start counting
9871080
9881081 If the WDT is not serviced before Timer 2 times out two things happen:
989-
1082+
9901083 1. NMI output pin is asserted
9911084 2. NMI HW_ERROR_FATAL is triggered which can assert an error_fatal on the MCI port.
9921085
@@ -1006,7 +1099,7 @@
10061099
10071100 #### MCU Mailbox Locking
10081101
1009-A Requester will read the "LOCK" register to obtain a lock on the mailbox. This is a read-set register, the lock is acquired when read returns 0. The Requester must be a [Trusted user](#mcu-mailbox-limited-trusted-axi-users). Once the lock is obtained the Requestor has read access to the entire mailbox and write access to:
1102+A Requester will read the "LOCK" register to obtain a lock on the mailbox. This is a read-set register, the lock is acquired when read returns 0. The Requester must be a [Trusted user](#mcu-mailbox-limited-trusted-axi-users). Once the lock is obtained the Requestor has read access to the entire mailbox and write access to:
10101103
10111104 - All mailbox registers except the following will be RO:
10121105 - CMD_STATUS
@@ -1016,7 +1109,7 @@
10161109 - Mailbox SRAM
10171110 Unlocking/releasing occurs when the requestor writes 0 to the EXECUTE register. After releasing the mailbox the SRAM is zeroed out([MCU Mailbox SRAM Clearing](#mcu-mailbox-sram-clearing)).
10181111
1019-On MCI reset release the MCU MBOX is locked for MCU. The MCU shall set the DLEN to the size of the SRAM and release the MBOX, causing the SRAM to be zeroed. This is done to prevent data leaking between warm resets via the SRAM.
1112+On MCI reset release the MCU MBOX is locked for MCU. The MCU shall set the DLEN to the size of the SRAM and release the MBOX, causing the SRAM to be zeroed. This is done to prevent data leaking between warm resets via the SRAM.
10201113
10211114 #### MCU Mailbox Target User
10221115
@@ -1033,7 +1126,7 @@
10331126 - TARGET_DONE register
10341127 - Mailbox SRAM
10351128
1036-The Target user will notify MCU it is done processing by setting TARGET_STATUS and TARGET_DONE. Setting TARGET_DONE will interrupt MCU. If required, MCU will then update the CMD_STATUS register with the final status of the command for the Requestor.
1129+The Target user will notify MCU it is done processing by setting TARGET_STATUS and TARGET_DONE. Setting TARGET_DONE will interrupt MCU. If required, MCU will then update the CMD_STATUS register with the final status of the command for the Requestor.
10371130
10381131 If a second Target user is required it is the MCU's responsibility to:
10391132
@@ -1041,7 +1134,7 @@
10411134 2. Clear TARGET_DONE
10421135 3. Set new TARGET_USER
10431136
1044-Otherwise these registers are cleared when the mailbox lock is released.
1137+Otherwise these registers are cleared when the mailbox lock is released.
10451138
10461139 Target users must be an [MCU Mailbox trusted user](mcu-mailbox-limited-trusted-AXI-user)
10471140
@@ -1053,7 +1146,7 @@
10531146
10541147 **Max Size**: 2MB
10551148
1056-If set to 0 the mailbox is not instantiated.
1149+If set to 0 the mailbox is not instantiated.
10571150
10581151 Accesses must be DWORD aligned and BYTE accesses are not supported by the SRAM.
10591152
@@ -1066,7 +1159,7 @@
10661159 3. MCU SRAM clearing ends
10671160 4. Mailbox is unlocked
10681161
1069-The Requester is locked out of the mailbox after step 1, even though the lock isn't cleared until step 4.
1162+The Requester is locked out of the mailbox after step 1, even though the lock isn't cleared until step 4.
10701163
10711164 It is expected that agents write their content from 0 to DLEN. If an agent writes outside of this SRAM area, there is no security guarantee for that content because that data would not be zeroized between mailbox operations.
10721165
@@ -1088,6 +1181,7 @@
10881181 | **Interrupt** | **Description** |
10891182 | :--------- | :--------- |
10901183 | Mailbox data available from MCU | Asserted when MCU gets lock and assert the EXECUTE register, indicating data is available for SOC consumption. |
1184+
10911185
10921186 #### MCU Mailbox Errors
10931187
@@ -1101,13 +1195,13 @@
11011195 | Double Bit ECC Error | - Error interrupt to MCU<br> - HW_NON_FATAL error set for SOC consumption<br>- Mailbox ECC DB status set<br>- Invalid data returned | Double bit ECC error while reading Mailbox. |
11021196
11031197
1104-Whenever an agent reads data from the SRAM they either need to consume the Double Bit ECC interrupt wire or check the MCU Mailbox status registers to know if the data they received is valid.
1198+Whenever an agent reads data from the SRAM they either need to consume the Double Bit ECC interrupt wire or check the MCU Mailbox status registers to know if the data they received is valid.
11051199
11061200 #### MCU Mailbox MCU Access
11071201
1108-When there is a mailbox lock the MCU has full access to the mailbox CSRs and SRAM in order to facilitage interactions and help with any lockup.
1109-
1110-It is the only agent allowed to set TARGET_USER and update the final CMD_STATUS.
1202+When there is a mailbox lock the MCU has full access to the mailbox CSRs and SRAM in order to facilitage interactions and help with any lockup.
1203+
1204+It is the only agent allowed to set TARGET_USER and update the final CMD_STATUS.
11111205
11121206 #### MCU Mailbox Address Map
11131207
@@ -1117,11 +1211,12 @@
11171211 | 0x0020_0000 | 0x020_003F | MBOX CSR | Mailbox Control Status Registers |
11181212
11191213
1120- *NOTE: MBOX SRAM size is configurable, but MBOX always reserves 2MB address space. See [MCU Mailbox Errors](#mcu-mailbox-errors) for how access to and invalid SRAM address are handled.
1214+ *NOTE: MBOX SRAM size is configurable, but MBOX always reserves 2MB address space. See [MCU Mailbox Errors](#mcu-mailbox-errors) for how access to and invalid SRAM address are handled.
11211215
11221216 [MCU MBOX Register Spec](https://chipsalliance.github.io/caliptra-ss/main/regs/?p=soc.mci_top.mcu_mbox0_csr)
11231217
11241218 ### MCU SRAM
1219+
11251220 ![](../images/caliptra-ss/docs/images/MCI-MCU-SRAM-Diagram.png)
11261221
11271222 The MCU SRAM provides essential data and instruction memory for the Manufacturer Control Unit. This SRAM bank is utilized by the MCU to load firmware images, store application data structures, and create a runtime stack. The SRAM is accessible via the AXI interface and is mapped into the MCI's memory space for easy access and management. Exposing this SRAM via a restricted API through the SoC AXI interconnect enables seamless and secured Firmware Updates to be managed by Caliptra.
@@ -1133,18 +1228,20 @@
11331228 AXI USER filtering is used to restrict access within the MCU SRAM based on system state and accessor. Access permissions are based on the AXI USER input straps (either the MCU SRAM Config AXI_USER, or the MCU IFU/LSU AXI USERS). Any write attempt by an invalid AXI_USER is discarded and returns an error status. Any read attempt returns 0 data and an error status.
11341229 The MCU SRAM contains two regions, a Protected Data Region and an Updatable Execution Region, each with a different set of access rules.
11351230
1136-After each MCU reset the Updateable Execution Region may only be read/written by MCU SRAM Config User (typically Caliptra) prior to mcu_sram_fw_exec_region_lock input signal is set. Once fw_exec_region_lock is set it can be read/written by the MCU IFU or MCU LSU until MCU reset is asserted.
1231+After each MCU reset the Updateable Execution Region may only be read/written by MCU SRAM Config User (typically Caliptra) prior to mcu_sram_fw_exec_region_lock input signal is set. Once fw_exec_region_lock is set it can be read/written by the MCU IFU or MCU LSU until MCU reset is asserted.
11371232
11381233 The Protected Data Region is only ever read/write accessible by MCU LSU.
1139-The span of each region is dynamically defined by the MCU ROM during boot up. Once MCU has switched to running Runtime Firmware, the RAM sizing shall be locked until any SoC-level reset. ROM uses the register FW_SRAM_EXEC_REGION_SIZE to configure the SRAM allocation in 4KB increments. FW_SRAM_EXEC_REGION_SIZE counts in base 0 meaning the smallest the Updateable Execution Region size can be is 4KB. It is possible for the entire SRAM to be allocated to the Updatable Execution Region and there be no Protected Data Region.
1140-
1141-The entire MCU SRAM has ECC protection with no ability to disable. Single bit errors are detected and corrected. Double bit errors are detected and error.
1234+The span of each region is dynamically defined by the MCU ROM during boot up. Once MCU has switched to running Runtime Firmware, the RAM sizing shall be locked until any SoC-level reset. ROM uses the register FW_SRAM_EXEC_REGION_SIZE to configure the SRAM allocation in 4KB increments. FW_SRAM_EXEC_REGION_SIZE counts in base 0 meaning the smallest the Updateable Execution Region size can be is 4KB. It is possible for the entire SRAM to be allocated to the Updatable Execution Region and there be no Protected Data Region.
1235+
1236+The entire MCU SRAM has ECC protection with no ability to disable. Single bit errors are detected and corrected. Double bit errors are detected and error.
11421237
11431238 **MCI actions for single bit errors:**
1239+
11441240 - Correct data and pass corrected data back to the initiator.
11451241 - Send maskable interrupt notification to MCU.
11461242
11471243 **MCI actions for double bit errors:**
1244+
11481245 - AXI SLVERR response to the initiator
11491246 - HW_ERROR_FATAL asserted and sent to SOC
11501247
@@ -1152,7 +1249,7 @@
11521249
11531250 #### MCU Hitless Update Handshake
11541251
1155-The hitless flow is described in full in [Caliptra Top Spec](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#subsystem-support-for-hitless-updates). The [Caliptra SS Integration Spec](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSIntegrationSpecification.md#mci) contains all MCI warm reset and hitless update flows and restrictions. This section is focused on the HW registers both Caliptra and MCU will used to complete the flow.
1252+The hitless flow is described in full in [Caliptra Top Spec](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#subsystem-support-for-hitless-updates). The [Caliptra SS Integration Spec](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSIntegrationSpecification.md#mci) contains all MCI warm reset and hitless update flows and restrictions. This section is focused on the HW registers both Caliptra and MCU will used to complete the flow.
11561253
11571254 MCI tracks three different ```RESET_REASON``` in its register bank:
11581255
@@ -1171,7 +1268,7 @@
11711268
11721269 ### MCI AXI Subordinate
11731270
1174-MCI AXI Subordinate decodes the incoming AXI transaction and passes it onto the appropriate submodule within MCI.
1271+MCI AXI Subordinate decodes the incoming AXI transaction and passes it onto the appropriate submodule within MCI.
11751272
11761273 The MCI AXI Sub will respond with an AXI error if one of the following conditions is met:
11771274
@@ -1182,24 +1279,25 @@
11821279 1. Writes dropped
11831280 2. Reads return 0
11841281
1185-
11861282 ### MCI Interrupts
11871283
11881284 ![](../images/caliptra-ss/docs/images/MCI-Interrupts.png)
11891285
11901286 All interrupt status and control registers live in the CSR block. Each interrupt has the following properties:
1287+
11911288 - Status: W1C for SW to clear
11921289 - Enable: Prevents status from propagating. It does not block the status from being set.
11931290 - SW Trigger: Ability for SW to manually trigger the interrupt. Typically used for debug.
1194-- Counter: Counts number of times the interrupt event was detected (SW or HW).
1291+- Counter: Counts number of times the interrupt event was detected (SW or HW).
11951292
11961293 There are two different groups of interrupts
1294+
11971295 - Error
1198-- Notification
1199-
1200-Each group of interrupts has its own global status and enable registers that are an aggregate of all interrupts in the group. These status and enable registers have the same properties as the individual interrupt status and enable registers.
1201-
1202-All interrupt groups are ORed and sent out on a signal mci_intr pin.
1296+- Notification
1297+
1298+Each group of interrupts has its own global status and enable registers that are an aggregate of all interrupts in the group. These status and enable registers have the same properties as the individual interrupt status and enable registers.
1299+
1300+All interrupt groups are ORed and sent out on a signal mci_intr pin.
12031301
12041302 SW access to all interrupt registers are restricted to MCU.
12051303
@@ -1223,7 +1321,7 @@
12231321
12241322 Regions of 6 bits in the aggregate error registers are reserved for each component.
12251323 MCU and Caliptra errors are connected to appropriate severity levels.
1226-Lifecycle controller, fuse controller and I3C are connected to both severities.
1324+Lifecycle controller, fuse controller and I3C are connected to both severities.
12271325 Masks are used to set the severity of each error for these components. These can be configured by integrators, ROM, or runtime firmware.
12281326
12291327 | **Error Register Bits** | **Component** | **Default Error Severity** | **Description** |
@@ -1239,11 +1337,12 @@
12391337
12401338 ![](../images/caliptra-ss/docs/images/MCI-internal-error.png)
12411339
1242-
12431340 ### MCI Fuse Storage Support
1341+
12441342 MCI also provides capability to store fuses required for Caliptra subsystem for Caliptra core's usage for production debug unlock feature. MCU will read the fuse controller for the production debug unlock hashes , write to the corresponding registers in the MCI block and lock the registers from being changed by MCU RT FW. Lock is done by writing to do a FUSE_WR_DONE (FIXME: Add specific register & bit names).
12451343
12461344 ### MCU Timer
1345+
12471346 Standard RISC-V timer interrupts for MCU are implemented using the mtime and mtimecmp registers defined in the RISC-V Privileged Architecture Specification. Both mtime and mtimecmp are included in the MCI register bank, and are accessible by the MCU to facilitate precise timing tasks. Frequency for the timers is configured by the SoC using the dedicated timer configuration register, which satisfies the requirement prescribed in the RISC-V specification for such a mechanism. These timer registers drive the timer_int pin into the MCU.
12481347
12491348 ### MCU Trace Buffer
@@ -1261,12 +1360,13 @@
12611360 ![](../images/caliptra-ss/docs/images/MCI-MCU-Trace-Buffer-Circular-Diagram.png)
12621361
12631362 #### MCU Trace Buffer SW Interface
1363+
12641364 Below is the SW interface to extract trace data:
12651365
1266-| **Register Name** | **Access Type** | **Description** |
1267-| :--------- | :--------- | :---------|
1366+| **Register Name** | **Access Type** | **Description** |
1367+| :--------- | :--------- | :---------|
12681368 | DATA | RO | Trace data at READ_PTR location|
1269-| READ_PTR | RW | Read pointer in trace buffer for DATA. NOTE: this is not an address, meaning increment by 1 to get the next entry. |
1369+| READ_PTR | RW | Read pointer in trace buffer for DATA. NOTE: this is not an address, meaning increment by 1 to get the next entry. |
12701370 | WRITE_PTR | RO | Offset to store next trace entry in trace buffer. If VALID_DATA is set, WRITE_PTR - 1 is the newest trace entry. |
12711371 | STATUS.VALID_DATA | RO | Indicates at least one entry is valid in the trace buffer. |
12721372 | STATUS.WRAPPED | RO | Indicates the trace buffer has wrapped at least once. Meaning all entries in the trace buffer are valid. If 0, then the oldest entry in the buffer is at ptr=0. If 1, the oldest entry is at WRITE_PTR|
@@ -1280,7 +1380,7 @@
12801380
12811381 ![](../images/caliptra-ss/docs/images/MCI-MCU-Trace-Buffer-Data.png)
12821382
1283-Assuming there is only one trace stored in the trace buffer the WRITE_PTR would read as 0x4. To get the entire trace packet the user would need to read offsets 0x0, 0x1, 0x2, and 0x3.
1383+Assuming there is only one trace stored in the trace buffer the WRITE_PTR would read as 0x4. To get the entire trace packet the user would need to read offsets 0x0, 0x1, 0x2, and 0x3.
12841384
12851385 #### MCU Trace Buffer Extraction
12861386
@@ -1289,7 +1389,7 @@
12891389 1. Write READ_PTR
12901390 2. Read DATA
12911391
1292-Repeat these steps until all data required has been extracted.
1392+Repeat these steps until all data required has been extracted.
12931393
12941394 The user should use the combination of WRITE_PTR, VALID_DATA, WRAPPED, and TRACE_BUFFER_DEPTH to know where valid data lives in the trace buffer.
12951395
@@ -1297,21 +1397,20 @@
12971397
12981398 AXI access to the MCU Trace Buffer while not in debug mode will result in an AXI error.
12991399
1300-DMI access to the MCU Trace Buffer while not in debug mode will result in writes being dropped and reads returning 0.
1301-
1302-If the user sets the READ_PTR > (TRACE_BUFFER_DEPTH - 1) and tries to read the DATA register, the behavior is undefined.
1400+DMI access to the MCU Trace Buffer while not in debug mode will result in writes being dropped and reads returning 0.
1401+
1402+If the user sets the READ_PTR > (TRACE_BUFFER_DEPTH - 1) and tries to read the DATA register, the behavior is undefined.
13031403
13041404 ## MCI Debug
13051405
13061406 ### MCI Debug Access
13071407
1308-MCI provides DMI access via MCU TAP and a DEBUG AXI USER address for debug access to MCI.
1408+MCI provides DMI access via MCU TAP and a DEBUG AXI USER address for debug access to MCI.
13091409
13101410 #### MCI DMI
13111411
13121412 **NOTE: DMI access to MBOX0/1 is not enabled in Caliptra 2.0. This will be enabled in future Caliptra versions**
13131413 ![](../images/caliptra-ss/docs/images/MCI-DMI-Interface.png)
1314-
13151414
13161415 The DMI port on MCU is a dedicated interface that is controlled via the MCU TAP interface. MCI provides two services when it comes to DMI:
13171416
@@ -1328,15 +1427,13 @@
13281427 2. Uncore
13291428 - Access to MCI registers
13301429
1331-
13321430 MCI provides the logic for these enables. When the following condition(s) are met the enables are set:
13331431
13341432 **MCU Core Enable**: Debug Mode
13351433
13361434 **MCU Uncore Enable**: Debug Mode **OR** LCC Manufacturing Mode **OR** DEBUG_INTENT strap set
13371435
1338-*Note: These are the exact same controls Calipitra Core uses for DMI enable*
1339-
1436+*Note: These are the exact same controls Calipitra Core uses for DMI enable*
13401437
13411438 ##### MCI DMI Interface
13421439
@@ -1403,26 +1500,25 @@
14031500 | MCU\_NMI\_VECTOR | 0x7B | RW | | Yes |
14041501 | MCI\_DMI\_MCI\_HW\_OVERRIDE ([DMI ONLY Reg](#dmi-only-registers)) | 0x7C | RW | | Yes |
14051502
1406-###### DMI Only Registers
1503+###### DMI Only Registers
14071504
14081505 MCI\_DMI\_MCU\_HW\_OVERRIDE
14091506
1410-| Field Name | Bits | Access Type | Description |
1411-| :---- | :---- | :---- | :---- |
1507+| Field Name | Bits | Access Type | Description |
1508+| :---- | :---- | :---- | :---- |
14121509 | `mcu_sram_fw_exec_region_lock` | [0] | RW | mcu_sram_fw_exec_region_lock control. ORed with input signal giving debugger control if Caliptra Core in reset while attempting MCU reset flow. |
14131510 | `reserved` | [31:1] | RW | Reserved |
14141511
1415-
14161512 ##### DMI MCU SRAM Access
14171513
14181514 MCU SRAM is only accessable via DMI while in **Debug Unlock**. While in **Debug Unlock** DMI has RW permission to the entire MCU SRAM.
14191515
14201516 Due to limited DMI address space the MCU SRAM is accessable via a two register mailbox.
14211517
1422-* `MCU_SRAM_ADDR`
1423-* `MCU_SRAM_DATA`
1424-
1425-The first MCU SRAM address is at address 0x0. The address is byte addressable, but all accesses must be DWORD aligned. Failure to align the address will result in undefined behavior. Access to addresses beyond the MCU SRAM size will result in address wrapping.
1518+- `MCU_SRAM_ADDR`
1519+- `MCU_SRAM_DATA`
1520+
1521+The first MCU SRAM address is at address 0x0. The address is byte addressable, but all accesses must be DWORD aligned. Failure to align the address will result in undefined behavior. Access to addresses beyond the MCU SRAM size will result in address wrapping.
14261522
14271523 To write content to the MCU SRAM the flow is:
14281524
@@ -1434,20 +1530,19 @@
14341530 1. Write `MCU_SRAM_ADDR`
14351531 2. Read `MCU_SRAM_DATA`
14361532
1437-There is no error response on the DMI port, so any ECC error must be checked via the ECC registers in the MCI Register Bank.
1533+There is no error response on the DMI port, so any ECC error must be checked via the ECC registers in the MCI Register Bank.
14381534
14391535 **Important**: MCU core must be halted to access MCU SRAM via DMI. Failure to do so will result in collisions between the two interfaces and an error will be reported.
14401536
1441-
14421537 ##### DMI MCU Trace Buffer Access
14431538
14441539 Access to the MCU Trace buffer via DMI is the same SW interface as specified in [MCU Trace Buffer](#mcu-trace-buffer).
14451540
1446-Access is limited to **Debug Unlock** mode only. Access to this space while not in **Debug Unlock** will result in writes being dropped and reads return 0x0.
1541+Access is limited to **Debug Unlock** mode only. Access to this space while not in **Debug Unlock** will result in writes being dropped and reads return 0x0.
14471542
14481543 ### MCI Boot FSM Breakpoint
14491544
1450-The MCI Breakpoint is used as a stopping point for debugging Caliptra SS. At this breakpoint the user can either use one of the [MCI Debug Access](#MCI-Debug-Access) mechanisms to configure MCI before bringing MCU or Caliptra out of reset.
1545+The MCI Breakpoint is used as a stopping point for debugging Caliptra SS. At this breakpoint the user can either use one of the [MCI Debug Access](#mci-debug-access) mechanisms to configure MCI before bringing MCU or Caliptra out of reset.
14511546
14521547 #### MCI Boot FSM Breakpoint Flow
14531548
@@ -1455,7 +1550,7 @@
14551550 2. Deassert MCI Reset
14561551 3. DEBUG ACCESS TO MCI
14571552 4. Set MCI's BRKPOINT_GO register to 1
1458- - Through one of the [MCI Debug Access](#MCI-Debug-Access) methods.
1553+ - Through one of the [MCI Debug Access](#mci-debug-access) methods.
14591554 5. FSM will continue
14601555
14611556 ## MCI Design for Test (DFT)

Image Changes

v2.0: AXI-Recovery-Handler-Bypass.png

Image not present in this version

v2.1: AXI-Recovery-Handler-Bypass.png

New version

v2.0: AXI-Recovery-Handler.png

Image not present in this version

v2.1: AXI-Recovery-Handler.png

New version

v2.0: Caliptra-AXI-DMA-AES.png

Image not present in this version

v2.1: Caliptra-AXI-DMA-AES.png

New version

v2.0: Caliptra-AXI-DMA-RD-WR.png

Old version

v2.1: Caliptra-AXI-DMA-RD-WR.png

New version

v2.0: Caliptra-AXI-DMA-RD.png

Old version

v2.1: Caliptra-AXI-DMA-RD.png

New version

v2.0: Caliptra-AXI-DMA-WR.png

Old version

v2.1: Caliptra-AXI-DMA-WR.png

New version

v2.0: Caliptra-AXI-DMA.png

Old version

v2.1: Caliptra-AXI-DMA.png

New version

v2.0: LCC-Summary.png

Old version

v2.1: LCC-Summary.png

New version