` argument to simulation
## **Regression Tests** ##
-### Standalone SystemVerilog Testbench Regression ###
-Only tests from the L0 Regression List should be run.
-The list is defined in the file [L0_regression.yml](https://github.com/chipsalliance/caliptra-rtl/blob/main/src/integration/stimulus/L0_regression.yml)
-
-### UVM Regression ###
-The UVM simulation environment for `caliptra_top` uses a special set of validation firmware to generate stimulus as required for the test plan. This firmware suite is found in `src/integration/test_suites` and includes:
- - `caliptra_top`: A C-based program that emulates a minimal set of bringup functions similar to the function of the ROM. This C file transitions very early to either a the FMC image or Runtime image based on bringup (reset reason) conditions.
- - `caliptra_fmc`: A C-based program that emulates the functionality of the First Mutable Code. In this reduced-functionality validation implementation, the FMC code is a simple intermediary that runs from ICCM and serves to boot the Runtime Firmware.
- - `caliptra_rt`: A C-based program that emulates the functionality of the production Runtime code. This program receives and services interrupts, defines a minimal Non-Maskable Interrupt handler, generates FW resets as needed, processes mailbox commands (generated through the UVM validation test plan), and runs some baseline Watchdog Timer testing.
-
-These three programs are designed to be run within the context of a UVM simulation, and will fail to generate meaningful stimulus in the standalone `caliptra_top_tb` test.
-
+Only tests from the L0 Regression List should be run.
## **NOTES** ##
* The internal registers are auto rendered at the [GitHub page](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs)
diff --git a/Release_Notes.md b/Release_Notes.md
index d390c9210..3dc7c388d 100644
--- a/Release_Notes.md
+++ b/Release_Notes.md
@@ -14,11 +14,11 @@ See the License for the specific language governing permissions and
limitations under the License.*_
# **Release Notes** #
-_*Last Update: 2023/11/02*_
+_*Last Update: 2023/09/13*_
-## Rev 1p0-rc1 ##
+## Rev 1p0 ##
-### Rev 1p0-rc1 release date: 2023/11/03 (1p0 version pending ROM release for official declaration) ###
+### Rev 1p0 release date: (pending ROM release for official declaration) ###
- Caliptra IP Specification: see docs/ folder
- Caliptra Integration Specification: see docs/ folder
- Caliptra testplan: see docs/ folder
diff --git a/SECURITY.md b/SECURITY.md
deleted file mode 100644
index a7ac201ef..000000000
--- a/SECURITY.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Caliptra Project Security Incident Response
-
-Please refer to the security policy at [Caliptra security policy](https://github.com/chipsalliance/caliptra/security/policy).
diff --git a/docs/CaliptraHardwareSpecification.md b/docs/CaliptraHardwareSpecification.md
deleted file mode 100644
index 55f9068bc..000000000
--- a/docs/CaliptraHardwareSpecification.md
+++ /dev/null
@@ -1,1536 +0,0 @@
-
-
-Caliptra Hardware Specification
-
-Version 0.5
-
-
-
-# Scope
-
-This document defines technical specifications for a Caliptra RoT for Measurement (RTM)[1] cryptographic subsystem used in the Open Compute Project (OCP). This document, along with [Caliptra: A Datacenter System on a Chip (SoC) Root of Trust (RoT)](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html), shall comprise the Caliptra technical specification.
-
-# Overview
-
-This document provides definitions and requirements for a Caliptra cryptographic subsystem. The document then relates these definitions to existing technologies, enabling device and platform vendors to better understand those technologies in trusted computing terms.
-
-# Caliptra Core
-
-The following figure shows the Caliptra Core.
-
-*Figure 1: Caliptra Block Diagram*
-
-TODO: add figures
-
-## Boot FSM
-
-The Boot FSM detects that the SoC is bringing Caliptra out of reset. Part of this flow involves signaling to the SoC that Caliptra is awake and ready for fuses. After fuses are populated and the SoC indicates that it is done downloading fuses, Caliptra can wake up the rest of the IP by de-asserting the internal reset.
-
-The following figure shows the initial power-on arc of the Mailbox Boot FSM.
-
-*Figure 2: Mailbox Boot FSM state diagram*
-
-The Boot FSM first waits for the SoC to assert cptra\_pwrgood and de-assert cptra\_rst\_b. In the BOOT\_FUSE state, Caliptra signals to the SoC that it is ready for fuses. After the SoC is done writing fuses, it sets the fuse done register and the FSM advances to BOOT\_DONE.
-
-BOOT\_DONE enables Caliptra reset de-assertion through a two flip-flop synchronizer.
-
-## FW update reset (Impactless FW update)
-
-Runtime FW updates write to fw\_update\_reset register to trigger the FW update reset. When this register is written, only the RISC-V core is reset using cptra\_uc\_fw\_rst\_b pin and all AHB slaves are still active. All registers within the slaves and ICCM/DCCM memories are intact after the reset. Since ICCM is locked during runtime, it must be unlocked after the RISC-V reset is asserted. Reset is deasserted synchronously after a programmable number of cycles (currently set to 5 clocks) and normal boot flow updates the ICCM with the new FW from the mailbox SRAM. Reset de-assertion is done through a two flip-flop synchronizer. The boot flow is modified as shown in the following figure.
-
-*Figure 3: Mailbox Boot FSM state diagram for FW update reset*
-
-After Caliptra comes out of global reset and enters the BOOT\_DONE state, a write to the fw\_update\_reset register triggers the FW update reset flow. In the BOOT\_FWRST state, only the reset to the VeeR core is asserted, ICCM is unlocked and the timer is initialized. After the timer expires, the FSM advances from the BOOT\_WAIT to BOOT\_DONE state where the reset is deasserted.
-
-| Control register | Start address | Description |
-| :------- | :---------- | :--------- |
-| FW_UPDATE_RESET | 0x30030418 | Register to trigger the FW update reset flow. Setting it to 1 starts the Boot FSM. The field auto-clears to 0. |
-| FW_UPDATE_RESET_WAIT_CYCLES | 0x3003041C | Programmable wait time to keep the microcontroller reset asserted. |
-
-## RISC-V core
-
-The RISC-V core is VeeR EL2 from CHIPS Alliance. It is a 32-bit CPU core that contains a 4-stage, scalar, in-order pipeline. The core supports RISC-V’s integer(I), compressed instruction(C), multiplication and division (M), instruction-fetch fence, CSR, and subset of bit manipulation instructions (Z) extensions. A link to the RISC-V VeeR EL2 Programmer’s Reference Manual is provided in the [References](#references) section.
-
-### Configuration
-
-The RISC-V core is highly configurable and has the following settings.
-
-| Parameter | Configuration |
-| :---------------------- | :------------ |
-| Interface | AHB-Lite |
-| DCCM | 128 KiB |
-| ICCM | 128 KiB |
-| I-Cache | Disabled |
-| Reset Vector | 0x00000000 |
-| Fast Interrupt Redirect | Enabled |
-| External Interrupts | 31 |
-
-### Embedded memory export
-
-Internal RISC-V SRAM memory components are exported from the Caliptra subsystem to support adaptation to various fabrication processes. For more information, see the [Caliptra Integration Specification](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraIntegrationSpecification.md).
-
-#### Memory map address regions
-
-The 32-bit address region is subdivided into 16 fixed-sized, contiguous 256 MB regions. The following table describes the address mapping for each of the AHB devices that the RISC-V core interfaces with.
-
-| Subsystem | Address size | Start address | End address |
-| :------------------ | :----------- | :------------ | :---------- |
-| ROM | 48 KiB | 0x0000_0000 | 0x0000_BFFF |
-| Cryptographic | 512 KiB | 0x1000_0000 | 0x1007_FFFF |
-| Peripherals | 32 KiB | 0x2000_0000 | 0x2000_7FFF |
-| SoC IFC | 256 KiB | 0x3000_0000 | 0x3003_FFFF |
-| RISC-V Core ICCM | 128 KiB | 0x4000_0000 | 0x4001_FFFF |
-| RISC-V Core DCCM | 128 KiB | 0x5000_0000 | 0x5001_FFFF |
-| RISC-V MM CSR (PIC) | 256 MiB | 0x6000_0000 | 0x6FFF_FFFF |
-
-##### Cryptographic subsystem
-
-The following table shows the memory map address ranges for each of the IP blocks in the cryptographic subsystem.
-
-| IP/Peripheral | Slave \# | Address size | Start address | End address |
-| :---------------------------------- | :------- | :----------- | :------------ | :---------- |
-| Cryptographic Initialization Engine | 0 | 32 KiB | 0x1000_0000 | 0x1000_7FFF |
-| ECC Secp384 | 1 | 32 KiB | 0x1000_8000 | 0x1000_FFFF |
-| HMAC384 | 2 | 4 KiB | 0x1001_0000 | 0x1001_0FFF |
-| Key Vault | 3 | 8 KiB | 0x1001_8000 | 0x1001_9FFF |
-| PCR Vault | 4 | 8 KiB | 0x1001_A000 | 0x1001_BFFF |
-| Data Vault | 5 | 8 KiB | 0x1001_C000 | 0x1001_DFFF |
-| SHA512 | 6 | 32 KiB | 0x1002_0000 | 0x1002_7FFF |
-| SHA256 | 13 | 32 KiB | 0x1002_8000 | 0x1002_FFFF |
-
-##### Peripherals subsystem
-
-The following table shows the memory map address ranges for each of the IP blocks in the peripherals’ subsystem.
-
-| IP/Peripheral | Slave \# | Address size | Start address | End address |
-| :------------ | :------- | :----------- | :------------ | :---------- |
-| QSPI | 7 | 4 KiB | 0x2000_0000 | 0x2000_0FFF |
-| UART | 8 | 4 KiB | 0x2000_1000 | 0x2000_1FFF |
-| CSRNG | 15 | 4 KiB | 0x2000_2000 | 0x2000_2FFF |
-| ENTROPY SRC | 16 | 4 KiB | 0x2000_3000 | 0x2000_3FFF |
-
-##### SoC interface subsystem
-
-The following table shows the memory map address ranges for each of the IP blocks in the SoC interface subsystem.
-
-| IP/Peripheral | Slave \# | Address size | Start address | End address |
-| :------------------------- | :------- | :----------- | :------------ | :---------- |
-| Mailbox SRAM Direct Access | 10 | 128 KiB | 0x3000_0000 | 0x3001_FFFF |
-| Mailbox CSR | 10 | 4 KiB | 0x3002_0000 | 0x3002_0FFF |
-| SHA512 Accelerator CSR | 10 | 4 KiB | 0x3002_1000 | 0x3002_1FFF |
-| Mailbox | 10 | 64 KiB | 0x3003_0000 | 0x3003_FFFF |
-
-##### RISC-V core local memory blocks
-
-The following table shows the memory map address ranges for each of the local memory blocks that interface with RISC-V core.
-
-| IP/Peripheral | Slave \# | Address size | Start address | End address |
-| :-------------- | :------- | :----------- | :------------ | :---------- |
-| ICCM0 (via DMA) | 12 | 128 KiB | 0x4000_0000 | 0x4001_FFFF |
-| DCCM | 11 | 128 KiB | 0x5000_0000 | 0x5001_FFFF |
-
-#### Interrupts
-
-The VeeR-EL2 processor supports multiple types of interrupts, including non-maskable interrupts (NMI), software interrupts, timer interrupts, external interrupts, and local interrupts. Local interrupts are events not specified by the RISC-V standard, such as auxiliary timers and correctable errors.
-
-Caliptra uses NMI in conjunction with a watchdog timer to support fatal error recovery and system restart. For more information, see the [Watchdog timer](#watchdog-timer) section.
-
-Software and local interrupts are not implemented in the first generation of Caliptra. Standard RISC-V timer interrupts are implemented using the mtime and mtimecmp registers defined in the RISC-V Privileged Architecture Specification. Both mtime and mtimecmp are included in the soc\_ifc register bank, and are accessible by the internal microprocessor 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 internal microprocessor.
-
-##### Non-maskable interrupts
-
- 0p8 describe a register bank that may be used to dynamically configure the NMI reset vector. (i.e., where the PC resets to).
-
-##### External interrupts
-
-Caliptra uses the external interrupt feature to support event notification from all attached peripheral components in the subsystem. The RISC-V processor supports multiple priority levels (ranging from 1-15), which allows firmware to configure interrupt priority per component.
-
-Errors and notifications are allocated as interrupt events for each component, with error interrupts assigned a higher priority and expected to be infrequent.
-
-Notification interrupts are used to alert the processor of normal operation activity, such as completion of requested operations or arrival of SoC requests through the shared interface.
-
-Vector 0 is reserved by the RISC-V processor and may not be used, so vector assignment begins with Vector 1. Bit 0 of the interrupt port to the processor corresponds with Vector 1.
-
-| IP/Peripheral | Interrupt vector | Interrupt priority example
(Increasing, Max 15) |
-| :-------------------------------------------------- | :--------------- | :---------------------------------------------- |
-| Cryptographic Initialization Engine (Errors) | 1 | 8 |
-| Cryptographic Initialization Engine (Notifications) | 2 | 7 |
-| ECC (Errors) | 3 | 8 |
-| ECC (Notifications) | 4 | 7 |
-| HMAC (Errors) | 5 | 8 |
-| HMAC (Notifications) | 6 | 7 |
-| KeyVault (Errors) | 7 | 8 |
-| KeyVault (Notifications) | 8 | 7 |
-| SHA512 (Errors) | 9 | 8 |
-| SHA512 (Notifications) | 10 | 7 |
-| SHA256 (Errors) | 11 | 8 |
-| SHA256 (Notifications) | 12 | 7 |
-| QSPI (Errors) | 13 | 4 |
-| QSPI (Notifications) | 14 | 3 |
-| UART (Errors) | 15 | 4 |
-| UART (Notifications) | 16 | 3 |
-| RESERVED | 17 | 4 |
-| RESERVED | 18 | 3 |
-| Mailbox (Errors) | 19 | 8 |
-| Mailbox (Notifications) | 20 | 7 |
-
-## Watchdog timer
-
-The primary function of Caliptra Watchdog Timer (WDT) is to reset the microcontroller (Caliptra), in the event of a software malfunction, by resetting the device if it has not been cleared in software. It is a two-stage timer, independent of the RISCV core.
-
-### Operation
-
-The WDT consists of two timers. When enabled in cascade mode (done by enabling Timer 1 alone), the WDT increments Timer 1 until the counter rolls over or times out. Typically, the timer is serviced at regular intervals to prevent it from overflowing or rolling over. If Timer 1 has not timed out, Timer 2 is disabled and held at its initial value. However, when Timer 1 does roll over, it triggers an error interrupt to the RISC-V core. In parallel, Timer 2 is enabled and begins counting. If the interrupt is serviced before Timer 2 times out, the timers are reset and continue to operate normally. If Timer 2 times out, it asserts an SoC fatal error and an NMI. The SoC fatal error is also captured in the CPTRA\_HW\_ERROR\_FATAL register, which can be cleared by the SoC by writing a 1. A warm reset is required by the SoC to reset the timers when Timer 2 times out.
-
-The WDT timers can be configured to operate independent of each other. When the enable register for Timer 2 is set, the default configuration of cascaded timers is disabled and both timers count independently of each other. In this case, a timeout on Timer 2 causes an error interrupt to the RISC-V core similar to Timer 1. Disabling Timer 2 configures the timers back into the default cascaded mode.
-
-Each timer has an enable bit, a restart bit, and a 64-bit timeout value register that can be programmed as needed. The restart bit is used to service the timers and restart counting. The timeout period registers can be configured to the desired upper bound of timers.
-
-If the WDT timers are disabled and then re-enabled with a new timeout period, they must be restarted by setting the appropriate control register (restart bit). If the timers are temporarily disabled and re-enabled with the same timeout period, they resume counting and do not restart from 0.
-
-For more details regarding the register interface to control the WDT, see the [register documentation](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg) published in the RTL GitHub repository.
-
-The following figure shows the two timers.
-
-*Figure 4: Caliptra Watchdog Timer*
-
-### Prescale settings
-
-Assuming a clock source of 500 MHz, a timeout value of 32’hFFFF\_FFFF results in a timeout period of ~8.5 seconds. Two 32-bit registers are provided for each timer, allowing a 64-bit timeout period to be programmed for each timer. This accommodates a maximum timeout value of over 1000 years for the same 500 Mhz clock source.
-
-### Microcontroller interface
-
-The Caliptra microcontroller communicates with the mailbox through its internal AHB-Lite fabric.
-
-#### AHB-lite interface
-
-AHB-lite is a subset of the full AHB specification. It is primarily used in single master systems. This interface connects VeeR EL2 Core (LSU master) to the slave devices as shown in Figure 1.
-
-The interface can be customized to support variable address and data widths, and a variable number of slave devices. Each slave device is assigned an address range within the 32-bit address memory map region. The interface includes address decoding logic to route data to the appropriate AHB slave device based on the address specified.
-
-The integration parameters for Caliptra’s AHB-lite interface are shown in the following table.
-
-| Parameter | Value |
-| :------------ | :---- |
-| ADDRESS_WIDTH | 32 |
-| DATA_WIDTH | 64 |
-| NUM_OF_SLAVES | 17 |
-
-Each IP component in the Caliptra system uses a native AHB data width of 32-bits (1 dword). The AHB responder logic in each IP component contains width conversion logic that transforms from the fabric data width of 64-bits to this native 32-bit width. The conversion involves calculating the dword offset (either 0 or 1) relative to the native 64-bit width by evaluating bit [2] of the address line. This information is used to extract the correct 32-bits from the native write data line. If there is a data offset, data is shifted down by 32-bits; otherwise, the upper 32-bits are simply truncated. This new dword-address is passed to the internal register interface along with the dword-sized data. A similar conversion works in reverse to correctly place read data in the response data line from the responder.
-
-As a result of this implementation, 64-bit data transfers are not supported on the Caliptra AHB fabric. Firmware running on the internal microprocessor may only access memory and registers using a 32-bit or smaller request size, as 64-bit transfer requests will be corrupted.
-
-### Cryptographic subsystem
-
-For details, see the [Cryptographic subsystem architecture](#cryptographic-subsystem-architecture) section.
-
-### Peripherals subsystem
-
-Caliptra includes QSPI and UART peripherals that are used to facilitate alternative operating modes and debug. In the first generation, Caliptra includes code to enable QSPI in the RTL, but does not support the BMI profile. Therefore, QSPI must not be enabled. Similarly, the UART interface exists to facilitate firmware debug in an FPGA prototype, but should be disabled in final silicon. SystemVerilog defines used to disable these peripherals are described in the [Caliptra Integration Specification](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraIntegrationSpecification.md). Operation of these peripherals is described in the following sections.
-
-#### QSPI Flash Controller
-
-Caliptra implements a QSPI block that can communicate with 2 QSPI devices. This QSPI block is accessible to FW over the AHB-lite Interface.
-
-The QSPI block is composed of the spi\_host implementation. For information, see the [SPI\_HOST HWIP Technical Specification](https://opentitan.org/book/hw/ip/spi_host/index.html). The core code (see [spi\_host](https://github.com/lowRISC/opentitan/tree/master/hw/ip/spi_host)) is reused but the interface to the module is changed to AHB-lite and the number of chip select lines supported is increased to 2. The design provides support for Standard SPI, Dual SPI, or Quad SPI commands. The following figure shows the QSPI flash controller.
-
-*Figure 5: QSPI flash controller*
-
-#### Operation
-
-Transactions flow through the QSPI block starting with AHB-lite writes to the TXDATA FIFO. Commands are then written and processed by the control FSM, orchestrating transmissions from the TXDATA FIFO and receiving data into the RXDATA FIFO.
-
-The structure of a command depends on the device and the command itself. In the case of a standard SPI device, the host IP always transmits data on qspi\_d\_io[0] and always receives data from the target device on qspi\_d\_io[1]. In Dual or Quad modes, all data lines are bi-directional, thus allowing full bandwidth in transferring data across 4 data lines.
-
-A typical SPI command consists of different segments that are combined as shown in the following example. Each segment can configure the length, speed, and direction. As an example, the following SPI read transaction consists of 2 segments.
-
-*Figure 6: SPI read transaction segments*
-
-| Segment \# | Length (Bytes) | Speed | Direction | TXDATA FIFO | RXDATA FIFO |
-| :--------- | :------------- | :------- | :---------------- | :----------- | :----------------- |
-| 1 | 4 | standard | TX
qspi_d_io\[0\] | \[0\] 0x3 (ReadData)
\[1\] Addr\[23:16\]
\[2\] Addr\[15:8\]
\[3\] Addr\[7:0\] | |
-| 2 | 1 | standard | RX
qspi_d_io\[1\] | | \[0\] Data \[7:0\] |
-
-In this example, the ReadData (0x3) command was written to the TXDATA FIFO, followed by the 3B address. This maps to a total of 4 bytes that are transmitted out across qspi\_d\_io[0] in the first segment. The second segment consists of a read command that receives 1 byte of data from the target device across qspi\_d\_io[1].
-
-QSPI consists of up to four command segments in which the host:
-
-1. Transmits instructions or data at the standard rate
-2. Transmits instructions address or data on 2 or 4 data lines
-3. Holds the bus in a high-impedance state for some number of dummy cycles where neither side transmits
-4. Receives information from the target device at the specified rate (derived from the original command)
-
-The following example shows the QSPI segments.
-
-*Figure 7: QSPI segments*
-
-| Segment \# | Length (Bytes) | Speed | Direction | TXDATA FIFO | RXDATA FIFO |
-| :--------- | :------------- | :------- | :------------------ | :----------- | :---------------- |
-| 1 | 1 | standard | TX
qspi_d_io\[3:0\] | \[0\] 0x6B (ReadDataQuad) | |
-| 2 | 3\* | quad | TX
qspi_d_io\[3:0\] | \[1\] Addr\[23:16\]
\[2\] Addr\[15:8\]
\[3\] Addr\[7:0\] | |
-| 3 | 2 | N/A | None (Dummy) | | |
-| 4 | 1 | quad | RX
qspi_d_io\[3:0\] | | \[0\] Data\[7:0\] |
-
-Note: In the preceding figure, segment 2 doesn’t show bytes 2 and 3 for brevity.
-
-#### Configuration
-
-The CONFIGOPTS multi-register has one entry per CSB line and holds clock configuration and timing settings that are specific to each peripheral. After the CONFIGOPTS multi-register is programmed for each SPI peripheral device, the values can be left unchanged.
-
-The most common differences between target devices are the requirements for a specific SPI clock phase or polarity, CPOL and CPHA. These clock parameters can be set via the CONFIGOPTS.CPOL or CONFIGOPTS.CPHA register fields.
-
-The SPI clock rate depends on the peripheral clock and a 16b clock divider configured by CONFIGOPTS.CLKDIV. The following equation is used to configure the SPI clock period:
-
-
-
-By default, CLKDIV is set to 0, which means that the maximum frequency that can be achieved is at most half the frequency of the peripheral clock (Fsck = Fclk/2).
-
-We can rearrange the equation to solve for the CLKDIV:
-
-
-
-Assuming a 400MHz target peripheral, and a SPI clock target of 100MHz:
-
-CONFIGOPTS.CLKDIV = (400/(2\*100)) -1 = 1
-
-The following figure shows CONFIGOPTS.
-
-*Figure 8: CONFIGOPTS*
-
-#### Signal descriptions
-
-The QSPI block architecture inputs and outputs are described in the following table.
-
-| Name | Input or output | Description |
-| :------------------ | :-------------- | :-------------------------------------------------------- |
-| clk_i | input | All signal timings are related to the rising edge of clk. |
-| rst_ni | input | The reset signal is active LOW and resets the core. |
-| cio_sck_o | output | SPI clock |
-| cio_sck_en_o | output | SPI clock enable |
-| cio_csb_o\[1:0\] | output | Chip select \# (one hot, active low) |
-| cio_csb_en_o\[1:0\] | output | Chip select \# enable (one hot, active low) |
-| cio_csb_sd_o\[3:0\] | output | SPI data output |
-| cio_csb_sd_en_o | output | SPI data output enable |
-| cio_csb_sd_i\[3:0\] | input | SPI data input |
-
-#### SPI\_HOST IP programming guide
-
-The operation of the SPI\_HOST IP proceeds in seven general steps.
-
-To initialize the IP:
-
-1. Program the CONFIGOPTS multi-register with the appropriate timing and polarity settings for each csb line.
-2. Set the desired interrupt parameters.
-3. Enable the IP.
-
-Then for each command:
-
-4. Load the data to be transmitted into the FIFO using the TXDATA memory window.
-5. Specify the target device by programming the CSID.
-6. Specify the structure of the command by writing each segment into the COMMAND register.
-
- For multi-segment transactions, assert COMMAND.CSAAT for all but the last command segment.
-
-7. For transactions that expect to receive a reply, the data can then be read back from the RXDATA window.
-
-Steps 4-7 are then repeated for each subsequent command.
-
-#### UART
-
-Caliptra implements a UART block that can communicate with a serial device that is accessible to FW over the AHB-lite Interface. This is a configuration that the SoC opts-in by defining CALIPTRA\_INTERNAL\_UART.
-
-The UART block is composed of the uart implementation. For information, see the [UART HWIP Technical Specification](https://opentitan.org/book/hw/ip/uart/). The design provides support for a programmable baud rate. The UART block is shown in the following figure.
-
-*Figure 9: UART block*
-
-#### Operation
-
-Transactions flow through the UART block starting with an AHB-lite write to WDATA, which triggers the transmit module to start a UART TX serial data transfer. The TX module dequeues the byte from the internal FIFO and shifts it out bit by bit at the baud rate. If TX is not enabled, the output is set high and WDATA in the FIFO is queued up.
-
-The following figure shows the transmit data on the serial lane, starting with the START bit, which is indicated by a high to low transition, followed by the 8 bits of data.
-
-*Figure 10: Serial transmission frame*
-
-On the receive side, after the START bit is detected, the data is sampled at the center of each data bit and stored into a FIFO. A user can monitor the FIFO status and read the data out of RDATA.
-
-#### Configuration
-
-The baud rate can be configured using the CTRL.NCO register field. This should be set using the following equation:
-
-
-
-If the desired baud rate is 115,200bps:
-
-
-
-
-
-#### Signal descriptions
-
-The UART block architecture inputs and outputs are described in the following table.
-
-| Name | Input or output | Description |
-| :------- | :-------------- | :-------------------------------------------------------- |
-| clk_i | input | All signal timings are related to the rising edge of clk. |
-| rst_ni | input | The reset signal is active LOW and resets the core. |
-| cio_rx_i | input | Serial receive bit |
-| cio_tx_o | output | Serial transmit bit |
-
-### SoC mailbox
-
-For more information on the mailbox protocol, see [Mailbox](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/Caliptra_rtl.md#mailbox) in the Caliptra Integration Specification. TODO: Fix this!
-
-The following table describes the mailbox control registers.
-
-| Control register | Start address | Description |
-| :------------------------ | :---------------- | :----------------- |
-| MBOX_LOCK | 0x30020000 | Mailbox lock register for mailbox access. Reading 0 sets the lock. |
-| MBOX_USER | 0x30020004 | Stores the user that locked the mailbox.|
-| MBOX_CMD | 0x30020008 | Command requested for data in mailbox. |
-| MBOX_DLEN | 0x3002000c | Data length for mailbox access. |
-| MBOX_DATAIN | 0x30020010 | Data in register. Writes the next data to mailbox. |
-| MBOX_DATAOUT | 0x30020010 | Data out register. Reads the next data from mailbox.|
-| MBOX_EXECUTE | 0x30020018 | Mailbox execute register indicates to the receiver that the sender is done. |
-| MBOX_STATUS | 0x3002001c | Status of the mailbox command:
CMD_BUSY - 2’b00 – Indicates the requested command is still in progress
DATA_READY - 2’b01 – Indicates the return data is in the mailbox for the requested command
CMD_COMPLETE- 2’b10 – Indicates the successful completion of the requested command
CMD_FAILURE- 2’b11 – Indicates the requested command failed |
-| HW_ERROR_FATAL | 0x30030000 | Indicates fatal hardware error. |
-| HW_ERROR_NON_FATAL | 0x30030004 | Indicates non-fatal hardware error. |
-| FW_ERROR_FATAL | 0x30030008 | Indicates fatal firmware error. |
-| FW_ERROR_NON_FATAL | 0x3003000c | Indicates non-fatal firmware error. |
-| HW_ERROR_ENC | 0x30030010 | Encoded error value for hardware errors. |
-| FW_ERROR_ENC | 0x30030014 | Encoded error value for firmware errors. |
-| BOOT_STATUS | 0x30030018 | Reports the boot status. |
-| FLOW_STATUS | 0x3003001c | Reports the status of the firmware flows. |
-| GENERIC_INPUT_WIRES | 0x30030024 | Generic input wires connected to the SoC interface. |
-| GENERIC_OUTPUT_WIRES | 0x3003002c | Generic output wires connected to the SoC interface. |
-| KEY_MANIFEST_PK_HASH | 0x300302b0 | |
-| KEY_MANIFEST_PK_HASH_MASK | 0x30030370 | |
-| KEY_MANIFEST_SVN | 0x30030374 | |
-| BOOT_LOADER_SVN | 0x30030384 | |
-| RUNTIME_SVN | 0x30030388 | |
-| ANTI_ROLLBACK_DISABLE | 0x3003038c | |
-| IEEE_IDEVID_CERT_CHAIN | 0x30030390 | |
-| FUSE_DONE | 0x300303f0 | |
-
-### Security state
-
-Caliptra uses the MSB of the security state input to determine whether or not Caliptra is in debug mode.
-
-When Caliptra is in debug mode:
-
-* Security state MSB is set to 0.
-
-* Caliptra JTAG is opened for the microcontroller and HW debug.
-
-* Device secrets (UDS, FE, key vault, and obfuscation key) are programmed to debug values.
-
-If a transition to debug mode happens during ROM operation, any values computed from the use of device secrets may not match expected values.
-
-Transitions to debug mode trigger a hardware clear of all device secrets, and also trigger an interrupt to FW to inform of the transition. FW is responsible for initiating another hardware clear of device secrets utilizing the clear secrets register, in case any derivations were in progress and stored after the transition was detected. FW may open the JTAG after all secrets are cleared.
-
-Debug mode values may be set by integrators in the Caliptra configuration files. The default values are shown in the following table.
-
-| Name | Default value |
-| :-------------------------- | :------------ |
-| Obfuscation Key Debug Value | All 0x1 |
-| UDS Debug Value | All 0x1 |
-| Field Entropy Debug Value | All 0x1 |
-| Key Vault Debug Value 0 | All 0xA |
-| Key Vault Debug Value 1 | All 0x5 |
-
-### Clock gating
-
-Caliptra provides a clock gating feature that turns off clocks when the microcontroller is halted. Clock gating is disabled by default, but can be globally enabled via the following register.
-
-| Control register | Start address | Description |
-| :------------------- | :---------------- | :------------------------ |
-| CPTRA_CLK_GATING_EN | 0x300300bc | Register bit to enable or disable the clock gating feature. |
-
-When enabled, halting the microcontroller turns off clocks to all of the cryptographic subsystem, the vaults (keyvault, PCR vault, and data vault), mailbox SRAM, SoC interface, and peripherals subsystem. The Watchdog timer and SoC registers run on the gated RDC clock. The RV core implements its own clock gating mechanism. Halting the core automatically turns off its clock.
-
-There are a total of 4 clocks in Caliptra: ungated clock, gated clock, gated RDC clock, and gated SoC IFC clock. The following table shows the different modules and their designated clocks.
-
-| Module | Clock |
-| :-------------------- | :-------------------------------------- |
-| RV core | Clk |
-| SOC IFC | Clk; clk_cg; rdc_clk_cg; soc_ifc_clk_cg |
-| Crypto subsystem | Clk_cg |
-| Vaults | Clk_cg |
-| Peripherals subsystem | Clk_cg |
-| AHB Lite IF, 2to1 Mux | Clk_cg |
-| TRNG | Clk_cg |
-
-#### Wake up conditions
-
-For details on halting the core and waking up the core from the halt state, see section 5 of the [RISC-V VeeR EL2 Programmer's Reference Manual](https://github.com/chipsalliance/Cores-VeeR-EL2/blob/main/docs/RISC-V_VeeR_EL2_PRM.pdf).
-
-When the RV core wakes up, all clocks are enabled. However, when the core is halted, it is possible to wake up Caliptra clocks through:
-
-* A change in generic\_input\_wires
-
-* Cptra\_fatal\_error assertion
-
-* Entry to debug or scan modes
-
-* JTAG accesses
-
-* APB transactions
-
-Activity on the APB interface only wakes up the SoC IFC clock. All other clocks remain off until any other condition is met or the core exits the halt state.
-
-| Cpu_halt_status | PSEL | Generic input wires
\|\| fatal error
\|\| debug/scan mode
\|\|JTAG access | Expected behavior |
-| :-------------- | :--- | :---------- | :-------------- |
-| 0 | X | X | All gated clocks active |
-| 1 | 0 | 0 | All gated clocks inactive |
-| 1 | 0 | 1 | All gated clocks active (as long as condition is true) |
-| 1 | 1 | 0 | Soc_ifc_clk_cg active (as long as PSEL = 1)
All other clks inactive |
-| 1 | 1 | 1 | Soc_ifc_clk_cg active (as long as condition is true OR PSEL = 1)
All other clks active (as long as condition is true) |
-
-#### Usage
-
-The following applies to the clock gating feature:
-
-* The core should only be halted after all pending vault writes are done and cryptographic operations are complete.
-* While the core is halted, any APB transaction wakes up the SoC interface clock and leaves all other clocks disabled. If the core is still halted when the APB transactions are done, the SoC interface clock is returned to a disabled state. .
-* The RDC clock is similar to an ungated clock and is only disabled when a reset event occurs. This avoids metastability on flops. The RDC clock operates independently of core halt status.
-
-
-#### Timing information
-
-The following figure shows the timing information for clock gating.
-
-*Figure 11: Clock gating timing*
-
-## Integrated TRNG
-
-Caliptra implements a true random number generator (TRNG) block for local use models. Firmware is able to read a random number from the TRNG core by accessing its register block over the AHB-lite interface. This is a configuration that SoC integrators enable by defining CALIPTRA\_INTERNAL\_TRNG.
-
-This TRNG block is a combination of entropy source and CSRNG implementations. For information, see the [ENTROPY\_SRC HWIP Technical Specification](https://opentitan.org/book/hw/ip/entropy_src/index.html) and the [CSRNG HWIP Technical Specification](https://opentitan.org/book/hw/ip/csrng/). The core code (see [entropy source](https://github.com/lowRISC/opentitan/tree/master/hw/ip/entropy_src) and [csrng](https://github.com/lowRISC/opentitan/tree/master/hw/ip/csrng)) is reused from here but the interface to the module is changed to AHB-lite. This design provides an interface to an external physical random noise generator. This is also referred to as a physical true random number generator (PTRNG). The PTRNG external source is a physical true random noise source. A noise source and its relation to an entropy source are defined by [SP 800-90B](https://csrc.nist.gov/publications/detail/sp/800-90b/final).
-
-The block is instantiated based on a design parameter chosen at integration time. This is to provide options for SoC to reuse an existing TRNG to build an optimized SoC design. For the optimized scenarios, SoC needs to follow the TODO: heading link in markdown.
-
-The following figure shows the integrated TRNG block.
-
-*Figure 12: Integrated TRNG block*
-
-The following figure shows the CSRNG block.
-
-*Figure 13: CSRNG block*
-
-The following figure shows the entropy source block.
-
-*Figure 14: Entropy source block*
-
-### Operation
-
-Requests for entropy bits start with [command requests](https://opentitan.org/book/hw/ip/csrng/doc/theory_of_operation.html#general-command-format) over the AHB-lite interface to the csrng [CMD\_REQ](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.csrng_reg.CMD_REQ) register.
-
-The following describes the fields of the command request header:
-
-* Application Command: Selects one of five operations to perform. The commands supported are instantiate, reseed, generate, update, and uninstantiate.
-
-* Command Length: Number of 32-bit words that can optionally be appended to the command. A value of zero will only transfer the command header. A value of 4'hc transfers the header plus an additional twelve 32-bit words of data.
-
-* Command Flag0: flag0 is associated with the current command. Setting this field to True (4’h6) enables flag0 to be enabled. Note that flag0 is used for the instantiate and reseed commands only; for all other commands, the flag0 value is ignored.
-
-* Generate Length: Only defined for the generate command, this field is the total number of cryptographic entropy blocks requested. Each unit represents 128 bits of entropy returned. A value of 8 would return a total of 1024 bits. The maximum size supported is 4096.
-
-First an instantiate command is requested over the SW application interface to initialize an instance in the CSRNG module. Depending on the flag0 and clen fields in the command header, a request to the entropy\_src module over the entropy interface is sent to seed the csrng. This can take a few milliseconds if the seed entropy is not immediately available.
-
-Example instantiation:
-
-acmd = 0x1 (Instantiate)
-
-clen/flag0 = The seed behavior is described in the following table.
-
-glen = Not used
-
-| flag0 | clen | Description |
-| :---- | :--- | :----------------------------------------------------------- |
-| F | 0 | Only entropy source seed is used. |
-| F | 1-12 | Entropy source seed is xor'ed with provided additional data. |
-| T | 0 | Seed of zero is used (no entropy source seed used). |
-| T | 1-12 | Only provided additional data is used as seed. |
-
-Next a generate command is used to request generation of cryptographic entropy bits. The glen field defines how many 128 bit words are to be returned to the application interface. After the generated bits are ready, they can be read out via the GENBITS register. This register must be read out glen \* 4 times for each request made.
-
-Example generate command:
-
-acmd = 0x3 (Generate)
-
-clen = 0
-
-flag0 = false (4’h9)
-
-glen = 4 (4 \*128 = 512b)
-
-This requires 16 reads from GENBITS to read out all of the generated entropy.
-
-### Configuration
-
-The HW application interfaces are not supported. Only the SW application interface should be used for this design.
-
-### Physical true random noise source signal descriptions
-
-These are the top level signals defined in caliptra\_top.
-
-| Name | Input or output | Description |
-| :---------- | :-------------- | :------------ |
-| itrng_data | input | Physical true random noise source data |
-| itrng_valid | input | Valid is asserted high for one cycle when data is valid. The expected valid output rate is about 50KHz. |
-
-The following figure shows the top level signals defined in caliptra\_top.
-
-*Figure 15: caliptra\_top signals*
-
-### Entropy source signal descriptions
-
-The following table provides descriptions of the entropy source signals.
-
-| Name | Input or output | Description |
-| :------------------ | :-------------- | :--------------- |
-| clk_i | input | All signal timings are related to the rising edge of clk. |
-| rst_ni | input | The reset signal is active LOW and resets the core. |
-| entropy_src_rng_req | output | Request from the entropy_src module to the physical true random noise source to start generating data. |
-| entropy_src_rng_rsp | input | Contains the internal TRNG data and a flag indicating the data is valid. Valid is asserted high for one cycle when data is valid. |
-| entropy_src_hw_if_i | input | Downstream block request for entropy bits. |
-| entropy_src_hw_if_o | output | 384 bits of entropy data. Valid when es_ack is asserted high. |
-| cs_aes_halt_i | input | Response from csrng that all requests to AES block are halted. |
-| cs_aes_halt_o | output | Request to csrng to halt requests to the AES block for power leveling purposes. |
-
-The following figure shows the entropy source signals.
-
-*Figure 16: Entropy source signals*
-
-### CSRNG signal descriptions
-
-The following table provides descriptions for the CSRNG signals.
-
-| Name | Input or output | Description |
-| :------------------------- | :-------------- | :---------------------------------------------------------------------------------------------------- |
-| clk_i | input | All signal timings are related to the rising edge of clk. |
-| rst_ni | input | The reset signal is active LOW and resets the core. |
-| otp_en_csrng_sw_app_read_i | input | Enable firmware to access the ctr_drbg internal state and genbits through registers. |
-| lc_hw_debug_en_i | input | Lifecycle that selects which diversification value is used for xoring with the seed from entropy_src. |
-| entropy_src_hw_if_i | input | 384 bits of entropy data. Valid when es_ack is asserted high. |
-| entropy_src_hw_if_o | output | Downstream block request for entropy bits. |
-| cs_aes_halt_i | input | Request from entropy_src to halt requests to the AES block for power leveling purposes. |
-| cs_aes_halt_o | output | Response to entropy_src that all requests to AES block are halted. |
-
-The CSRNG may only be enabled if entropy\_src is enabled. After it is disabled, CSRNG may only be re-enabled after entropy\_src has been disabled and re-enabled.
-
-## External-TRNG REQ HW API
-
-For SoCs that choose to not instantiate Caliptra’s integrated TRNG, Caliptra provides a TRNGREQ HW API.
-
-1. Caliptra asserts TRNG\_REQ wire (FW made the request for a TRNG).
-2. SoC writes the TRNG architectural registers.
-3. SoC writes a done bit in the TRNG architectural registers.
-4. Caliptra desserts TRNG\_REQ.
-
-The reason to have a separate interface from the SoC mailbox is to ensure that this request is not intercepted by any SoC FW agents that communicate with the SoC mailbox. It is required for FIPS compliance that this TRNG HW API is always handled by a SoC HW gasket logic and not handled by SoC ROM/FW code.
-
-## SoC-SHA accelerator HW API
-
-Caliptra provides a SHA accelerator HW API for SoC and Caliptra internal FW to use. It is atomic in nature in that only one of them can use the SHA accelerator HW API at the same time. Details of the SHA accelerator register block may be found in the GitHub repository in [documentation](https://chipsalliance.github.io/caliptra-rtl/main/external-regs/?p=caliptra_top_reg.sha512_acc_csr) generated from the register definition file.
-
-Using the HW API:
-
-* A user of the HW API first locks the accelerator by reading the LOCK register. A read that returns the value 0 indicates that the resource was locked for exclusive use by the requesting user. A write of ‘1 clears the lock.
-* The USER register captures the APB pauser value of the requestor that locked the SHA accelerator. This is the only user that is allowed to control the SHA accelerator by performing APB register writes. Writes by any other agent on the APB interface are dropped.
-* MODE register is written to set the SHA execution mode.
- * SHA accelerator supports both SHA384 and SHA512 modes of operation.
- * SHA supports **streaming** mode: SHA is computed on a stream of incoming data to the DATAIN register. The EXECUTE register, when set, indicates to the accelerator that streaming is complete. The accelerator can then publish the result into the DIGEST register. When the VALID bit of the STATUS register is set, then the result in the DIGEST register is valid.
- * SHA supports **Mailbox** mode: SHA is computed on LENGTH (DLEN) bytes of data stored in the mailbox beginning at START\_ADDRESS. This computation is performed when the EXECUTE register is set by the user. When the operation is completed and the result in the DIGEST register is valid, SHA accelerator sets the VALID bit of the STATUS register.
- * The SHA computation engine in the SHA accelerator requires big endian data, but the SHA accelerator can accommodate mailbox input data in either the little endian or big endian format. By default, input data is assumed to be little endian and is swizzled to big endian at the byte level prior to computation. For the big endian format, data is loaded into the SHA engine as-is. Users may configure the SHA accelerator to treat data as big endian by setting the ENDIAN\_TOGGLE bit appropriately.
- * See the register definition for the encodings.
-* SHA engine also provides a ‘zeroize’ function through its CONTROL register to clear any of the SHA internal state. This can be used when the user wants to conceal previous state for debug or security reasons.
-
-## JTAG implementation
-
-For specific debug flows, see the [JTAG/TAP Debug](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html#jtagtap-debug) section in Caliptra: A Datacenter System on a Chip (SoC) Root of Trust (RoT).
-
-The following figure shows the JTAG implementation within the Caliptra boundary. The output of the existing DMI wrapper is used to find the non-Core (Caliptra uncore) aperture to route the JTAG commands.
-
-Caliptra’s JTAG/TAP should be implemented as a TAP EP. JTAG is open if the debug mode is set at the time of Caliptra reset deassertion.
-
-Note: If the debug security state switches to debug mode anytime, the security assets and keys are still flushed even though JTAG is not open.
-
-*Figure 17: JTAG implementation*
-
-# Cryptographic subsystem architecture
-
-The architecture of Caliptra cryptographic subsystem includes the following components:
-
-* Symmetric cryptographic primitives
- * De-obfuscation engine
- * SHA512/384 (based on NIST FIPS 180-4 [2])
- * SHA256 (based on NIST FIPS 180-4 [2])
- * HMAC384 (based on [NIST FIPS 198-1](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf) [5] and [RFC 4868](https://tools.ietf.org/html/rfc4868) [6])
-* Public-key cryptography
- * NIST Secp384r1 Deterministic Digital Signature Algorithm (based on FIPS-186-4 [11] and RFC 6979 [7])
-* Key vault
- * Key slots
- * Key slot management
-
-The high-level architecture of Caliptra cryptographic subsystem is shown in the following figure.
-
-*Figure 18: Caliptra cryptographic subsystem TODO: fix this image*
-
-## SHA512/SHA384
-
-SHA512 is a function of cryptographic hash algorithm SHA-2. The hardware implementation is based on [Secworks/SHA512](https://github.com/secworks/sha512) [1]. This implementation complies with the functionality in NIST FIPS 180-4 [2]. The implementation supports the SHA512 variants SHA-512/224, SHA-512/256, SHA384 and SHA512.
-
-The SHA512 algorithm is described as follows:
-
-* The message is padded by the host and broken into 1024-bit chunks
-* For each chunk:
- * The message is fed to the SHA512 core
- * The core should be triggered by the host
- * The SHA512 core status is changed to ready after hash processing
-* The result digest can be read after feeding all message chunks
-
-### Operation
-
-#### Padding
-
-The message should be padded before feeding to the hash core. The input message is taken, and some padding bits are appended to it to get it to the desired length. The bits that are used for padding are simply ‘0’ bits with a leading ‘1’ (100000…000). The appended length of the message (before pre-processing), in bits, is a 128-bit big-endian integer.
-
-The total size should be equal to 128 bits short of a multiple of 1024 since the goal is to have the formatted message size as a multiple of 1024 bits (N x 1024). The following figure shows the SHA512 input formatting.
-
-*Figure 19: SHA512 input formatting*
-
-#### Hashing
-
-The SHA512 core performs 80 iterative operations to process the hash value of the given message. The algorithm processes each block of 1024 bits from the message using the result from the previous block. For the first block, the initial vectors (IV) are used for starting the chain processing of each 1024-bit block.
-
-### FSM
-
-The SHA512 architecture has the finite-state machine as shown in the following figure.
-
-*Figure 20: SHA512 FSM*
-
-### Signal descriptions
-
-The SHA512 architecture inputs and outputs are described in the following table.
-
-| Name | Inputs and outputs | Description |
-|-----------------|--------------------|---------------------------------------------------------------------------------------------------|
-| clk | input | All signal timings are related to the rising edge of clk. |
-| reset_n | input | The reset signal is active LOW and resets the core. This is the only active LOW signal. |
-| init | input | The core is initialized and processes the first block of message. |
-| next | input | The core processes the rest of the message blocks using the result from the previous blocks. |
-| mode\[1:0\] | input | Indicates the hash type of the function. This can be:
- SHA512/224
- SHA512/256
- SHA384
- SHA512 |
-| zeroize | input | The core clears all internal registers to avoid any SCA information leakage. |
-| block\[1023:0\] | input | The input padded block of message. |
-| ready | output | When HIGH, the signal indicates the core is ready. |
-| digest\[511:0\] | output | The hashed value of the given block. |
-| digest_valid | output | When HIGH, the signal indicates that the result is ready. |
-
-### Address map
-
-The SHA512 address map is shown here: [sha512\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.sha512_reg)
-
-### Pseudocode
-
-The following pseudocode demonstrates how the SHA512 interface can be implemented.
-
-*Figure 21: SHA512 pseudocode*
-
-### SCA countermeasure
-
-We do not propose any countermeasure to protect the hash functions. Inherently, hash functions do not work like other cryptographic engines. Hash functions target integrity without requiring a secret key. Hence, the attacker can target only messages. Also, the attacker cannot build a CPA or DPA platform on the hash function because the same message ideally gives the same side-channel behavior.
-
-If the attacker works on the multi-message mechanism, the attacker then needs to work with single trace attacks, which are very unlikely in ASIC/FPGA implementations. Also, our hash implementation is a noisy platform. As a result, we do not propose any SCA implementation countermeasure on the hash functions.
-
-### Performance
-
-The SHA512 core performance is reported considering two different architectures: pure hardware architecture, and hardware/software architecture. These are described next.
-
-#### Pure hardware architecture
-
-In this architecture, the SHA512 interface and controller are implemented in hardware. The performance specification of the SHA512 architecture is shown in the following table.
-
-| Operation | Cycle count \[CCs\] | Time \[us\] @ 400 MHz | Throughput \[op/s\] |
-| :-------------------- | :------------------ | :-------------------- | :------------------ |
-| Data_In transmission | | 0.08 | |
-| Process | 87 | 0.22 | |
-| Data_Out transmission | 16 | 0.04 | |
-| Single block | 136 | 0.34 | 2,941,176 |
-| Double block | 224 | 0.56 | 1,785,714 |
-| 1 KiB message | 840 | 2.10 | 476,190 |
-| 128 KiB message | 17,632 | 44.08 | 22,686 |
-
-#### Hardware/software architecture
-
-In this architecture, the SHA512 interface and controller are implemented in RISC-V core. The performance specification of the SHA512 architecture is shown in the following table.
-
-| Operation | Cycle count \[CCs\] | Time \[us\]\] @ 400 MHz | Throughput \[op/s\] |
-| :-------------------- | :------------------ | :---------------------- | :------------------ |
-| Data_In transmission | 990 | 2.48 | |
-| Process | 139 | 0.35 | |
-| Data_Out transmission | 387 | 0.97 | |
-| Single block | 1,516 | 3.79 | 263,852 |
-| Double block | 2,506 | 6.27 | 159,617 |
-| 1 KiB message | 9,436 | 23.59 | 42,391 |
-| 128 KiB message | 1,015,276 | 2,538.19 | 394 |
-
-#### Pure software architecture
-
-In this architecture, the SHA512 algorithm is implemented fully in software. The implementation is derived from the [OpenSSL](https://www.openssl.org/docs/man3.0/man3/SHA512.html) SHA512 implementation [3]. The performance numbers for this architecture are shown in the following table.
-
-| Data size | Cycle count |
-| :------------ | :-------------- |
-| 1 KiB | 147,002 |
-| 4 KiB | 532,615 |
-| 8 KiB | 1,046,727 |
-| 12 KiB | 1,560,839 |
-| 128 KiB | 16,470,055 |
-
-## SHA256
-
-SHA256 is a function of the SHA-2 cryptographic hash algorithm. The hardware implementation is based on [Secworks/SHA256](https://github.com/secworks/sha256) [1]. The implementation supports the two variants: SHA256/224 and SHA256.
-
-The SHA256 algorithm is described as follows:
-
-* The message is padded by the host and broken into 512-bit chunks
-* For each chunk:
- * The message is fed to the sha256 core
- * The core should be triggered by the host
- * The sha256 core status is changed to ready after hash processing
-* The result digest can be read after feeding all message chunks
-
-
-### Operation
-
-#### Padding
-
-The message should be padded before feeding to the hash core. The input message is taken, and some padding bits are appended to the message to get it to the desired length. The bits that are used for padding are simply ‘0’ bits with a leading ‘1’ (100000…000). The appended length of the message (before pre-processing), in bits, is a 64-bit big-endian integer.
-
-The total size should be equal to 64 bits, short of a multiple of 512 because the goal is to have the formatted message size as a multiple of 512 bits (N x 512).
-
-The following figure shows SHA256 input formatting.
-
-*Figure 22: SHA256 input formatting*
-
-#### Hashing
-
-The SHA256 core performs 64 iterative operations to process the hash value of the given message. The algorithm processes each block of 512 bits from the message using the result from the previous block. For the first block, the initial vectors (IV) are used to start the chain processing of each 512-bit block.
-
-### FSM
-
-The SHA256 architecture has the finite-state machine as shown in the following figure.
-
-*Figure 23: SHA256 FSM*
-
-### Signal descriptions
-
-The SHA256 architecture inputs and outputs are described as follows.
-
-| Name | Input or output | Description |
-| :-------------- | :-------------- | :------------------------------------------------------------------------------------------- |
-| clk | input | All signal timings are related to the rising edge of clk. |
-| reset_n | input | The reset signal is active LOW and resets the core. This is the only active LOW signal. |
-| init | input | The core is initialized and processes the first block of message. |
-| next | input | The core processes the rest of the message blocks using the result from the previous blocks. |
-| mode | input | Indicates the hash type of the function. This can be:
- SHA256/224
- SHA256 |
-| zeroize | input | The core clears all internal registers to avoid any SCA information leakage. |
-| block\[511:0\] | input | The input padded block of message. |
-| ready | output | When HIGH, the signal indicates the core is ready. |
-| digest\[255:0\] | output | The hashed value of the given block. |
-| digest_valid | output | When HIGH, the signal indicates the result is ready. |
-
-### Address map
-
-The SHA256 address map is shown here: [sha256\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.sha256_reg).
-
-### Pseudocode
-
-The following pseudocode demonstrates how the SHA256 interface can be implemented.
-
-*Figure 24: SHA256 pseudocode*
-
-### SCA countermeasure
-
-We do not propose any countermeasure to protect the hash functions. For more information, see SCA countermeasure in the [SHA512/SHA384](#sha512sha384) section.
-
-### Performance
-
-The SHA256 core performance is reported considering two different architectures: pure hardware architecture, and hardware/software architecture. These are described next.
-
-#### Pure hardware architecture
-
-In this architecture, the SHA256 interface and controller are implemented in hardware. The performance specification of the SHA256 architecture is reported as shown in the following table.
-
-| Operation | Cycle count \[CCs\] | Time \[us\] @ 400 MHz | Throughput \[op/s\] |
-| :-------------------- | :------------------ | :-------------------- | :------------------ |
-| Data_In transmission | 17 | 0.04 | |
-| Process | 66 | 0.17 | |
-| Data_Out transmission | 8 | 0.02 | |
-| Single block | 91 | 0.23 | 4,395,604 |
-| Double block | 158 | 0.40 | 2,531,646 |
-| 1 KiB message | 1163 | 2.91 | 343,938 |
-
-#### Hardware/software architecture
-
-In this architecture, the SHA256 interface and controller are implemented in RISC-V core. The performance specification of the SHA256 architecture is reported as shown in the following table.
-
-| Operation | Cycle count \[CCs\] | Time \[us\] @ 400 MHz | Throughput \[op/s\] |
-| :-------------------- | :------------------ | :-------------------- | :------------------ |
-| Data_In transmission | 500 | 1.25 | |
-| Process | 66 | 0.17 | |
-| Data_Out transmission | 195 | 0.49 | |
-| Single block | 761 | 1.90 | 525,624 |
-| Double block | 1355 | 3.39 | 295,203 |
-| 1 KiB message | 8761 | 21.90 | 45,657 |
-
-## HMAC384
-
-Hash-based message authentication code (HMAC) is a cryptographic authentication technique that uses a hash function and a secret key. HMAC involves a cryptographic hash function and a secret cryptographic key. This implementation supports HMAC-SHA-384-192 as specified in [NIST FIPS 198-1](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf) [5]. The implementation is compatible with the HMAC-SHA-384-192 authentication and integrity functions defined in [RFC 4868](https://tools.ietf.org/html/rfc4868) [6].
-
-Caliptra HMAC implementation uses SHA384 as the hash function, accepts a 384-bit key, and generates a 384-bit tag.
-
-The implementation also supports PRF-HMAC-SHA-384. The PRF-HMAC-SHA-384 algorithm is identical to HMAC-SHA-384-192, except that variable-length keys are permitted, and the truncation step is not performed.
-
-The HMAC algorithm is described as follows:
-* The key is fed to the HMAC core to be padded
-* The message is broken into 1024-bit chunks by the host
-* For each chunk:
- * The message is fed to the HMAC core
- * The HMAC core should be triggered by the host
- * The HMAC core status is changed to ready after hash processing
-* The result digest can be read after feeding all message chunks
-
-
-### Operation
-
-#### Padding
-
-The message should be padded before feeding to the HMAC core. Internally, the i\_padded key is concatenated with the message. The input message is taken, and some padding bits are appended to the message to get it to the desired length. The bits that are used for padding are simply ‘0’ bits with a leading ‘1’ (100000…000).
-
-The total size should be equal to 128 bits, short of a multiple of 1024 because the goal is to have the formatted message size as a multiple of 1024 bits (N x 1024).
-
-*Figure 25: HMAC input formatting*
-
-The following figures show examples of input formatting for different message lengths.
-
-*Figure 26: Message length of 1023 bits*
-
-When the message is 1023 bits long, padding is given in the next block along with message size.
-
-*Figure 27: 1 bit padding*
-
-When the message size is 895 bits, a padding of ‘1’ is also considered valid, followed by the message size.
-
-*Figure 28: Multi block message*
-
-Messages with a length greater than 1024 bits are broken down into N 1024-bit blocks. The last block contains padding and the size of the message.
-
-
-#### Hashing
-
-The HMAC core performs the sha2-384 function to process the hash value of the given message. The algorithm processes each block of the 1024 bits from the message, using the result from the previous block. This data flow is shown in the following figure.
-
-*Figure 29: HMAC-SHA-384-192 data flow*
-
-### FSM
-
-The HMAC architecture has the finite-state machine as shown in the following figure.
-
-*Figure 30: HMAC FSM*
-
-### Signal descriptions
-
-The HMAC architecture inputs and outputs are described in the following table.
-
-| Name | Input or output | Description |
-| :----------------- | :-------------- | :----------- |
-| clk | input | All signal timings are related to the rising edge of clk. |
-| reset_n | input | The reset signal is active LOW and resets the core. This is the only active LOW signal. |
-| init | input | The core is initialized and processes the key and the first block of the message. |
-| next | input | The core processes the rest of the message blocks using the result from the previous blocks. |
-| zeroize | input | The core clears all internal registers to avoid any SCA information leakage. |
-| key\[383:0\] | input | The input key. |
-| block\[1023:0\] | input | The input padded block of message. |
-| LFSR_seed\[159:0\] | Input | The input to seed PRNG to enable the masking countermeasure for SCA protection. |
-| ready | output | When HIGH, the signal indicates the core is ready. |
-| tag\[383:0\] | output | The HMAC value of the given key or block. For PRF-HMAC-SHA-384, a 384-bit tag is required. For HMAC-SHA-384-192, the host is responsible for reading 192 bits from the MSB. |
-| tag_valid | output | When HIGH, the signal indicates the result is ready. |
-
-### Address map
-
-The HMAC address map is shown here: [hmac\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.hmac_reg).
-
-### Pseudocode
-
-The following pseudocode demonstrates how the HMAC interface can be implemented.
-
-*Figure 31: HMAC pseudocode*
-
-### SCA countermeasure
-
-In an attack model, an attacker can form hypotheses about the secret key value and compute the corresponding output values by using the Hamming Distance model as an appropriate leakage model. An attacker who has knowledge of the implementation for open-source architecture has an advantage. The attacker can capture the power consumption traces to verify their hypotheses, by partitioning the acquisitions or using Pearson’s correlation coefficient.
-
-To protect the HMAC algorithm from side-channel attacks, a masking countermeasure is applied. This means that random values are added to the intermediate variables during the algorithm’s execution, so that the side-channel signals do not reveal any information about them.
-
-The embedded countermeasures are based on "Differential Power Analysis of HMAC Based on SHA-2, and Countermeasures" by McEvoy et. al. To provide the required random values for masking intermediate values, a lightweight 74-bit LFSR is implemented. Based on “Spin Me Right Round Rotational Symmetry for FPGA-specific AES” by Wegener et. al., LFSR is sufficient for masking statistical randomness.
-
-Each round of SHA512 execution needs 6,432 random bits, while one HMAC operation needs at least 4 rounds of SHA512 operations. However, the proposed architecture requires only 160-bit LFSR seed and provides first-order DPA attack protection at the cost of 10% latency overhead with negligible hardware resource overhead.
-
-### Performance
-
-The HMAC core performance is reported considering two different architectures: pure hardware architecture, and hardware/software architecture. These are described next.
-
-#### Pure hardware architecture
-
-In this architecture, the HMAC interface and controller are implemented in hardware. The performance specification of the HMAC architecture is reported as shown in the following table.
-
-| Operation | Cycle count \[CCs\] | Time \[us\] @ 400 MHz | Throughput \[op/s\] |
-| :-------------------- | :------------------ | :-------------------- | :------------------ |
-| Data_In transmission | 44 | 0.11 | - |
-| Process | 254 | 0.635 | - |
-| Data_Out transmission | 12 | 0.03 | - |
-| Single block | 310 | 0.775 | 1,290,322 |
-| Double block | 513 | 1.282 | 780,031 |
-| 1 KiB message | 1,731 | 4.327 | 231,107 |
-| 128 KiB message | 207,979 | 519.947 | 1,923 |
-
-#### Hardware/software architecture
-
-In this architecture, the HMAC interface and controller are implemented in RISC-V core. The performance specification of the HMAC architecture is reported as shown in the following table.
-
-| Operation | Cycle count \[CCs\] | Time \[us\] @ 400 MHz | Throughput \[op/s\] |
-| :-------------------- | :------------------ | :-------------------- | :------------------ |
-| Data_In transmission | 1389 | 3.473 | - |
-| Process | 253 | 0.633 | - |
-| Data_Out transmission | 290 | 0.725 | - |
-| Single block | 1932 | 4.83 | 207,039 |
-| Double block | 3166 | 7.915 | 136,342 |
-| 1 KiB message | 10,570 | 26.425 | 37,842 |
-| 128 KiB message | 1,264,314 | 3,160.785 | 316 |
-
-## HMAC_DRBG
-
-Hash-based message authentication code (HMAC) deterministic random bit generator (DRBG) is a cryptographic random bit generator that uses a HMAC function. HMAC_DRBG involves a cryptographic HMAC function and a seed. This architecture is designed as specified in section 10.1.2. of NIST SP 800-90A [12]. For ECC signing operation, the implementation is compatible with section 3.1. of RFC 6979 [7].
-
-Caliptra HMAC_DRBG implementation uses HMAC384 as the HMAC function, accepts a 384-bit seed, and generates a 384-bit random value.
-
-The HMAC algorithm is described as follows:
-
-* The seed is fed to HMAC_DRBG core by the host
-* For each 384-bit random value
- * The core should be triggered by the host
- * The HMAC_DRBG core status is changed to ready after HMAC processing
- * The result digest can be read
-
-
-### Operation
-
-HMAC_DRBG uses a loop of HMAC(K, V) to generate the random bits. In this algorithm, two constant values of K_init and V_init are used as follows:
-
- 1. Set V_init = 0x01 0x01 0x01 ... 0x01 (V has 384-bit)
- 2. Set K_init = 0x00 0x00 0x00 ... 0x00 (K has 384-bit)
- 3. K_tmp = HMAC(K_init, V_init || 0x00 || entropy || nonce)
- 4. V_tmp = HMAC(K_tmp, V_init)
- 5. K_new = HMAC(K_tmp, V_tmp || 0x01 || entropy || nonce)
- 6. V_new = HMAC(K_new, V_tmp)
- 7. Set T = []
- 8. T = T || HMAC(K_new, V_new)
- 9. Return T if T is within the [1,q-1] range, otherwise:
- 10. K_new = HMAC(K_new, V_new || 0x00)
- 11. V_new = HMAC(K_new, V_new)
- 12. Jump to 8
-
-For ECC KeyGen operation, HMAC_DRBG is used to generate privkey as follows:
-
- Privkey = HMAC_DRBG(seed, nonce)
-
-For ECC SIGNING operation, HMAC_DRBG is used to generate k as follows:
-
- K = HMAC_DRBG(privkey, hashed_msg)
-
-### Signal descriptions
-
-The HMAC_DRBG architecture inputs and outputs are described in the following table.
-
-| Name | Input or output | Description |
-| :------------------- | :-------------- | :-------------------------------------------------------------------------------------- |
-| clk | input | All signal timings are related to the rising edge of clk. |
-| reset_n | input | The reset signal is active LOW and resets the core. This is the only active LOW signal. |
-| init | input | The core is initialized with the given seed and generates a 384-bit random value. |
-| next | input | The core generates a new 384-bit random value using the result from the previous run. |
-| zeroize | input | The core clears all internal registers to avoid any SCA information leakage. |
-| entropy \[383:0\] | input | The input entropy. |
-| nonce \[383:0\] | input | The input nonce. |
-| LFSR_seed \[147 :0\] | input | The input to seed PRNG to enable masking countermeasure for SCA protection. |
-| ready | output | When HIGH, the signal indicates the core is ready. |
-| drbg \[383:0\] | output | The hmac_drbg value of the given inputs. |
-| valid | output | When HIGH, the signal indicates the result is ready. |
-
-### Address map
-
-The HMAC_DRBG is embedded into ECC architecture, since there is no address map to access it from FW.
-
-### SCA countermeasure
-
-For information, see SCA countermeasure in the [HMAC384](#hmac384) section.
-
-## ECC
-
-The ECC unit includes the ECDSA (Elliptic Curve Digital Signature Algorithm) engine, offering a variant of the cryptographically secure Digital Signature Algorithm (DSA), which uses elliptic curve (ECC). A digital signature is an authentication method in which a public key pair and a digital certificate are used as a signature to verify the identity of a recipient or sender of information.
-
-The hardware implementation supports deterministic ECDSA, 384 Bits (Prime Field), also known as NIST-Secp384r1, described in RFC6979.
-
-Secp384r1 parameters are shown in the following figure.
-
-*Figure 32: Secp384r1 parameters*
-
-### Operation
-
-The ECDSA consists of three operations, shown in the following figure.
-
-*Figure 33: ECDSA operations*
-
-#### KeyGen
-
-In the deterministic key generation, the paired key of (privKey, pubKey) is generated by KeyGen(seed, nonce), taking a deterministic seed and nonce. The KeyGen algorithm is as follows:
-
-* Compute privKey = HMAC_DRBG(seed, nonce) to generate a random integer in the interval [1, n-1] where n is the group order of Secp384 curve.
-* Generate pubKey(x,y) as a point on ECC calculated by pubKey=privKey × G, while G is the generator point over the curve.
-
-
-#### Signing
-
-In the signing algorithm, a signature (r, s) is generated by Sign(privKey, h), taking a privKey and hash of message m, h = hash(m), using a cryptographic hash function, SHA384. The signing algorithm includes:
-
-* Generate a random number k in the range [1..n-1], while k = HMAC\_DRBG(privKey, h)
-* Calculate the random point R = k × G
-* Take r = Rx mod n, where Rx is x coordinate of R=(Rx, Ry)
-* Calculate the signature proof: s = k-1 × (h + r × privKey) mod n
-* Return the signature (r, s), each in the range [1..n-1]
-
-#### Verifying
-
-The signature (r, s) can be verified by Verify(pubKey ,h ,r, s) considering the public key pubKey and hash of message m, h=hash(m) using the same cryptographic hash function SHA384. The output is r’ value of verifying a signature. The ECDSA verify algorithm includes:
-
-* Calculate s1 = s−1 mod n
-* Compute R' = (h × s1) × G + (r × s1) × pubKey
-* Take r’ = R'x mod n, while R'x is x coordinate of R’=(R'x, R'y)
-* Verify the signature by comparing whether r' == r
-
-### Architecture
-
-The ECC top-level architecture is shown in the following figure.
-
-*Figure 34: ECDSA architecture*
-
-### Signal descriptions
-
-The ECDSA architecture inputs and outputs are described in the following table.
-
-
-| Name | Input or output | Description |
-| :------------------------- | :-------------- | :----------- |
-| clk | input | All signal timings are related to the rising edge of clk. |
-| reset_n | input | The reset signal is active LOW and resets the core. This is the only active LOW signal. |
-| ctrl\[1:0\] | input | Indicates the AES type of the function. This can be:
− 0b00: No Operation
− 0b01: KeyGen
− 0b10: Signing
− 0b11: Verifying |
-| zeroize | input | The core clears all internal registers to avoid any SCA information leakage. |
-| seed \[383:0\] | input | The deterministic seed for HMAC_DRBG in the KeyGen operation. |
-| nonce \[383:0\] | input | The deterministic nonce for HMAC_DRBG in the KeyGen operation. |
-| privKey_in\[383:0\] | input | The input private key used in the signing operation. |
-| pubKey_in\[1:0\]\[383:0\] | input | The input public key(x,y) used in the verifying operation. |
-| hashed_msg\[383:0\] | input | The hash of message using SHA384. |
-| ready | output | When HIGH, the signal indicates the core is ready. |
-| privKey_out\[383:0\] | output | The generated private key in the KeyGen operation. |
-| pubKey_out\[1:0\]\[383:0\] | output | The generated public key(x,y) in the KeyGen operation. |
-| r\[383:0\] | output | The signature value of the given priveKey/message. |
-| s\[383:0\] | output | The signature value of the given priveKey/message. |
-| r’\[383:0\] | Output | The signature verification result. |
-| valid | output | When HIGH, the signal indicates the result is ready. |
-
-### Address map
-
-The ECDSA address map is shown here: [ecc\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.ecc_reg).
-
-### Pseudocode
-
-The following pseudocode blocks demonstrate example implementations for KeyGen, Signing, and Verifying.
-
-#### KeyGen
-
-*Figure 35: KeyGen pseudocode*
-
-#### Signing
-
-*Figure 36: Signing pseudocode*
-
-#### Verifying
-
-*Figure 37: Verifying pseudocode*
-
-### SCA countermeasure
-
-The described ECDSA has three main routines: KeyGen, Signing, and Verifying. Since the Verifying routine requires operation with public values rather than a secret value, our side-channel analysis does not cover this routine. Our evaluation covers the KeyGen and Signing routines where the secret values are processed.
-
-KeyGen consists of HMAC DRBG and scalar multiplication, while Signing first requires a message hashing and then follows the same operations as KeyGen (HMAC DRBG and scalar multiplication). The last step of Signing is generating “S” as the proof of signature. Since HMAC DRBG and hash operations are evaluated separately in our document, this evaluation covers scalar multiplication and modular arithmetic operations.
-
-#### Scalar multiplication
-
-To perform the scalar multiplication, the Montgomery ladder is implemented, which is inherently resistant to timing and single power analysis (SPA) attacks.
-
-Implementation of complete unified addition formula for the scalar multiplication avoids information leakage and enhances architecture from security and mathematical perspectives.
-
-To protect the architecture against horizontal power/electromagnetic (EM) and differential power analysis (DPA) attacks, several countermeasures are embedded in the design [9]. Since these countermeasures require random inputs, HMAC-DRBG is fed by IV to generate these random values.
-
-Since HMAC-DRBG generates random value in a deterministic way, firmware MUST feed different IV to ECC engine for EACH keygen and signing operation.
-
-#### Base point randomization
-
-This countermeasure is achieved using the randomized base point in projective coordinates. Hence, the base point G=(Gx, Gy) in affine coordinates is transformed and randomized to projective coordinates as (X, Y, Z) using a random value as follows:
-
-This approach does not have the performance or area overhead because the architecture is variable-base-point implemented.
-
-#### Scalar blinding
-
-This countermeasure is achieved by randomizing the scalar as follows:
-
-Based on [10], half of the bit size of is required to prevent advanced DPA attacks. Therefore, has 192 bits, and the blinded scalar has 576 bits. Hence, this countermeasure extends the Montgomery ladder iterations due to extended scalar.
-
-This approach is achieved at the cost of 50% more latency on scalar multiplication and adding one lightweight block, including one 32\*32 multiplier and an accumulator.
-
-Note: the length of rand is configurable to have a trade-off between the required protection and performance.
-
-#### Making countermeasures embedded into HMAC\_DRBG
-
-In the first step of the KeyGen operation, the privkey is generated using HMAC\_DRBG by feeding the following two inputs: seed and nonce. To avoid SCA information leakage during this operation, we embed masking countermeasures into the HMAC\_DRBG architecture.
-
-Each round of SHA512 execution needs 6,432 random bits, and one HMAC operation needs at least 4 rounds of SHA512 operations. Furthermore, each HMAC\_DRBG round needs at least 5 rounds of HMAC operations. However, the proposed architecture uses a lightweight LFSR and provides first-order DPA attack protection with negligible latency and hardware resource overhead.
-
-#### ECDSA signing nonce leakage
-
-Generating “S” as the proof of signature at the steps of the signing operation leaks where the hashed message is signed with private key and ephemeral key as follows:
-
-Since the given message is known or the signature part r is known, the attacker can perform a known-plaintext attack. The attacker can sign multiple messages with the same key, or the attacker can observe part of the signature that is generated with multiple messages but the same key.
-
-The evaluation shows that the CPA attack can be performed with a small number of traces, respectively. Thus, an arithmetic masked design for these operations is implemented.
-
-##### Masking signature
-
-This countermeasure is achieved by randomizing the privkey as follows:
-
-Although computation of “S” seems the most vulnerable point in our scheme, the operation does not have a big contribution to overall latency. Hence, masking these operations has low overhead on the cost of the design.
-
-#### Random number generator for SCA countermeasure
-
-The ECC countermeasure requires several random vectors to randomize the intermediate values, as described in the preceding section. HMAC\_DRBG is used to take one random vector of 384-bit (i.e., ECC\_IV register) and to generate the required random vectors for different countermeasures.
-
-The state machine of HMAC\_DRBG utilization is shown in the following figure, including three main states:
-
-1. SCA random generator: Running HMAC\_DRBG with IV and an internal counter to generate the required random vectors.
-2. KEYGEN PRIVKEY: Running HMAC\_DRBG with seed and nonce to generate the privkey in KEYGEN operation.
-3. SIGNING NONCE: Running HMAC\_DRBG based on RFC6979 in SIGNING operation with privkey and hashed\_msg.
-
-*Figure 38: HMAC\_DRBG utilization*
-
-In SCA random generator state:
-
-* This state (in KeyGen operation mode) generates 3 384-bit random vectors for the following: LFSR, base point randomization, and scalar blinding randomization.
-* This state (in signing operation) generates 4 384-bit random vectors for the following: LFSR, base point randomization, scalar blinding, and masking signature randomization.
-* HMAC\_DRBG is initialized with IV and an internal counter. This 64-bit counter enables after reset and zeroization and contains different values depending on when ECC is called.
-* HMAC\_DRBG is enabled by the INIT command. To generate all required vectors, HMAC-DRBG is continued by the NEXT command that increments the built-in counter inside the HMAC-DRBG unit.
-* To initialize the required seed for LFSR, LFSR\_INIT\_SEED is set as a constant by RTL after reset and zeroization. However, this value is updated before enabling HMAC\_DRBG as follows:
- * In the first execution of HMAC\_DRBG after reset and zeroization, hmac\_lfsr\_seed is equal to LFSR\_INIT\_SEED XORed by internal 64-bit counter.
- * In the next executions of HMAC\_DRBG, hmac\_lfsr\_seed is equal to HMAC\_DRBG output of the first execution XORed by internal 64-bit counter.
-
-The data flow of the HMAC\_DRBG operation in keygen operation mode is shown in the following figure.
-
-*Figure 39: HMAC\_DRBG data flow*
-
-#### TVLA results
-
-Test vector leakage assessment (TVLA) provides a robust test using a 𝑡-test. This test evaluates the differences between sets of acquisitions to determine if one set of measurement can be distinguished from the other. This technique can detect different types of leakages, providing a clear indication of leakage or lack thereof.
-
-In practice, observing a t-value greater than a specific threshold (mainly 4.5) indicates the presence of leakage. However, in ECC, due to its latency, around 5 million samples are required to be captured. This latency leads to many false positives and the TVLA threshold can be considered a higher value than 4.5. Based on the following figure from “Side-Channel Analysis and Countermeasure Design for Implementation of Curve448 on Cortex-M4” by Bisheh-Niasar et. al., the threshold can be considered equal to 7 in our case.
-
-*Figure 40: TVLA threshold as a function of the number of samples per trace*
-
-##### Keygen TVLA
-
-TODO: provide content for this section
-
-
-##### Signing TVLA
-
-The TVLA results for performing privkey-dependent leakage detection using 20,000 traces is shown in the following figure. Based on this figure, there is no leakage in ECC signing by changing the privkey after 20,000 operations.
-
-*Figure 41: privkey-dependent leakage detection using TVLA for ECC signing after 20,000 traces*
-
-The TVLA results for performing message-dependent leakage detection using 64,000 traces is shown in the following figure. Based on this figure, there is no leakage in ECC signing by changing the message after 64,000 operations.
-
-*Figure 42: Message-dependent leakage detection using TVLA for ECC signing after 64,000 traces*
-
-The point with t-value equal to -40 is mapped to the Montgomery conversion of the message that is a publicly known value (no secret is there). By ignoring those corresponding samples, there are some sparse samples with a t-value greater than 7, as shown in the following table.
-
-| Sample | Duration | Cycle | t-value | Operation |
-| :-------- | :--------- | :-------- | :------ | :---------------------- |
-| 4,746,127 | 214 | 911,381.4 | 11.2 | start of mont_conv(msg) |
-| 4,746,341 | | 911,422.5 | -40 | end of mont_conv(msg) |
-| 4,757,797 | 1 | 913,622.0 | 7.4 | inv_q |
-| 4,768,302 | 1 | 915,639.0 | 7.8 | inv_q |
-| 4,779,610 | 1 | 917,810.1 | -9.1 | inv_q |
-| 4,788,120 | 1 | 919,444.0 | 7.6 | inv_q |
-| 4,813,995 | 1 | 924,412.0 | 7.3 | inv_q |
-| 4,822,693 | 1 | 926,082.1 | 7.5 | inv_q |
-| 4,858,671 | to the end | 932,989.8 | -7.6 | Ended ECC signing |
-
-### Performance
-
-The ECC core performance is reported in the next section.
-
-### Pure hardware architecture
-
-In this architecture, the ECC interface and controller are implemented in hardware. The performance specification of the ECC architecture is reported as shown in the following table.
-
-| Operation | Cycle count \[CCs\] | Time \[ms\] @ 400 MHz | Throughput \[op/s\] |
-| :-------- | :------------------ | :-------------------- | :------------------ |
-| Keygen | 909,648 | 2.274 | 439 |
-| Signing | 932,990 | 2.332 | 428 |
-| Verifying | 1,223,938 | 3.060 | 326 |
-## PCR vault
-
-* Platform Configuration Register (PCR) vault is a register file that stores measurements to be used by the microcontroller.
-* PCR entries are read-only registers of 384 bits each.
-* Control bits allow for entries to be cleared by FW, which sets their values back to 0.
-* A lock bit can be set by FW to prevent the entry from being cleared. The lock bit is sticky and only resets on a powergood cycle.
-
-| PCRV register | Address Offset | Description |
-| :---------------------------------| :------------- | :----------------------------- |
-| PCR Control\[31:0\] | 0x1001a000 | 32 Control registers, 32 bits each |
-| PCR Entry\[31:0\]\[11:0\]\[31:0\] | 0x1001a600 | 32 PCR entries, 384 bits each |
-
-### PCR vault functional block
-
-PCR entries are hash extended using a hash extension function. The hash extension function takes the data currently in the PCR entry specified, concatenates data provided by the FW, and performs a SHA384 function on that data, storing the result back into the same PCR entry.
-
-### PCR hash extend function
-
-FW provides the PCR entry to use as source and destination of the hash extend. HW copies the PCR into the start of the SHA block and locks those dwords from FW access. FW then provides the new data, and runs the SHA function as usual. After initialization, the locked dwords are unlocked.
-
-FW must set a last cycle flag before running the last iteration of the SHA engine. This could be the first “init” cycle, or the Nth “next” cycle. This flag allows HW to copy the final resulting hash output back to the source PCR.
-
-### PCR signing
-
-* PCR signing uses the key in key slot index 7 for PCR signing
-* HW implements a HW function called GEN\_PCR\_HASH
- * HW reads all the PCRs from all the PCR slots and hash extends them along with the NONCE that Caliptra FW provides
- * PCR Hash = Hash(PCR[0], …, PCR[31], Nonce)
-* HW also implements a HW function called SIGN\_PCR. This function takes the PCR digest that was generated by the previous routine and signs it using the key in key slot 7, following the same ECC sign flow defined in the [ECC](#ecc) section.
- * The resulting PCR DIGEST is used only once for signing by the HW. If a new PCR signing is required, GEN\_PCR\_HASH needs to be redone.
-
-## Key vault
-
-Key Vault (KV) is a register file that stores the keys to be used by the microcontroller, but this register file is not observed by the microcontroller. Each cryptographic function has a control register and functional block designed to read from and write to the KV.
-
-| KV register | Description |
-| :------------------------------- | :------------------------------------------------------- |
-| Key Control\[7:0\] | 8 Control registers, 32 bits each |
-| Key Entry\[7:0\]\[15:0\]\[31:0\] | 8 Key entries, 512 bits each
No read or write access |
-
-### Key vault functional block
-
-Keys and measurements are stored in 512b register files. These have no read or write path from the microcontroller. The entries are read through a passive read mux driven by each cryptographic block. Locked entries return zeroes.
-
-Entries in the KV must be cleared via control register, or by de-assertion of pwrgood.
-
-Each entry has a control register that is writable by the microcontroller.
-
-The destination valid field is programmed by FW in the cryptographic block generating the key, and it is passed here at generation time. This field cannot be modified after the key is generated and stored in the KV.
-
-| KV Entry Ctrl Fields | Reset | Description |
-|---------------------------|-------------------|------------------------|
-| Lock wr\[0\] | core_only_rst_b | Setting the lock wr field prevents the entry from being written by the microcontroller. Keys are always locked. After a lock is set, it cannot be reset until cptra_rst_b is de-asserted. |
-| Lock use\[1\] | core_only_rst_b | Setting the lock use field prevents the entry from being used in any cryptographic blocks. After the lock is set, it cannot be reset until cptra_rst_b is de-asserted. |
-| Clear\[2\] | cptra_rst_b | If unlocked, setting the clear bit causes KV to clear the associated entry. The clear bit is reset after entry is cleared. |
-| Copy\[3\] | cptra_rst_b | ENHANCEMENT: Setting the copy bit causes KV to copy the key to the entry written to Copy Dest field. |
-| Copy Dest\[8:4\] | cptra_rst_b | ENHANCEMENT: Destination entry for the copy function. |
-| Dest_valid\[16:9\] | hard_reset_b | KV entry can be used with the associated cryptographic block if the appropriate index is set.
\[0\] - HMAC KEY
\[1\] - HMAC BLOCK
\[2\] - SHA BLOCK
\[2\] - ECC PRIVKEY
\[3\] - ECC SEED
\[7:5\] - RSVD |
-| last_dword\[20:19\] | hard_reset_b | Store the offset of the last valid dword, used to indicate the last cycle for read operations. |
-
-### Key vault cryptographic functional block
-
-A generic block is instantiated in each cryptographic block to enable access to KV.
-
-Each input to a cryptographic engine can have a key vault read block associated with it. The KV read block takes in a keyvault read control register that drives an FSM to copy an entry from the keyvault into the appropriate input register of the cryptographic engine.
-
-Each output generated by a cryptographic engine can have its result copied to a slot in the keyvault. The KV write block takes in a keyvault write control register. This register drives an FSM to copy the result from the cryptographic engine into the appropriate keyvault entry. It also programs a control field for that entry to indicate where that entry can be used.
-
-After programming the key vault read control, FW needs to query the associated key vault read status to confirm that the requested key was copied successfully. After valid is set and the error field reports success, the key is ready to be used.
-
-Similarly, after programming the key vault write control and initiating the cryptographic function that generates the key to be written, FW needs to query the associated key vault write status to confirm that the requested key was generated and written successfully.
-
-The following tables describe read, write, and status values for key vault blocks.
-
-| KV Read Ctrl Reg | Description |
-| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
-| read_en\[0\] | Indicates that the read data is to come from the key vault. Setting this bit to 1 initiates copying of data from the key vault. |
-| read_entry\[5:1\] | Key vault entry to retrieve the read data from the engine. |
-| pcr_hash_extend\[6\] | Requested entry is a PCR. This is used only for the SHA engine to hash extend. It is not functional in any other cryptographic engine. |
-| rsvd\[31:7\] | Reserved field |
-
-| KV Write Ctrl Reg | Description |
-| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
-| write_en\[0\] | Indicates that the result is to be stored in the key vault. Setting this bit to 1 copies the result to the key vault when it is ready. |
-| write_entry\[5:1\] | Key vault entry to store the result. |
-| hmac_key_dest_valid\[6\] | HMAC KEY is a valid destination. |
-| hmac_block_dest_valid\[7\] | HMAC BLOCK is a valid destination. |
-| sha_block_dest_valid\[8\] | SHA BLOCK is a valid destination. |
-| ecc_pkey_dest_valid\[9\] | ECC PKEY is a valid destination. |
-| ecc_seed_dest_valid\[10\] | ECC SEED is a valid destination. |
-| rsvd\[31:11\] | Reserved field |
-
-| KV Status Reg | Description |
-| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |
-| ready\[0\] | Key vault control is idle and ready for a command. |
-| valid\[1\] | Requested flow is done. |
-| error\[9:2\] | SUCCESS - 0x0 - Key Vault flow was successful
KV_READ_FAIL - 0x1 - Key Vault Read flow failed
KV_WRITE_FAIL - 0x2 - Key Vault Write flow failed |
-
-### De-obfuscation engine
-
-To protect software intellectual property from different attacks and, particularly, for thwarting an array of supply chain threats, code obfuscation is employed. Hence, the de-obfuscation engine is implemented to decrypt the code.
-
-Advanced Encryption Standard (AES) is used as a de-obfuscation function to encrypt and decrypt data [4]. The hardware implementation is based on[ Secworks/aes](https://github.com/secworks/aes) [1]. The implementation supports the two variants: 128- and 256-bit keys with a block/chunk size of 128 bits.
-
-The AES algorithm is described as follows:
-
-* The key is fed to an AES core to compute and initialize the round key
-* The message is broken into 128-bit chunks by the host
-* For each chunk:
- * The message is fed to the AES core
- * The AES core and its working mode (enc/dec) are triggered by the host
- * The AES core status is changed to ready after encryption or decryption processing
-* The result digest can be read before processing the next message chunks
-
-
-### Key vault de-obfuscation block operation
-
-A de-obfuscation engine (DOE) is used in conjunction with AES cryptography to de-obfuscate the UDS and field entropy.
-
-1. The obfuscation key is driven to the AES key. The data to be decrypted (either obfuscated UDS or obfuscated field entropy) is fed into the AES data.
-2. An FSM manually drives the AES engine and writes the decrypted data back to the key vault.
-3. FW programs the DOE with the requested function (UDS or field entropy de-obfuscation), and the destination for the result.
-4. After de-obfuscation is complete, FW can clear out the UDS and field entropy values from any flops until cptra\_pwrgood de-assertion.
-
-The following tables describe DOE register and control fields.
-
-| DOE Register | Address | Description |
-| :----------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------- |
-| IV | 0x10000000 | 128 bit IV for DOE flow. Stored in big-endian representation. |
-| CTRL | 0x10000010 | Controls for DOE flows. |
-| STATUS | 0x10000014 | Valid indicates the command is done and results are stored in keyvault. Ready indicates the core is ready for another command. |
-
-| DOE Ctrl Fields | Reset | Description |
-| :--------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
-| COMMAND\[1:0\] | Cptra_rst_b | 2’b00 Idle
2’b01 Run UDS flow
2’b10 Run FE flow
2’b11 Clear Obf Secrets |
-| DEST\[4:2\] | Cptra_rst_b | Destination register for the result of the de-obfuscation flow. Field entropy writes into DEST and DEST+1
Key entry only, can’t go to PCR . |
-
-### Key vault de-obfuscation flow
-
-1. ROM loads IV into DOE. ROM writes to the DOE control register the destination for the de-obfuscated result and sets the appropriate bit to run UDS and/or the field entropy flow.
-2. DOE state machine takes over and loads the Caliptra obfuscation key into the key register.
-3. Next, either the obfuscated UDS or field entropy are loaded into the block register 4 DWORDS at a time.
-4. Results are written to the KV entry specified in the DEST field of the DOE control register.
-5. State machine resets the appropriate RUN bit when the de-obfuscated key is written to KV. FW can poll this register to know when the flow is complete.
-6. The clear obf secrets command flushes the obfuscation key, the obfuscated UDS, and the field entropy from the internal flops. This should be done by ROM after both de-obfuscation flows are complete.
-
-## Data vault
-
-Data vault is a set of generic scratch pad registers with specific lock functionality and clearable on cold and warm resets.
-
-* 48B scratchpad registers that are lockable but cleared on cold reset (10 registers)
-* 48B scratchpad registers that are lockable but cleared on warm reset (10 registers)
-* 4B scratchpad registers that are lockable but cleared on cold reset (8 registers)
-* 4B scratchpad registers that are lockable but cleared on warm reset (10 registers)
-* 4B scratchpad registers that are cleared on warm reset (8 registers)
-
-## Cryptographic blocks fatal and non-fatal errors
-
-The following table describes cryptographic errors.
-
-| Errors | Error type | Description |
-| :--------- | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ECC_R_ZERO | HW_ERROR_NON_FATAL | Indicates a non-fatal error in ECC signing if the computed signature R is equal to 0. FW should change the message or privkey to perform a valid signing. |
-
-# Terminology
-
-The following terminology is used in this document.
-
-| Abbreviation | Description |
-| :----------- | :--------------------------------------------- |
-| AES | Advanced Encryption Standard |
-| BMC | Baseboard Management Controller |
-| CA | Certificate Authority |
-| CDI | Composite Device Identifier |
-| CPU | Central Processing Unit |
-| CRL | Certificate Revocation List |
-| CSR | Certificate Signing Request |
-| CSP | Critical Security Parameter |
-| DICE | Device Identifier Composition Engine |
-| DME | Device Manufacturer Endorsement |
-| DPA | Differential Power Analysis |
-| DRBG | Deterministic Random Bit Generator |
-| DWORD | 32-bit (4-byte) data element |
-| ECDSA | Elliptic Curve Digital Signature Algorithm |
-| FMC | FW First Mutable Code |
-| FSM | Finite State Machine |
-| GPU | Graphics Processing Unit |
-| HMAC | Hash-based message authentication code |
-| IDevId | Initial Device Identifier |
-| iRoT | Internal RoT |
-| IV | Initial Vector |
-| KAT | Known Answer Test |
-| KDF | Key Derivation Function |
-| LDevId | Locally Significant Device Identifier |
-| MCTP | Management Component Transport Protocol |
-| NIC | Network Interface Card |
-| NIST | National Institute of Standards and technology |
-| OCP | Open Compute Project |
-| OTP | One-time programmable |
-| PCR | Platform Configuration Register |
-| PKI | Public Key infrastructure |
-| PUF | Physically unclonable function |
-| RNG | Random Number Generator |
-| RoT | Root of Trust |
-| RTI | RoT for Identity |
-| RTM | RoT for Measurement |
-| RTR | RoT for Reporting |
-| SCA | Side-Channel Analysis |
-| SHA | Secure Hash Algorithm |
-| SoC | System on Chip |
-| SPA | Simple Power Analysis |
-| SPDM | Security Protocol and Data Model |
-| SSD | Solid State Drive |
-| TCB | Trusted Computing Base |
-| TCI | TCB Component Identifier |
-| TCG | Trusted Computing Group |
-| TEE | Trusted Execution Environment |
-| TRNG | True Random Number Generator |
-| UECC | Uncorrectable Error Correction Code |
-
-# References
-
-1. J. Strömbergson, "Secworks," \[Online\]. Available at https://github.com/secworks.
-2. NIST, Federal Information Processing Standards Publication (FIPS PUB) 180-4 Secure Hash Standard (SHS).
-3. OpenSSL \[Online\]. Available at https://www.openssl.org/docs/man3.0/man3/SHA512.html.
-4. N. W. Group, RFC 3394, Advanced Encryption Standard (AES) Key Wrap Algorithm, 2002.
-5. NIST, Federal Information Processing Standards Publication (FIPS) 198-1, The Keyed-Hash Message Authentication Code, 2008.
-6. N. W. Group, RFC 4868, Using HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512 with IPsec, 2007.
-7. RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), 2013.
-8. TCG, Hardware Requirements for a Device Identifier Composition Engine, 2018.
-9. Coron, J.-S.: Resistance against differential power analysis for elliptic curve cryptosystems. In: Ko¸c, C¸ .K., Paar, C. (eds.) CHES 1999. LNCS, vol. 1717, pp. 292–302.
-10. Schindler, W., Wiemers, A.: Efficient side-channel attacks on scalar blinding on elliptic curves with special structure. In: NISTWorkshop on ECC Standards (2015).
-11. National Institute of Standards and Technology, "Digital Signature Standard (DSS)", Federal Information Processing Standards Publication (FIPS PUB) 186-4, July 2013.
-12. NIST SP 800-90A, Rev 1: "Recommendation for Random Number Generation Using Deterministic Random Bit Generators", 2012. |
-13. CHIPS Alliance, “RISC-V VeeR EL2 Programmer’s Reference Manual” \[Online\] Available at https://github.com/chipsalliance/Cores-VeeR-EL2/blob/main/docs/RISC-V_VeeR_EL2_PRM.pdf.
-14. “The RISC-V Instruction Set Manual, Volume I: User-Level ISA, Document Version 20191213”, Editors Andrew Waterman and Krste Asanovi ́c, RISC-V Foundation, December 2019. Available at https://riscv.org/technical/specifications/.
-15. “The RISC-V Instruction Set Manual, Volume II: Privileged Architecture, Document Version 20211203”, Editors Andrew Waterman, Krste Asanovi ́c, and John Hauser, RISC-V International, December 2021. Available at https://riscv.org/technical/specifications/.
-
-[1] _Caliptra.** **Spanish for “root cap” and describes the deepest part of the root_
diff --git a/docs/CaliptraIntegrationSpecification.md b/docs/CaliptraIntegrationSpecification.md
deleted file mode 100644
index e270db4e3..000000000
--- a/docs/CaliptraIntegrationSpecification.md
+++ /dev/null
@@ -1,898 +0,0 @@
-
-
-Caliptra Integration Specification
-
-Version 1.0-rc1
-
-
-
-# Scope
-
-This document describes the Caliptra hardware implementation requirements, details, and release notes. This document is intended for a high-level overview of the IP used in Caliptra.
-
-This document is not intended for any micro-architectural design specifications. Detailed information on each of the IP components are shared in individual documents, where applicable.
-
-# Overview
-
-This document contains high level information on the Caliptra hardware design. The details include open-source IP information, configuration settings for open-source IP (if applicable), and IP written specifically for Caliptra.
-
-For more information, see[ Caliptra: A Datacenter System on a Chip (SoC) Root of Trust (RoT)](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html).
-
-## References and related specifications
-
-The blocks described in this document are either obtained from open-source GitHub repositories, developed from scratch, or modification of open-source implementations. Links to relevant documentation and GitHub sources are shared in the following table.
-
-*Table 1: Related specifications*
-
-| IP/Block | GitHub URL | Documentation | Link |
-| :--------- | :--------- | :--------- |:--------- |
-| Cores-VeeR | [GitHub - chipsalliance/Cores-VeeR-EL2](https://github.com/chipsalliance/Cores-VeeR-EL2) | VeeR EL2 Programmer’s Reference Manual | [chipsalliance/Cores-VeeR-EL2 · GitHubPDF](http://cores-swerv-el2/RISC-V_SweRV_EL2_PRM.pdf%20at%20master%20%C2%B7) |
-| AHB Lite Bus | [aignacio/ahb_lite_bus: AHB Bus lite v3.0 (github.com)](https://github.com/aignacio/ahb_lite_bus) | AHB Lite Protocol
[Figure 2: SoC interface block diagram](#soc-interface-definition) | [ahb_lite_bus/docs at master · aignacio/ahb_lite_bus (github.com)](https://github.com/aignacio/ahb_lite_bus/tree/master/docs)
[ahb_lite_bus/diagram_ahb_bus.png at master · aignacio/ahb_lite_bus (github.com)](https://github.com/aignacio/ahb_lite_bus/blob/master/diagram_ahb_bus.png) |
-| SHA 256 | [secworks/sha256: Hardware implementation of the SHA-256 cryptographic hash function (github.com)](https://github.com/secworks/sha256) | | |
-| SHA 512 | | | |
-| SPI Controller | | | |
-
-# Caliptra Core
-
-The following figure shows the Caliptra Core.
-
-*Figure 1: Caliptra block diagram*
-
-
-
-## Boot Media Dependent (passive) vs Boot Media Integrated (active) profile
-
-In the BMD profile, QSPI and I3C IO peripherals are disabled using integration-time defines passed to the hardware, which are also exposed to ROM. Peripheral IOs can be tied off appropriately for the BMD profile at SoC integration time. For more information on the BMD vs. BMI profile differences, see the boot flows in [Caliptra profiles](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html#caliptra-profiles). Only the BMD profile is supported for the first generation release of Caliptra.
-
-# SoC interface definition
-
-The following figure shows the SoC interface definition.
-
-*Figure 2: SoC Interface Block Diagram*
-
-
-
-## Integration parameters
-
-The following table describes integration parameters.
-
-*Table 2: Integration parameters*
-
-| **Parameter name** | **Width** | **Defines file** | **Description** |
-| :--------- | :--------- | :--------- | :--------- |
-| CPTRA_SET_MBOX_PAUSER_INTEG | 5 | soc_ifc_pkg.sv | Each bit hardcodes the valid PAUSER for mailbox at integration time. |
-| CPTRA_MBOX_VALID_PAUSER | \[4:0\]\[31:0\] | soc_ifc_pkg.sv | Each parameter corresponds to a hardcoded valid PAUSER value for mailbox, set at integration time. Must set corresponding bit in the CPTRA_SET_MBOX_PAUSER_INTEG parameter for this valid pauser override to be used. |
-| CPTRA_DEF_MBOX_VALID_PAUSER | 32 | soc_ifc_pkg.sv | Sets the default valid PAUSER for mailbox accesses. This PAUSER is valid when any VALID_PAUSER is unlocked or not set by INTEG parameter. |
-| CPTRA_SET_FUSE_PAUSER_INTEG | 1 | soc_ifc_pkg.sv | Sets the valid PAUSER for fuse accesses at integration time. |
-| CPTRA_FUSE_VALID_PAUSER | 32 | soc_ifc_pkg.sv | Overrides the programmable valid PAUSER for fuse accesses when CPTRA_SET_FUSE_PAUSER_INTEG is set to 1. |
-
-*Table 3: Integration Defines*
-
-| **Defines** | **Defines file** | **Description** |
-| :--------- | :--------- | :--------- |
-| CALIPTRA_APB_ADDR_WIDTH | config_defines.svh | Width of the APB Address field. Default to 32. |
-| CALIPTRA_APB_DATA_WIDTH | config_defines.svh | Width of the APB Data field. Default to 32. |
-| CALIPTRA_APB_USER_WIDTH | config_defines.svh | Width of the APB PAUSER field. |
-| CALIPTRA_INTERNAL_TRNG | config_defines.svh | Defining this enables the internal TRNG source. |
-| CALIPTRA_INTERNAL_UART | config_defines.svh | Defining this enables the internal UART. |
-| CALIPTRA_INTERNAL_QSPI | config_defines.svh | Defining this enables the internal QSPI. |
-
-## Interface
-
-The following tables describe the interface signals.
-
-*Table 4: Clocks and resets*
-
-| Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description|
-| :--------- | :--------- | :--------- | :--------- | :--------- |
-| cptra_pwrgood | 1 | Input | Asynchronous Assertion
Synchronous deassertion to clk | Active high power good indicator.
Deassertion hard resets Caliptra. |
-| cptra_rst_b | 1 | Input | Asynchronous Assertion
Synchronous deassertion to clk | Active low asynchronous reset. |
-| clk | 1 | Input | | Convergence and validation done at 400MHz. All other frequencies are up to the user. |
-
-*Table 5: APB Interface*
-
-| Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description |
-| :--------- | :--------- | :--------- | :--------- | :--------- |
-| PADDR | 32 | Input | Synchronous to clk | Address bus |
-| PPROT | 3 | Input | Synchronous to clk | Protection level |
-| PSEL | 1 | Input | Synchronous to clk | Select line |
-| PENABLE | 1 | Input | Synchronous to clk | Indicates the second and subsequent cycles. |
-| PWRITE | 1 | Input | Synchronous to clk | Indicates transfer is a write when high or a read when low. |
-| PWDATA | 32 | Input | Synchronous to clk | Write data bus |
-| PAUSER | APB_USER_REQ_WIDTH | Input | Synchronous to clk | Sideband signal indicating requestor ID for transfer. |
-| PREADY | 1 | Output | Synchronous to clk | Used to extend an APB transfer by completer. |
-| PRDATA | 32 | Output | Synchronous to clk | Read data bus |
-| PSLVERR | 1 | Output | Synchronous to clk | Transfer error |
-
-*Table 6: QSPI signals*
-
-| Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description |
-| :--------- | :--------- | :--------- | :--------- | :--------- |
-| qspi_clk_o | 1 | Output | | QSPI clock |
-| qspi_cs_no | 2 | Output | Synchronous to qspi_clk_o | QSPI chip select |
-| qspi_d_i | 4 | Input | Synchronous to qspi_clk_o | QSPI data lanes for receiving data. |
-| qspi_d_o | 4 | Output | Synchronous to qspi_clk_o | QSPI data output lanes for sending opcode and address. |
-| qspi_d_en_o | 4 | Output | Synchronous to qspi_clk_o | QSPI enable pins to control data direction. |
-
-*Table 7: Mailbox notifications*
-
-| Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description |
-| :--------- | :--------- | :--------- | :--------- | :--------- |
-| ready_for_fuses | 1 | Output | Synchronous to clk | Indicates that Caliptra is ready for fuse programming. |
-| ready_for_fw_push | 1 | Output | Synchronous to clk | Indicates that Caliptra is ready for firmware. |
-| ready_for_runtime | 1 | Output | Synchronous to clk | Indicates that Caliptra firmware is ready for RT flow. |
-| mailbox_data_avail | 1 | Output | Synchronous to clk | Indicates that the mailbox has data for SoC to read (reflects the value of the register). |
-| mailbox_flow_done | 1 | Output | Synchronous to clk | Indicates that the mailbox flow is complete (reflects the value of the register). |
-
-*Table 8: SRAM interface*
-
-| Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description |
-| :--------- | :--------- | :--------- | :--------- | :--------- |
-| mbox_sram_cs | 1 | Output | Synchronous to clk | Chip select for mbox SRAM |
-| mbox_sram_we | 1 | Output | Synchronous to clk | Write enable for mbox SRAM |
-| mbox_sram_addr | MBOX_ADDR_W | Output | Synchronous to clk | Addr lines for mbox SRAM |
-| mbox_sram_wdata | MBOX_DATA_W | Output | Synchronous to clk | Write data for mbox SRAM |
-| mbox_sram_rdata | MBOX_DATA_W | Input | Synchronous to clk | Read data for mbox SRAM |
-| imem_cs | 1 | Output | Synchronous to clk | Chip select for imem SROM |
-| imem_addr | IMEM_ADDR_WIDTH | Output | Synchronous to clk | Addr lines for imem SROM |
-| imem_rdata | IMEM_DATA_WIDTH | Input | Synchronous to clk | Read data for imem SROM |
-| iccm_clken | ICCM_NUM_BANKS | Input | Synchronous to clk | Per-bank clock enable |
-| iccm_wren_bank | ICCM_NUM_BANKS | Input | Synchronous to clk | Per-bank write enable |
-| iccm_addr_bank | ICCM_NUM_BANKS x (ICCM_BITS-4) | Input | Synchronous to clk | Per-bank address |
-| iccm_bank_wr_data | ICCM_NUM_BANKS x 39 | Input | Synchronous to clk | Per-bank input data |
-| iccm_bank_dout | ICCM_NUM_BANKS x 39 | Output | Synchronous to clk | Per-bank output data |
-| dccm_clken | DCCM_NUM_BANKS | Input | Synchronous to clk | Per-bank clock enable |
-| dccm_wren_bank | DCCM_NUM_BANKS | Input | Synchronous to clk | Per-bank write enable |
-| dccm_addr_bank | DCCM_NUM_BANKS x (DCCM_BITS-4) | Input | Synchronous to clk | Per-bank address |
-| dccm_wr_data_bank | DCCM_NUM_BANKS x DCCM_FDATA_WIDTH | Input | Synchronous to clk | Per-bank input data |
-| dccm_bank_dout | DCCM_NUM_BANKS x DCCM_FDATA_WIDTH | Output | Synchronous to clk | Per-bank output data |
-
-*Table 9: JTAG interface*
-
-| Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description |
-| :--------- | :--------- | :--------- | :--------- | :--------- |
-| jtag_tck | 1 | input | | |
-| jtag_tms | 1 | input | Synchronous to tck | |
-| jtag_tdi | 1 | input | Synchronous to tck | |
-| jtag_trst_n | 1 | input | Async Deassertion
Assertion Synchronous to tck | |
-| jtag_tdo | 1 | output | Synchronous to tck | |
-
-*Table 10: UART interface*
-
-| Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description |
-| :--------- | :--------- | :--------- | :--------- | :--------- |
-| uart_tx | 1 | output | | UART transmit pin |
-| uart_rx | 1 | input | | UART receive pin |
-
-*Table 11: Security and miscellaneous*
-
-| Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description |
-| :--------- | :--------- | :--------- | :--------- | :--------- |
-| CPTRA_OBF_KEY | 256 | Input Strap | Asynchronous | Obfuscation key is driven by SoC at integration time. Ideally this occurs just before tape-in and the knowledge of this key must be protected unless PUF is driving this. The key is latched by Caliptra on caliptra powergood deassertion. It is cleared after its use and can only re-latched on a power cycle (powergood deassertion to assertion). |
-| SECURITY_STATE | 3 | Input Strap | Synchronous to clk | Security state that Caliptra should take (for example, manufacturing, secure, unsecure, etc.). The key is latched by Caliptra on cptra_noncore_rst_b deassertion. Any time the state changes to debug mode, all keys, assets, and secrets stored in fuses or key vault are cleared. Cryptography core states are also flushed if they were being used. |
-| scan_mode | 1 | Input Strap | Synchronous to clk | Must be set before entering scan mode. This is a separate signal than the scan chain enable signal that goes into scan cells. This allows Caliptra to flush any assets or secrets present in key vault and flops if the transition is happening from a secure state. |
-| GENERIC_INPUT_WIRES | 64 | Input | Synchronous to clk | Placeholder of input wires for late binding features. These values are reflected into registers that are exposed to firmware. |
-| GENERIC_OUTPUT_WIRES | 64 | Output | Synchronous to clk | Placeholder of output wires for late binding features. Firmware can set the wires appropriately via register writes. |
-| CALIPTRA_ERROR_FATAL | 1 | Output | Synchronous to clk | Indicates a fatal error from Caliptra. |
-| CALIPTRA_ERROR_NON_FATAL | 1 | Output | Synchronous to clk | Indicates a non fatal error from Caliptra. |
-| BootFSM_BrkPoint | 1 | Input Strap | Asynchronous | Stops the BootFSM to allow TAP writes set up behavior. Examples of these behaviors are skipping or running ROM flows, or stepping through BootFSM. |
-| eTRNG_REQ | 1 | Output | Synchronous to clk | External source mode: TRNG_REQ to SoC. SoC writes to TRNG architectural registers with a NIST-compliant entropy.
Internal source mode: TRNG_REQ to SoC. SoC enables external RNG digital bitstream input into iTRNG_DATA/iTRNG_VALID. |
-| iTRNG_DATA | 4 | Input | Synchronous to clk | External source mode: Not used.
Internal source mode only: RNG digital bit stream from SoC, which is sampled when iTRNG_VALID is high. |
-| iTRNG_VALID | 1 | Input | Synchronous to clk | External source mode: Not used.
Internal source mode only: RNG bit valid. This is valid per transaction. TRNG_DATA can be sampled whenever this bit is high. The expected iTRNG_VALID output rate is about 50KHz. |
-
-## Architectural registers and fuses
-
-Control registers and fuses are documented on GitHub.
-
-* External Registers: [caliptra\_top\_reg — caliptra\_top\_reg Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/external-regs/?p=)
-* Internal Registers - [clp — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=)
-
-## Fuses
-
-Fuses are writable only one time and require a cptra\_pwrgood to be recycled to be written again.
-
-After all fuses are written, the fuse done register at the end of the fuse address space must be set to 1 to lock the fuse writes and to proceed with the boot flow.
-
-Although fuse values (and the fuse done register) persist across a warm reset, SoC is still required to perform a write to the fuse done register while in the BOOT\_FUSE state in order to complete the bringup from reset. See 6.1 Boot FSM for further details.
-
-## Interface rules
-
-The following figure shows the reset rules and timing.
-
-*Figure 3: Reset rules and timing diagram*
-
-
-
-Deassertion of cptra\_pwrgood indicates a power cycle that results in returning Caliptra to its default state. All resettable flops are reset.
-
-De-assertion of cptra\_rst\_b indicates a warm reset cycle that resets all but the “sticky” registers (fuses, error logging, etc.).
-
-### APB arbitration
-
-Caliptra is a client on the APB bus, incapable of initiating transfers. If SoCs have multiple APBs or other proprietary-fabric protocols that require any special fabric arbitration, that arbitration is done at SoC level.
-
-### Undefined address accesses
-
-All accesses that are outside of the defined address space of Caliptra are responded to by Caliptra’s SoC interface:
-* All reads to undefined addresses get completions with zero data.
-* All writes to undefined addresses are dropped.
-* All other undefined opcodes are silently dropped.
-* Access to mailbox memory region with invalid PAUSER are dropped.
-* Access to a fuse with invalid PAUSER are dropped.
-* PSLVERR is asserted for any of the above conditions.
-
-All accesses must be 32-bit aligned. Misaligned writes are dropped and reads return 0x0.
-
-### Undefined mailbox usages
-
-A trusted/valid requester that locks the mailbox and never releases the lock will cause the mailbox to be locked indefinitely.
-
-Caliptra firmware internally has the capability to force release the mailbox based on various timers but there is no architectural requirement to use this capability.
-
-### Straps
-
-Straps are signal inputs to Caliptra that are sampled once on reset exit, and the latched value persists throughout the remaining uptime of the system. Straps are sampled on either caliptra pwrgood signal deassertion or cptra\_noncore\_rst\_b deassertion – refer to interface table for list of straps.
-
-### Deobfuscation key
-
-SoC drives the key at the tape-in time of the SoC using an Engineering Change Order (ECO) and must be protected from common knowledge. For a given SoC construction, this can be driven using a PUF too.
-
-The key must follow the security rules defined in the[ Caliptra architectural specification](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html).
-
-SoC must ensure that there are no SCAN cells on the flops that latch this key internally to Caliptra.
-
-## Late binding interface signals
-
-The interface signals GENERIC\_INPUT\_WIRES and GENERIC\_OUTPUT\_WIRES are placeholders on the SoC interface reserved for late binding features. This may include any feature that is required for correct operation of the design in the final integrated SoC and that may not be accommodated through existing interface signaling (such as the mailbox).
-
-While these late binding interface pins are generic in nature until assigned a function, integrators must not define non-standard use cases for these pins. Defining standard use cases ensures that the security posture of Caliptra in the final implementation is not degraded relative to the consortium design intent.
-
-Each wire connects to a register in the SoC Interface register bank through which communication to the internal microprocessor may be facilitated. Each signal is 64 bits in size.
-
-Activity on any bit of the GENERIC\_INPUT\_WIRES triggers a notification interrupt to the microcontroller indicating a bit toggle.
-
-The following table describes the allocation of functionality on GENERIC\_INPUT\_WIRES.
-
-*Table 12: GENERIC\_INPUT\_WIRES function binding*
-
-| Bit | Name | Description |
-| :--------- | :--------- | :--------- |
-| 0 | Zeroization status | Used by SoC to provide zeroization status of fuses. |
-| 63:1 | RESERVED | No allocated function. |
-
-# SoC interface operation
-
-The Caliptra mailbox is the primary communication method between Caliptra and the SoC that Caliptra is integrated into.
-
-The Caliptra mailbox uses an APB interface to communicate with the SoC. The SoC can write to and read from various memory mapped register locations over the APB interface in order to pass information to Caliptra.
-
-Caliptra in turn also uses the mailbox to pass information back to the SoC. The interface does not author any transaction on the APB interface. The interface only signals to the SoC that data is available in the mailbox and it is the responsibility of the SoC to read that data from the mailbox.
-
-## Boot FSM
-
-The Boot FSM detects that the SoC is bringing Caliptra out of reset. Part of this flow involves signaling to the SoC that Caliptra is ready for fuses. After fuses are populated and the SoC indicates that it is done downloading fuses, Caliptra can wake up the rest of the IP by deasserting the internal reset. The following figure shows the boot FSM state.
-
-*Figure 4: Mailbox Boot FSM state diagram*
-
-
-
-The boot FSM first waits for the SoC to assert cptra\_pwrgood and de-assert cptra\_rst\_b. In the BOOT\_FUSE state, Caliptra signals to the SoC that it is ready for fuses. After the SoC is done writing fuses, it sets the fuse done register and the FSM advances to BOOT\_DONE.
-
-BOOT\_DONE enables Caliptra reset deassertion through a two flip-flop synchronizer.
-
-## SoC access mechanism
-
-The SoC communicates with the mailbox through an APB Interface. The SoC acts as the requester with the Caliptra mailbox as the receiver.
-
-The PAUSER bits are used by the SoC to identify which device is accessing the mailbox.
-
-## Mailbox
-
-The Caliptra mailbox is a 128 KiB buffer used for exchanging data between the SoC and the Caliptra microcontroller.
-
-When a mailbox is populated by the SoC, initiation of the operation by writing the execute bit triggers an interrupt to the microcontroller. This interrupt indicates that a command is available in the mailbox. The microcontroller is responsible for reading from and responding to the command.
-
-When a mailbox is populated by the microcontroller, an output wire to the SoC indicates that a command is available in the mailbox. The SoC is responsible for reading from and responding to the command.
-
-Mailboxes are generic data-passing structures with a specific protocol that defines legal operations. This protocol for writing to and reading from the mailbox is enforced in hardware as described in the [Caliptra mailbox errors](#caliptra-mailbox-errors) section. How the command and data are interpreted by the microcontroller and SoC are not enforced in this specification. \
-
-## Sender Protocol
-
-**Sending data to the mailbox:**
-
-1. Requester queries the mailbox by reading the LOCK control register.
- 1. If LOCK returns 0, LOCK is granted and will be set to 1.
- 2. If LOCK returns 1, MBOX is locked for another device.
-2. Requester writes the command to the COMMAND register.
-3. Requester writes the data length in bytes to the DLEN register.
-4. Requester writes data packets to the MBOX DATAIN register.
-5. Requester writes to the EXECUTE register.
-6. Requester reads the STATUS register. Status can return:
- 1. CMD\_BUSY - 2’b00 – Indicates the requested command is still in progress
- 2. DATA\_READY - 2’b01 – Indicates the return data is in the mailbox for requested command
- 3. CMD\_COMPLETE- 2’b10 – Indicates the successful completion of the requested command
- 4. CMD\_FAILURE- 2’b11 – Indicates the requested command failed
-7. Requester reads the response if DATA\_READY was the status.
-8. Requester resets the EXECUTE register to release the lock.
-
-**Notes on behavior:**
-
-Once LOCK is granted, the mailbox is locked until that device has concluded its operation. Caliptra has access to an internal mechanism to terminate a lock early or release the lock if the device does not proceed to use it or to recover from deadlock scenarios. The following figure shows the sender protocol flow.
-
-*Figure 5: Sender protocol flow chart*
-
-
-
-## Receiver Protocol
-
-Upon receiving indication that mailbox has been populated, the appropriate device can read the mailbox. This is indicated by a dedicated wire that is asserted when Caliptra populates the mailbox for SoC consumption.
-
-Caliptra will not initiate any mailbox commands that require a response from the SoC. Caliptra initiated mailbox commands are “broadcast” and available to any user on the SoC. SoC will not be able to write the DLEN or DATAIN register while processing a Caliptra initiated mailbox command.
-
-**Receiving data from the mailbox:**
-1. On mailbox\_data\_avail assertion, the receiver reads the COMMAND register.
-2. Receiver reads the DLEN register.
-3. Receiver reads the CMD register.
-4. Receiver reads the MBOX DATAOUT register.
- * Continue reading MBOX DATAOUT register until DLEN bytes are read.
-5. If a response is required, the receiver can populate the mailbox with the response by updating the DLEN register and writing to DATAIN with the response. (NOTE: The new DLEN value will not take effect until control is returned to the sender via write to the status register).
-6. Set the mailbox status register appropriately to hand control back to the sender.
-7. The sender will reset the EXECUTE register.
- * This releases the LOCK on the mailbox.
-
-The following figure shows the receiver protocol flow.
-
-*Figure 6: Receiver protocol flowchart*
-
-
-
-## Mailbox arbitration
-
-From a mailbox protocol perspective, as long as CPTRA\_VALID\_PAUSER registers carry valid requestors, mailbox lock can be obtained by any of those valid requestors but only one of them at any given time. While the mailbox flow is happening, all other requestors will not get a grant.
-
-A request for lock that is denied due to firmware having the lock results in an interrupt to the firmware. Firmware can optionally use this interrupt to release the lock.
-
-There is no fair arbitration scheme between SoC and microcontroller. It is first come, first served. When the mailbox is locked for microcontroller use and SoC has unsuccessfully requested the mailbox (due to mailbox actively being used), the mailbox generates an interrupt to the microcontroller as a notification.
-
-Further, there is no arbitration between various PAUSER attributes. PAUSER attributes exist for security and filtering reasons only.
-
-## MAILBOX PAUSER attribute register
-
-It is strongly recommended that these PAUSER registers are either set at integration time through integration parameters or be programmed by the SoC ROM before any mutable firmware or ROM patches are applied.
-
-### Programmable registers
-
-Caliptra provides 5 programmable registers that SoC can set at boot time to limit access to the mailbox peripheral. The default PAUSER set by the integration parameter CPTRA\_DEF\_MBOX\_VALID\_PAUSER is valid until all programmable registers are consumed. CPTRA\_MBOX\_VALID\_PAUSER registers become valid once the corresponding lock bit CPTRA\_MBOX\_PAUSER\_LOCK is set.
-
-*Table 13: PAUSER register definition*
-
-| Register | Description |
-| :--------- | :--------- |
-| CPTRA_MBOX_VALID_PAUSER\[4:0\]\[31:0\] | 5 registers for programming PAUSER values that are considered valid for accessing the mailbox protocol. Requests with PAUSER attributes that are not in this list will be ignored. |
-| CPTRA_MBOX_PAUSER_LOCK\[4:0\] | 5 registers, bit 0 of each will lock and mark VALID for the corresponding VALID_PAUSER register. |
-
-### Parameter override
-
-Another option for limiting access to the mailbox peripheral are the integration time parameters that override the programmable PAUSER registers. At integration time, the CPTRA\_SET\_MBOX\_PAUSER\_INTEG parameters can be set to 1 which enables the corresponding CPTRA\_MBOX\_VALID\_PAUSER parameters to override the programmable register.
-
-*Table 14: PAUSER Parameter definition*
-
-| Parameter | Description |
-| :--------- | :--------- |
-| CPTRA_SET_MBOX_PAUSER_INTEG\[4:0\] | Setting to 1 enables the corresponding CPTRA_MBOX_VALID_PAUSER parameter. |
-| CPTRA_MBOX_VALID_PAUSER\[4:0\] | Value to override programmable PAUSER register at integration time if corresponding CPTRA_SET_MBOX_PAUSER_INTEG parameter is set to 1. |
-
-## Caliptra mailbox protocol
-
-After the SoC side has written the EXECUTE register, the mailbox sends an interrupt to the microcontroller.
-
-The microcontroller reads the COMMAND and DLEN registers, as well as the data populated in the mailbox.
-
-The microcontroller can signal back to SoC through functional registers, and populate COMMAND, DLEN, and MAILBOX as well.
-
-## Caliptra mailbox errors
-
-Mailbox is responsible for only accepting writes from the device that requested and locked the mailbox.
-
-If the SoC violates this protocol, the mailbox flags a protocol violation and enters an error state. Two protocol violations are detected:
-1. Access without lock: Writes to any mailbox register by SoC or reads from the dataout register, without having first acquired the lock, are a violation.
- 1. If any agent currently has the lock, accesses by agents other than the one holding the lock are ignored.
- 2. If no agent currently has the lock, the violation results in a flagged error.
-2. Out of order access: SoC must follow the rules for the sender and receiver protocol that define access ordering and progression for a mailbox command.
- 1. If, after acquiring the lock, an SoC agent performs any register write (or read from the dataout register) outside of the prescribed ordering, this is a flagged violation.
- 2. Such access by any SoC agent that does not have the lock is ignored.
-
-After a mailbox protocol violation is flagged, it is reported to the system in several ways:
-* The mailbox FSM enters the ERROR state in response to an out of order access violation, and the new FSM state is readable via the mailbox status register. The LOCK value is preserved on entry to the ERROR state. The access without lock violation does not result in a state change. After entering the ERROR state, the mailbox may only be restored to the IDLE state by:
- * System reset
- * Write to the force unlock register by firmware inside Caliptra (via internal bus)
-
- Either of these mechanisms will also clear the mailbox LOCK.
-* Mailbox protocol violations are reported as fields in the HW ERROR non-fatal register. These events also cause assertion of the cptra\_error\_non\_fatal interrupt signal to SoC. Upon detection, SoC may acknowledge the error by clearing the error field in this register via bus write.
-* Mailbox protocol violations generate an internal interrupt to the Caliptra microcontroller. Caliptra firmware is aware of the protocol violation.
-
-The following table describes APB transactions that cause the Mailbox FSM to enter the ERROR state, given that the register “mbox\_user” contains the value of the APB PAUSER that was used to originally acquire the mailbox lock.
-
-*Table 15: Mailbox protocol error trigger conditions*
-
-| FSM state | SOC HAS LOCK | APB PAUSER eq mbox_user | Error state trigger condition |
-| :--------- | :--------- | :--------- | :--------- |
-| MBOX_RDY_FOR_CMD | 1 | true | Read from mbox_dataout. Write to any register other than mbox_cmd. |
-| MBOX_RDY_FOR_CMD | 1 | false | \- |
-| MBOX_RDY_FOR_CMD | 0 | \- | \- |
-| MBOX_RDY_FOR_DLEN | 1 | true | Read from mbox_dataout. Write to any register other than mbox_dlen. |
-| MBOX_RDY_FOR_DLEN | 1 | false | \- |
-| MBOX_RDY_FOR_DLEN | 0 | \- | \- |
-| MBOX_RDY_FOR_DATA | 1 | true | Read from mbox_dataout. Write to any register other than mbox_datain or mbox_execute. |
-| MBOX_RDY_FOR_DATA | 1 | false | \- |
-| MBOX_RDY_FOR_DATA | 0 | \- | \- |
-| MBOX_EXECUTE_UC | 1 | true | Read from mbox_dataout. Write to any register. |
-| MBOX_EXECUTE_UC | 1 | false | \- |
-| MBOX_EXECUTE_UC | 0 | \- | \- |
-| MBOX_EXECUTE_SOC | 1 | true | Write to any register other than mbox_execute. |
-| MBOX_EXECUTE_SOC | 1 | false | \- |
-| MBOX_EXECUTE_SOC | 0 | true/false\* | Write to any register other than mbox_status. |
-
-\* mbox\_user value is not used when Caliptra has lock and is sending a Caliptra to SoC mailbox operation.
-
-# SoC SHA acceleration block
-
-## Overview
-
-The SHA acceleration block is in the SoC interface. The SoC can access the accelerator’s hardware API and stream data to be hashed over the APB interface.
-
-SHA acceleration block uses a similar protocol to the mailbox, but has its own dedicated registers.
-
-SHA\_LOCK register is set on read. A read of 0 indicates the SHA was unlocked and will now be locked for the requesting user.
-
-SHA\_MODE register sets the mode of operation for the SHA.
-
-See the Hardware specification for additional details.
-* 2’b00 - SHA384 streaming mode
-* 2’b01 - SHA512 streaming mode
-* 2’b10 - SHA384 mailbox mode (Caliptra only, invalid for SoC requests)
-* 2’b11 - SHA512 mailbox mode (Caliptra only, invalid for SoC requests)
-
-## SoC Sender Protocol
-
-**Sending data to the SHA accelerator:**
-1. Requester queries the accelerator by reading the SHA\_LOCK control register.
- * If SHA\_LOCK returns 0, SHA\_LOCK is granted and is set to 1.
- * If SHA\_LOCK returns 1, it is locked for another device.
-2. Requester writes the SHA\_MODE register to the appropriate mode of operation.
-3. Requester writes the data length in bytes to the SHA\_DLEN register.
-4. Requester writes data packets to the SHA\_DATAIN register until SHA\_DLEN bytes are written.
-5. Requester writes the SHA\_EXECUTE register, this indicates that it is done streaming data.
-6. Requesters can poll the SHA\_STATUS register for the VALID field to be asserted.
-7. Once VALID is asserted, the completed hash can be read from the SHA\_DIGEST register.
-8. Requester must write 1 to the LOCK register to release the lock.
-
-# TRNG REQ HW API
-
-For SoCs that choose to not instantiate Caliptra’s embedded TRNG, we provide a TRNQ REQ HW API.
-
-**While the use of this API is convenient for early enablement, the current
-Caliptra hardware is unable to provide the same security guarantees with an
-external TRNG. In particular, it is highly advisable to instantiate an internal
-TRNG if ROM glitch protection is important.**
-
-1. Caliptra asserts TRNG\_REQ wire (this may be because Caliptra’s internal hardware or firmware made the request for a TRNG).
-2. SoC writes the TRNG architectural registers.
-3. SoC write a done bit in the TRNG architectural registers.
-4. Caliptra deasserts TRNG\_REQ.
-
-Having an interface that is separate from the SoC mailbox ensures that this request is not intercepted by any SoC firmware agents (which communicate with SoC mailbox). It is a requirement for FIPS compliance that this TRNG HW API is always handled by SoC hardware gasket logic (and not some SoC ROM or firmware code).
-
-TRNG DATA register is tied to TRNG VALID PAUSER. SoC can program the TRNG VALID PAUSER and lock the register using TRNG\_PAUSER\_LOCK[LOCK]. This ensures that TRNG DATA register is read-writeable by only the PAUSER programmed into the TRNG\_VALID\_PAUSER register. If the CPTRA\_TNRG\_PAUSER\_LOCK.LOCK is set to ‘0, then any agent can write to the TRNG DATA register. If the lock is set, only an agent with a specific TRNG\_VALID\_PAUSER can write.
-
-# SRAM implementation
-
-## Overview
-
-SRAMs are instantiated at the SoC level. Caliptra provides the interface to export SRAMs from internal components.
-
-SRAM repair logic (for example, BIST) and its associated fuses, which are proprietary to companies and their methodologies, is implemented external to the Caliptra boundary.
-
-SRAMs must NOT go through BIST or repair flows across a “warm reset”.
-
-Mailbox SRAM is implemented with ECC protection. Data width for the mailbox is 32-bits, with 7 parity bits for a Hamming-based SECDED (single-bit error correction and double-bit error detection).
-
-## RISC-V internal memory export
-
-To support synthesis flexibility and ease memory integration to various fabrication processes, all SRAM blocks inside the RISC-V core are exported to an external location in the testbench. A single unified interface connects these memory blocks to their parent logic within the RISC-V core. Any memory implementation may be used to provide SRAM functionality in the external location in the testbench, provided the implementation adheres to the interface requirements connected to control logic inside the processor. Memories behind the interface are expected to be implemented as multiple banks of SRAM, from which the RISC-V processor selects the target using an enable vector. The I-Cache has multiple ways, each containing multiple banks of memory, but I-Cache is disabled in Caliptra and this may be removed for synthesis.
-
-The following memories are exported:
-* Instruction Closely-Coupled Memory (ICCM)
-* Data Closely Coupled Memory (DCCM)
-
-Table 4 indicates the signals contained in the memory interface. Direction is relative to the exported memory wrapper that is instantiated outside of the Caliptra subsystem (that is, from the testbench perspective).
-
-## SRAM timing behavior
-* [Writes] Input wren signal is asserted simultaneously with input data and address. Input data is stored at the input address 1 clock cycle later.
-* [Reads] Input clock enable signal is asserted simultaneously with input address. Output data is available 1 clock cycle later from a flip-flop register stage.
-* [Writes] Input wren signal is asserted simultaneously with input data and address. Data is stored at the input address 1 clock cycle later.
-
-The following figure shows the SRAM interface timing.
-
-*Figure 7: SRAM interface timing*
-
-
-
-## SRAM parameterization
-
-Parameterization for ICCM/DCCM memories is derived from the configuration of the VeeR RISC-V core that has been selected for Caliptra integration. Parameters defined in the VeeR core determine signal dimensions at the Caliptra top-level interface and drive requirements for SRAM layout. For details about interface parameterization, see the [Interface](#interface) section. The following configuration options from the RISC-V Core dictate this behavior:
-
-*Table 16: SRAM parameterization*
-
-| Parameter | Value | Description |
-| :--------- | :--------- | :--------- |
-| ICCM_ENABLE | 1 | Configures ICCM to be present in VeeR core. |
-| ICCM_NUM_BANKS | 4 | Determines the number of physical 39-bit (32-bit data + 7-bit ECC) SRAM blocks that are instantiated in the ICCM. |
-| ICCM_INDEX_BITS | 13 | Address bit width for each ICCM Bank that is instantiated. |
-| ICCM_SIZE | 128 | Capacity of the ICCM in KiB. Total ICCM capacity in bytes is given by 4 \* ICCM_NUM_BANKS \* 2ICCM_INDEX_BITS. |
-| DCCM_ENABLE | 1 | Configures DCCM to be present in VeeR core. |
-| DCCM_NUM_BANKS | 4 | Determines the number of physical 39-bit (32-bit data + 7-bit ECC) SRAM blocks that are instantiated in the DCCM. |
-| DCCM_INDEX_BITS | 13 | Address bit width for each DCCM Bank that is instantiated. |
-| DCCM_SIZE | 128 | Capacity of the DCCM in KiB. Total DCCM capacity in bytes is given by 4 \* DCCM_NUM_BANKS \* 2DCCM_INDEX_BITS. |
-
-## Example SRAM machine check reliability integration
-
-This section describes an example implementation of integrator machine check reliability.
-
-This example is applicable to scenarios where an integrator may need control of or visibility into SRAM errors for purposes of reliability or functional safety. In such cases, integrators may introduce additional layers of error injection, detection, and correction logic surrounding SRAMs. The addition of such logic is transparent to the correct function of Caliptra, and removes integrator dependency on Caliptra for error logging or injection.
-
-Note that the example assumes that data and ECC codes are in non-deterministic bit-position in the exposed SRAM interface bus. Accordingly, redundant correction coding is shown in the integrator level logic (i.e., integrator\_ecc(calitpra\_data, caliptra\_ecc)). If the Caliptra data and ECC are deterministically separable at the Caliptra interface, the integrator would have discretion to store the ECC codes directly and calculate integrator ECC codes for the data alone.
-
-*Figure 8: Example machine check reliability implementation*
-
-
-
-### Error detection and logging
-
-1. Caliptra IP shall interface to ECC protected memories.
-2. Caliptra IP calculates and applies its own ECC code, which produces a total of 39-bit data written to external or INTEGRATOR instantiated SRAMs.
-3. Each 39-bit bank memory internally calculates 8-bit ECC on a write and stores 47 bits of data with ECC into SRAM.
-4. On read access syndrome is calculated based on 39-bit data.
-5. If parity error is detected and syndrome is valid, then the error is deemed single-bit and correctable.
-6. If no parity error is detected but syndrome == 0 or the syndrome is invalid, the error is deemed uncorrectable.
-7. On both single and double errors, the read data is modified before being returned to Caliptra.
-8. Since single-bit errors shall be corrected through INTEGRATOR instantiated logic, Caliptra never sees single-bit errors from SRAM.
-9. Double-bit or uncorrectable errors would cause unpredictable data to be returned to Caliptra. Since this condition shall be detected and reported to MCRIP, there is no concern or expectation that Caliptra will operate correctly after a double error.
-10. On detection, single errors are reported as transparent to MCRIP, double errors are reported as fatal.
-11. Along with error severity, MCRIP logs physical location of the error.
-12. After MCRIP logs an error, it has a choice to send out in-band notification to an external agent.
-13. MCRIP logs can be queried by SoC software.
-
-### Error injection
-
-1. MCRIP supports two error injection modes: intrusive and non-intrusive.
-2. Intrusive error injection:
- 1. Can force a single or double error to be injected, which would result in incorrect data to be returned on read access.
- 2. The intrusive error injection mode is disabled in Production fused parts via Security State signal.
-3. Non-intrusive error injection:
- 1. Allows external software to write into MCRIP error log registers.
- 2. The non-intrusive error injection does not interfere with the operation of memories.
- 3. The non-intrusive error injection is functional in Production fused parts.
-
-### Caliptra error and recovery flow
-
-1. Caliptra Stuck:
- 1. SoC BC timeout mechanism with 300us timeout.
-2. Caliptra reports non-fatal error during boot flow:
- 1. cptra\_error\_non\_fatal is an output Caliptra signal, which shall be routed to SoC interrupt controller.
- 2. SoC can look at the Caliptra non-fatal error register for error source.
- 3. Assume Caliptra can report a non-fatal error at any time.
- 4. SoC should monitor the error interrupt or check it before sending any mailbox command.
- 5. In the event of a non-fatal error during boot (that is, prior to a ready for RT signal), SoC should enter recovery flow and attempt to boot again using alternate boot part/partition.
- 6. If SoC sees that a non-fatal error has occurred AFTER receiving the ready for RT signal, SoC may attempt to recover Caliptra by executing the “Run Self-Test” mailbox command (not yet defined).
- 7. If this command completes successfully, SoC may continue using Caliptra as before.
- 8. If this command is unsuccessful, Caliptra is in an error state for the remainder of the current boot.
- 9. Non-fatal ECC errors are never reported by Caliptra; SoC needs to monitor MCRIP for non-fatal Caliptra ECC errors.
-3. Caliptra reports fatal error during boot flow:
- 1. cptra\_error\_fatal is an output Caliptra signal, which shall be routed to SoC interrupt controller.
- 2. SoC can look at the Caliptra fatal error register for error source.
- 3. Assume Caliptra can report a fatal error at any time.
- 4. Fatal errors are generally hardware in nature. SoC may attempt to recover by full reset of the entire SoC, or can move on and know that Caliptra will be unavailable for the remainder of the current boot.
- 5. We cannot assume that uncorrectable errors will be correctly detected by Caliptra, ECC fatal errors shall be reported by SOC MCRIP.
-
-# SoC integration requirements
-
-The following table describes SoC integration requirements.
-
-*Table 17: SoC integration requirements*
-
-| Category | Requirement | Definition of done | Rationale |
-| :--------- | :--------- | :--------- | :--------- |
-| Deobfuscation Key | SoC backend flows shall generate deobfuscation key with appropriate NIST compliance as dictated in the Caliptra RoT specification. | Statement of conformance | Required by UDS and Field Entropy threat model |
-| Deobfuscation Key | If not driven through PUF, SoC backend flows shall ECO the deobfuscation key before tapeout. | Statement of conformance | Required by UDS and Field Entropy threat model |
-| Deobfuscation Key | Rotation of the deobfuscation key (if not driven through PUF) between silicon steppings of a given product (for example, A0 vs. B0 vs. PRQ stepping) is dependent on company-specific policies. | Statement of conformance | Required by UDS and Field Entropy threat model |
-| Deobfuscation Key | SoC backend flows should not insert deobfuscation key flops into the scan chain. | Synthesis report | Required by UDS and Field Entropy threat model |
-| Deobfuscation Key | For defense in depth, it is strongly recommended that debofuscation key flops are not on the scan chain.
Remove the following signals from the scan chain:
cptra_scan_mode_Latched_d
cptra_scan_mode_Latched_f
field_storage.internal_obf_key | Statement of conformance | Caliptra HW threat model |
-| DFT | Before scan is enabled (separate signal that SoC implements on scan insertion), SoC shall set Caliptra's scan_mode indication to '1 to allow secrets/assets to be flushed. | Statement of conformance | Required by Caliptra threat model |
-| DFT | Caliptra’s TAP should be a TAP endpoint. | Statement of conformance | Functional requirement |
-| Mailbox | SoC shall provide an access path between the mailbox and the application CPU complex on SoCs with such complexes (for example, Host CPUs and Smart NICs). See the [Sender Protocol](#sender-protocol) section for details about error conditions. | Statement of conformance | Required for Project Kirkland and TDISP TSM |
-| Fuses | SoC shall burn non-field fuses during manufacturing. Required vs. optional fuses are listed in the architectural specification. | Test on silicon | Required for UDS threat model |
-| Fuses | SoC shall expose an interface for burning field fuses. Protection of this interface is the SoC vendor’s responsibility. | Test on silicon | Required for Field Entropy |
-| Fuses | SoC shall write fuse registers and fuse done via immutable logic or ROM code. | Statement of conformance | Required for Caliptra threat model |
-| Security State | SoC shall drive security state wires in accordance with the SoC's security state. | Statement of conformance | Required for Caliptra threat model |
-| Security State | If SoC is under debug, then SoC shall drive debug security state to Caliptra. | Statement of conformance | Required for Caliptra threat model |
-| Resets and Clocks | SoC shall start input clock before caliptra_pwrgood assertion. | Statement of conformance | Functional |
-| Resets and Clocks | SoC reset logic shall assume reset assertions are asynchronous and deassertions are synchronous. | Statement of conformance | Functional |
-| Resets and Clocks | SoC shall ensure Caliptra's powergood is the SoC's own powergood. | Statement of conformance | Required for Caliptra threat model |
-| TRNG | SoC shall either provision Caliptra with a dedicated TRNG or shared TRNG. | Statement of conformance | Required for Caliptra threat model and Functional |
-| TRNG | SoC shall provision the Caliptra embedded TRNG with an entropy source if that is used (vs. SoC-shared TRNG API support). | Statement of conformance | Functional |
-| TRNG | If the TRNG is shared, then upon TRNG_REQ, SoC shall use immutable logic or code to program Caliptra's TRNG registers. | Statement of conformance | Required for Caliptra threat model and Functional |
-| SRAMs | SoC shall ensure timing convergence with 1-cycle read path for SRAMs. | Synthesis report | Functional |
-| SRAMs | SoC shall size SRAMs to account for SECDED. | Statement of conformance | Functional |
-| SRAMs | SoC shall write-protect fuses that characterize the SRAM. | Statement of conformance | Required for Caliptra threat model |
-| SRAMs | SoC shall ensure SRAM content is only destroyed on powergood cycling. | Statement of conformance | Functional (Warm Reset, Hitless Update) |
-| SRAMs | SoC shall only perform SRAM repair on powergood events and prior to caliptra_rst_b deassertion. | Statement of conformance | Functional (Warm Reset, Hitless Update) |
-| Backend convergence | Caliptra is validated and backend converged at 400MHz and at process nodes - TSMC 5nm, -- \ | | Functional |
-| Power saving | Caliptra clock gating shall be controlled by Caliptra firmware alone. SoC is provided a global clock gating enable signal (and a register) to control. | | Required for Caliptra threat model |
-| Power saving | SoC shall not power-gate Caliptra independently of the entire SoC. | Statement of conformance | Required for Caliptra threat model |
-| PAUSER | SoC shall drive PAUSER input in accordance with the IP integration spec. | Statement of conformance | ? |
-| Error reporting | SoC shall report Caliptra error outputs. | Statement of conformance | Telemetry and monitoring |
-| Error reporting | SoC shall only recover Caliptra fatal errors via SoC power-good reset. | Statement of conformance | Required for Caliptra threat model |
-| TRNG PAUSER Programming rules | If SoC doesn’t program the CPTRA_TRNG_PAUSER_LOCK\[LOCK\], then Caliptra HW will not accept TRNG data from any SoC entity. | Security | Required for Caliptra threat model |
-| TRNG PAUSER Programming rules | If SoC programs CPTRA_TRNG_VALID_PAUSER and sets CPTRA_TRNG_PAUSER_LOCK\[LOCK\], then Caliptra HW will accept TRNG data only from the entity that is programmed into the PAUSER register. | Security | Required for Caliptra threat model |
-| TRNG PAUSER Programming rules | It is strongly recommended that these PAUSER registers are either set at integration time through integration parameters or be programmed by the SoC ROM before any mutable FW or ROM patches are absorbed. | Security | Required for Caliptra threat model |
-| MAILBOX PAUSER programming rules | 5 PAUSER attribute registers are implemented at SoC interface. | Security | Required for Caliptra threat model |
-| MAILBOX PAUSER programming rules | At boot time, a default SoC or PAUSER can access the mailbox. The value of this PAUSER is an integration parameter, CPTRA_DEF_MBOX_VALID_PAUSER. | Security | Required for Caliptra threat model |
-| MAILBOX PAUSER programming rules | The value of CPTRA_MBOX_VALID_PAUSER\[4:0\] register can be programmed by SoC. After it is locked, it becomes a valid PAUSER for accessing the mailbox. | Security | Required for Caliptra threat model |
-| MAILBOX PAUSER programming rules | Alternatively, CPTRA_SET_MBOX_PAUSER_INTEG parameter can be set along with the corresponding CPTRA_MBOX_VALID_PAUSER parameter at integration time. | Security | Required for Caliptra threat model |
-| MAILBOX PAUSER programming rules | SoC logic (ROM, HW) that is using the Caliptra mailbox right out of cold reset, without first configuring the programmable mailbox PAUSER registers, must send the mailbox accesses with the default PAUSER, CPTRA_DEF_MBOX_VALID_PAUSER. | Security | Required for Caliptra threat model |
-| MAILBOX PAUSER programming rules | For CPTRA_MBOX_VALID_PAUSER\[4:0\], the corresponding lock bits MUST be programmed to ‘1. This enables the mailbox to accept transactions from non-default PAUSERS. | Security | Required for Caliptra threat model |
-| MAILBOX PAUSER programming rules | It is strongly recommended that these PAUSER registers are either set at integration time through integration parameters or be programmed by the SoC ROM before any mutable FW or ROM patches are applied. | Security | Required for Caliptra threat model |
-| FUSE PAUSER programming rules | 1 PAUSER attribute register is implemented at SoC interface: CPTRA_FUSE_VALID_PAUSER. | | |
-| FUSE PAUSER programming rules | CPTRA_FUSE_PAUSER_LOCK locks the programmable valid pauser register, and marks the programmed value as valid. | | |
-| FUSE PAUSER programming rules | Integrators can choose to harden the valid pauser for fuse access by setting the integration parameter, CPTRA_FUSE_VALID_PAUSER, to the desired value in RTL, and by setting CPTRA_SET_FUSE_PAUSER_INTEG to 1. | | |
-| GLS FEV | GLS FEV must be run to make sure netlist and RTL match and none of the countermeasures are optimized away. See the following table for example warnings from synthesis runs to resolve through FEV | GLS simulations pass | Functional requirement |
-
-*Table 18: Caliptra synthesis warnings for FEV evaluation*
-
-| Module | Warning | Line No. | Description |
-| :--------- | :--------- | :--------- | :--------- |
-| sha512_acc_top | Empty netlist for always_comb | 417 |Unused logic (no load)|
-| ecc_scalar_blinding | Netlist for always_ff block does not contain flip flop | 301 |Output width is smaller than internal signals, synthesis optimizes away the extra internal flops with no loads|
-| sha512_masked_core | "masked_carry" is read before being assigned. Synthesized result may not match simulation | 295, 312 ||
-| ecc_montgomerymultiplier | Netlist for always_ff block does not contain flip flop | 274, 326 |Output width is smaller than internal signals, synthesis optimizes away the extra internal flops with no loads|
-| Multiple modules | Signed to unsigned conversion occurs | ||
-
-# CDC analysis and constraints
-
-Clock Domain Crossing (CDC) analysis is performed on the Caliptra core IP. The following are the results and recommended constraints for Caliptra integrators using standard CDC analysis EDA tools.
-
-In an unconstrained environment, several CDC violations are anticipated. CDC analysis requires the addition of constraints to identify valid synchronization mechanisms and/or static/pseudo-static signals.
-
-## Analysis of missing synchronizers
-* All of the signals, whether single-bit or multi-bit, originate from the rvjtag\_tap module internal register on TCK clock, and the Sink/Endpoint is the rvdff register, which is in CalitpraClockDomain clock.
-* JTAG does a series of “jtag writes” for each single “register write”.
-* We only need to synchronize the controlling signal for this interface.
-* Inside the dmi\_wrapper, the dmi\_reg\_en and dmi\_reg\_wr\_en comes from dmi\_jtag\_to\_core\_sync, which is a 2FF synchronizer.
-
-The following code snippet and schematic diagram illustrate JTAG originating CDC violations.
-
-*Figure 9: Schematic diagram and code snippet showing JTAG-originating CDC violations*
-
-
-
-
-
-## CDC analysis conclusions
-* Missing synchronizers appear to be the result of “inferred” and/or only 2-FF instantiated synchronizers.
- * dmi\_jtag\_to\_core\_sync.v contains inferred 2FF synchronizers on the control signals “dmi\_reg\_wr\_en” and “dmi\_reg\_rd\_en”.
- * 2FF synchronizer inferences are considered non-compliant and should be replaced by an explicitly instantiated synchronization module, which is intended to be substituted on a per-integrator basis.
- * cdc report scheme two\_dff -severity violation
-* Multi-bit signals are effectively pseudo-static and are qualified by synchronized control qualifiers.
- * Pseudo-static: wr\_data, wr\_addr
- * cdc signal reg\_wr\_data -module dmi\_wrapper -stable
- * cdc signal reg\_wr\_addr -module dmi\_wrapper -stable
-* The core clock frequency must be at least twice the TCK clock frequency for the JTAG data to pass correctly through the synchronizers.
-
-## CDC constraints
-* cdc report scheme two\_dff -severity violation
-* cdc signal reg\_wr\_data -module dmi\_wrapper -stable
-* cdc signal reg\_wr\_addr -module dmi\_wrapper -stable
-
-# Synthesis findings
-
-Synthesis experiments have so far found the following:
-* Design converges at 400MHz 0.72V using a cutting edge TSMC process.
-* Design converges at 100MHz using TSMC 40nm process.
-
-Note: Any synthesis warnings of logic optimization must be reviewed and accounted for.
-
-# Netlist synthesis data
-
-The following table illustrates representative netlist synthesis results using industry standard EDA synthesis tools and tool configurations.
-
-These metrics are inclusive of VeeR core, Caliptra logic, imem/dmem RAM, ROM.
-
-The area is expressed in units of square microns.
-
-The target foundry technology node is an industry standard, moderately advanced technology node as of 2023 September.
-
-*Table 19: Netlist synthesis data*
-
-| **IP Name** | **Date** | **Path Group** | **Target Freq** | **QoR WNS** | **QoR Achieveable Freq** |
-| :--------- | :--------- | :--------- | :--------- | :--------- | :--------- |
-| CALIPTRA_WRAPPER | 6/15/2023 | CALIPTRACLK | 500MHz | -15.93 | 496MHz |
-| CALIPTRA_WRAPPER | 6/15/2023 | JTAG_TCK | 100MHz | 4606.5 | 100MHz |
-| CALIPTRA_WRAPPER | 6/15/2023 | clock_gating_default | 500MHz | 26.56 | 500MHz |
-| CALIPTRA_WRAPPER | 6/15/2023 | io_to_io | 500MHz | -599.82 | 385MHz |
-| CALIPTRA_WRAPPER | 6/15/2023 | io_to_flop | 500MHz | 0.25 | 500MHz |
-| CALIPTRA_WRAPPER | 6/15/2023 | flop_to_io | 500MHz | -627.58 | 381MHz |
-
-| **IP Name** | **Date** | **Stdcell Area** | **Macro Area** | **Memory Area** | **Total Area** | **Flop Count** | **No Clock Regs/Pins Count** | **FM Status** | **FM Eqv Pts** | **FM Non-Eqv Pts** | **FM Abort Pts** | **FM FM**
**Non-Comp** **Pts** |
-| :--------- | :--------- | :--------- | :--------- | :--------- | :--------- | :--------- | :--------- | :--------- | :--------- | :--------- | :--------- | :--------- |
-| CALIPTRA_WRAPPER | 10/4/2023 | 89279 | 7872 | 239937 | 337088 | 45601 | 31 | SUCCEEDED | 156211 | 0 | 0 | 0 |
-
-# LINT rules
-
-TODO 0p5: This is a WIP list
-
-## Recommended LINT rules
-
-The following LINT rules are the recommended minimum set for standalone analysis of Caliptra IP. The same set is recommended as a minimum subset that may be applied by Caliptra integrators.
-
-Error: "x" in casez statements not allowed
-
-Error: All instance inputs must be driven
-
-Error: An event variable is declared but never triggered
-
-Error: Bit truncation hazard; LHS/RHS truncation of extra bits
-
-Error: Blocking and non-blocking assignment to a signal/variable detected
-
-Error: Case expression width mismatch; case expression width does not match case select expression width
-
-Error: Combinational loops detected
-
-Error: Constant value clock pin of sequential instance
-
-Error: Detected a logical/scalar operation on a vector
-
-Error: Detected that a tristate is used below top-level of design
-
-Error: Detected always or process constructs that do not have an event control
-
-Error: Detected arithmetic comparison operator with unequal length
-
-Error: Detected conversion of unsigned (reg type) to integer
-
-Error: Detected floating or unconnected inout port of an instance
-
-Error: Detected loop step statement variables incorrectly incremented or decremented
-
-Error: Detected nonblocking assignment in a combinational always block
-
-Error: Detected reset or set used both synchronously and asynchronously
-
-Error: Detected signal read inside combinational always block missing from sensitivity list
-
-Error: Detected tri-state 'Z' or '?' value used in assign or comparison
-
-Error: Detected two state data type signals; must support 4 state data type
-
-Error: Detected undriven but loaded input of an instance
-
-Error: Detected undriven but loaded net is detected
-
-Error: Detected undriven but loaded output port of module
-
-Error: Detected undriven output pins connected to instance input
-
-Error: Detected unequal length operands in the bit-wise logical, arithmetic, and ternary operators
-
-Error: Detected unpacked structure declaration outside the package
-
-Error: Duplicate conditions of a case, unique-case, or priority-case
-
-Error: Function return does not set all bits of return variable
-
-Error: Inout port is not read or assigned
-
-Error: Instance pin connections must use named-association rather than positional association
-
-Error: LHS or RHS mismatch hazard; multi-bit expression assigned to single bit signal
-
-Error: Latch inference not permitted
-
-Error: Must declare enum base type explicitly as sized logic type
-
-Error: Negative or enum array index detected
-
-Error: Non-synthesizable construct; functions of type real detected
-
-Error: Non-synthesizable construct; repeat statement
-
-Error: Non-synthesizable construct; delays ignored by synthesis tools
-
-Error: Non-synthesizable construct; modelling style where clock and reset cannot be inferred in sequential inference
-
-Error: Non-synthesizable construct; states are not updated on the same clock phase in sequential inference
-
-Error: Null Ports detected
-
-Error: Port referred before definition
-
-Error: Range index or slice of an array discrepancy
-
-Error: Read before set hazard in blocking assignment signal
-
-Error: Recursive task hazard
-
-Error: Redeclaration of a port range
-
-Error: Text Macro Redefinition TMR
-
-Error: Variable is too short for array index
-
-Error: Identified case constructs without the default or `OTHERS` clause
-
-Fatal: Asynchronous reset inference must have "if" statement as first statement in the block
-
-Fatal: Blocking assignment detected in sequential always block
-
-Fatal: Detected a function or a sub-program sets a global signal or variable
-
-Fatal: Detected a function or a sub-program uses a global signal or variable
-
-Fatal: Detected assignment to input ports
-
-Fatal: Detected edge and non-edge conditions in block sensitivity list
-
-Fatal: Detected variable in which both the edges are used in an event control list
-
-Fatal: Event control detected in RHS of assignment statement
-
-Fatal: Illegal case construct label detected
-
-Fatal: Module instance port connection mismatch width compared to the port definition
-
-Fatal: Non-synthesizable construct; case equal operators (===) (!==) operators may not be synthesizable
-
-Fatal: Non-synthesizable construct; detected real operands that are used in logical comparisons
-
-Fatal: Non-synthesizable construct; detected real variables that are unsynthesizable
-
-Fatal: Non-synthesizable construct; MOS switches, such as cmos, pmos, and nmos
-
-Fatal: Non-synthesizable construct; disable statements detected
-
-Fatal: Non-synthesizable construct; event control expressions have multiple edges in sequential inference
-
-Fatal: Non-synthesizable construct; event variables
-
-Fatal: Non-synthesizable construct; the tri0 net declarations
-
-Fatal: Non-synthesizable construct; time declarations
-
-Fatal: Non-synthesizable construct; tri1 net declarations
-
-Fatal: Non-synthesizable construct; trireg declarations
-
-Fatal: The 'default' or 'others' must be last case in a case statement
-
-# Terminology
-
-The following terminology is used in this document.
-
-*Table 20: Terminology*
-
-
-| Abbreviation | Description |
-| :--------- | :--------- |
-| AHB | AMBA Advanced High-Performance Bus |
-| APB | AMBA Advanced Peripheral Bus |
-| AES | Advanced Encryption Standard |
-| BMD | Boot Media Dependent |
-| BMI | Boot Media Integrated |
-| ECC | Elliptic Curve Cryptography |
-| ECO | Engineering Change Order (used to implement logic changes to a hardware design post-synthesis) |
-| QSPI | Quad Serial Peripheral Interface |
-| RISC | Reduced Instruction Set Computer |
-| SHA | Secure Hashing Algorithm |
-| SPI | Serial Peripheral Interface |
-| UART | Universal Asynchronous Receiver Transmitter |
diff --git a/docs/Caliptra_Integration_Specification.pdf b/docs/Caliptra_Integration_Specification.pdf
new file mode 100755
index 0000000000000000000000000000000000000000..0cc3f9ebe02bede7acf9e1a061a5b6a7042b8c54
GIT binary patch
literal 1191923
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�Sye@5?G&qVP>uR
z(zXi2%6r`dGB=E(|GqlHx=*LH68SIs>J_)6F&Ir`5R!11D*Zx3$}t+5q;QAts#>A3
zBt(eCBJCX(($TJl06T}9K@BPxU)-#D!eINFUh@ZZo@2va%9H0G%v!w9wLgmEwg%3X
zCJ|hBjJ2*8VIxC**KOK!ipXfG%9=X)mE^(|xCs9h+E=&UAlG=f`a-%OTXwZN+sVy<
zOSr($4o*=3vhI+IA{KT8W3A
za$-439l7D2mgs>`6rT&q;6z=k=jRbP**&$|Jk>MTRV7&I}Z
zBtIakHh+|`wdh2=rPMs>&T)i?1x=yDl;R6}%8m4=S?{vyv`|Fa0rRc_N@m9e(Jyh`
zFkqbjwaF)XuvH=s@-0T13STAuIp%PguFnzcV3Fi<
z3zOrDlx72d=KYr+wVx%ryNId><;vd3vvykYon)+$1~y#t<(~rW&9mK{z=$&###~|T
z%L!Nb&skF4Xd#Tb2@<3%UyldwGo*R5jPP_iyo?@7gqUm-+qa*hTafZ6=y7H~7}A|d
zulB${I<>Q=uJWm4ti+~s-3_j0w*8*lSFXV4?rXfNLkQ$i!Ti}=MJo+LiH!USiXNXz
zAAHnWt+oDMi`nSP^*hyT;`XfEO2lB5W&_{yXUwLr5Bhcl-4(5g+$U{Co^>_TRIK$2
z4_EFd3DEfam2|jQwq-7)PovX6f3#>_WxrIOvp*PTyLZ#{YYecwa74QK;t`%Yp3)Df
zhf`Mt`X*E^J3cl$Ql!h@+ff!oLeR~X4zVL=q3AfT0;
z+ud)N?D(gFrZ!;O#yP*P`)ML^3hA>MvTOYgSU$mp;fN);9tHNwhM}w{wAH2GzQ-q;
z=s@|1-;zgLQxgdR#!$b1H2(I1;-3Md2FMf2TEb!4#yAXwaAR@^>e5zP@wRf=P)16^
zNhm*?wQu@RK?s@l4-LXAo}tz-iR-{fbr@x#%Q<4vJgvGXrPF6~V&y5J9X@OG@yX~I
zVuI%@;247?>W-@!+-a&W%2(5gCUg(bGFxY65I$lKU&;lg)&RWY8Y}K4FDZ&XR$)jO
z-1TT4-HPb+J$~YjxVwjjYoq(Ll6jR96NhMtx&{kgSJQ%LSg(E$lEG!^wer
z>}`(4Y!vyk3Ih?Nxkqw-BS>{hFf)bqEQTB^oE_|IuQ~Il(MFRz*b6tU^$Ie|rNSvC
zU8|%nmQUDxANxqUt!Lmi0#7m~#BX<0eks?ito;N(a-+C;g7nAP-KvQDH5tuBOtuXc
z-g^4qu_k%MhUHlJc%#YBWb6u#Cw0qNPFP&dXxgO7L;OehuiwPk2Y6V_?F{YjG`Z&T
zZf-6Z%E1Jg@R`Xt74#B2#L-N?O5_3tMR+UOFvYH7p?|dX#fKi!=rDb-TXekGNI`3;
z@P-iKDR?g5lo?&+_zM^q1|d1iO4D&%OPlLTTkW~2syXq3%vr@G5eccH-W?+=_x+ad!pS;
zJ)>BlV*+|JhzVG_3)#d*F~>^545#(KvnE^?juOsC&ApNtk;WQgZ{5rWNvT-P)u_*K
z)a&0>mwePK9R1lmdR$FlIb0ooiGMXlnsA#eJ7#+_v^`%&p~C=9nKmmE62@L72lYMb
zP&~E8+fSqUMM78B`?zC{740$xV39#9WnXbB(~?_>3l01l{H6NBBtwVa`u^O8!q6Yx
z-wO2CfRYntjNU^8_%z$;e8|ASkpb7@gzEzFeQ0J@{P*&NNWmXgv`0<@<@)X7!XB1>
zL`Pv?zW_^aL44h?G&<>K{n87X-FvvQ%&6l9Wzr(T!oGXyA8KCP=Y;F7C9?Or45^Q8
z4ztKCEW(7*{$~vkzPxk4vnfV)117LWGNN(nGb&~%&cc81^WUpn7;ykSVk@XKr
zRMGhcvexot2v!$LjIYTCirJW)WS`$*s$!Wuv)r|s)|NMFjISRlHqpgot>1~fHth9W
zf3a0�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