diff --git a/.github/scripts/gdb_test.sh b/.github/scripts/gdb_test.sh index 90eb5ac6b..20f783040 100755 --- a/.github/scripts/gdb_test.sh +++ b/.github/scripts/gdb_test.sh @@ -5,6 +5,17 @@ SIM_LOG=`realpath sim.log` OPENOCD_LOG=`realpath openocd.log` +GCC_PREFIX=riscv64-unknown-elf + +# Ensure that RISC-V toolchain is installed +if ! which ${GCC_PREFIX}-gcc >/dev/null; then + GCC_PREFIX=riscv32-unknown-elf +fi +if ! which ${GCC_PREFIX}-gcc >/dev/null; then + echo "RISC-V toolchain not found, please refer to https://github.com/chipsalliance/caliptra-rtl?tab=readme-ov-file#riscv-toolchain-installation for more details." + exit 1 +fi +export GCC_PREFIX set +e diff --git a/.github/workflows/build-test-verilator.yml b/.github/workflows/build-test-verilator.yml index 53d8b407c..c27e7880d 100644 --- a/.github/workflows/build-test-verilator.yml +++ b/.github/workflows/build-test-verilator.yml @@ -18,7 +18,7 @@ env: SCCACHE_GHA_CACHE_TO: sccache-verilator-10000 SCCACHE_GHA_CACHE_FROM: sccache-verilator- # Change this to a new random value if you suspect the cache is corrupted - SCCACHE_C_CUSTOM_CACHE_BUSTER: f3e6951f0c1d + SCCACHE_C_CUSTOM_CACHE_BUSTER: f3e6951f0c1e jobs: build_tools: @@ -101,9 +101,8 @@ jobs: if: steps.riscv_restore.outputs.cache-hit != 'true' run: | # Building from source takes around 6.65 GB of disk and download size - wget -O toolchain.tar.gz https://github.com/stnolting/riscv-gcc-prebuilt/releases/download/rv64imc-3.0.0/riscv64-unknown-elf.gcc-12.1.0.tar.gz - mkdir /opt/riscv - tar -xzf toolchain.tar.gz -C /opt/riscv/ + wget -O toolchain.tar.gz https://github.com/chipsalliance/caliptra-tools/releases/download/gcc-v12.1.0/riscv64-unknown-elf.gcc-12.1.0.tar.gz + tar -xzf toolchain.tar.gz -C /opt/ - name: Save riscv dir uses: actions/cache/save@v3 diff --git a/.github/workflows/interactive-debugging.yml b/.github/workflows/interactive-debugging.yml index 8415e094d..124e1d5f4 100644 --- a/.github/workflows/interactive-debugging.yml +++ b/.github/workflows/interactive-debugging.yml @@ -22,7 +22,7 @@ jobs: SCCACHE_GHA_CACHE_TO: sccache-verilator-10000 SCCACHE_GHA_CACHE_FROM: sccache-verilator- # Change this to a new random value if you suspect the cache is corrupted - SCCACHE_C_CUSTOM_CACHE_BUSTER: f3e6951f0c1d + SCCACHE_C_CUSTOM_CACHE_BUSTER: f3e6951f0c1e steps: - name: Restore sccache binary @@ -185,9 +185,8 @@ jobs: - name: Install Risc V Toolchain run: | # Building from source takes around 6.65 GB of disk and download size - wget -O toolchain.tar.gz https://github.com/stnolting/riscv-gcc-prebuilt/releases/download/rv64imc-3.0.0/riscv64-unknown-elf.gcc-12.1.0.tar.gz - mkdir /opt/riscv - tar -xzf toolchain.tar.gz -C /opt/riscv/ + wget -O toolchain.tar.gz https://github.com/chipsalliance/caliptra-tools/releases/download/gcc-v12.1.0/riscv64-unknown-elf.gcc-12.1.0.tar.gz + tar -xzf toolchain.tar.gz -C /opt/ - name: Install dependencies run: | @@ -268,9 +267,8 @@ jobs: - name: Install Risc V Toolchain run: | # Building from source takes around 6.65 GB of disk and download size - wget -O toolchain.tar.gz https://github.com/stnolting/riscv-gcc-prebuilt/releases/download/rv64imc-3.0.0/riscv64-unknown-elf.gcc-12.1.0.tar.gz - mkdir /opt/riscv - tar -xzf toolchain.tar.gz -C /opt/riscv/ + wget -O toolchain.tar.gz https://github.com/chipsalliance/caliptra-tools/releases/download/gcc-v12.1.0/riscv64-unknown-elf.gcc-12.1.0.tar.gz + tar -xzf toolchain.tar.gz -C /opt/ - name: Download Verilator binaries uses: actions/download-artifact@v3 diff --git a/README.md b/README.md index 3c86dc341..ec40a8b0c 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
limitations under the License.*_
# **Caliptra Hands-On Guide** # -_*Last Update: 2023/10/17*_ +_*Last Update: 2024/01/17*_ ## **Tools Used** ## @@ -144,12 +144,12 @@ Verilog file lists are generated via VCS and included in the config directory fo ## **Simulation Flow** ## ### Caliptra Top VCS Steps: ### -1. Setup tools, add to PATH (ensure riscv64-unknown-elf-gcc is also available) +1. Setup tools, add to PATH (ensure RISC-V toolchain is also available) 2. Define all environment variables above - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME - See [Regression Tests](#Regression-Tests) for information about available tests. 3. Create a run folder for build outputs (and cd to it) -4. [OPTIONAL] By default, this run flow will use the riscv64 toolchain to compile test firmware (according to TESTNAME) into program.hex, iccm.hex, dccm.hex, and mailbox.hex. As a first pass, integrators may alternatively use the pre-built hexfiles for convenience (available for [iccm_lock](src/integration/test_suites/iccm_lock) test). To do this, copy [iccm_lock.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) to the run directory and rename to `program.hex`. [dccm.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) should also be copied to the run directory, as-is. Use `touch iccm.hex mailbox.hex` to create empty hex files, as these are unnecessary for `iccm_lock` test. +4. [OPTIONAL] By default, this run flow will use the RISC-V toolchain to compile test firmware (according to TESTNAME) into program.hex, iccm.hex, dccm.hex, and mailbox.hex. As a first pass, integrators may alternatively use the pre-built hexfiles for convenience (available for [iccm_lock](src/integration/test_suites/iccm_lock) test). To do this, copy [iccm_lock.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) to the run directory and rename to `program.hex`. [dccm.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) should also be copied to the run directory, as-is. Use `touch iccm.hex mailbox.hex` to create empty hex files, as these are unnecessary for `iccm_lock` test. 5. Invoke `${CALIPTRA_ROOT}/tools/scripts/Makefile` with target 'program.hex' to produce SRAM initialization files from the firmware found in `src/integration/test_suites/${TESTNAME}` - E.g.: `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile program.hex` - NOTE: TESTNAME may also be overridden in the makefile command line invocation, e.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=iccm_lock program.hex` @@ -165,13 +165,13 @@ Verilog file lists are generated via VCS and included in the config directory fo 8. Simulate project with `caliptra_top_tb` as the top target ### Caliptra Top Verilator Steps: ### -1. Setup tools, add to PATH (ensure Verilator, GCC, and riscv64-unknown-elf-gcc are available) +1. Setup tools, add to PATH (ensure Verilator, GCC, and RISC-V toolchain are available) 2. Define all environment variables above - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME - See [Regression Tests](#Regression-Tests) for information about available tests. 3. Create a run folder for build outputs - Recommended to place run folder under `${CALIPTRA_WORKSPACE}/scratch/$USER/verilator/` -4. [OPTIONAL] By default, this run flow will use the riscv64 toolchain to compile test firmware (according to TESTNAME) into program.hex, iccm.hex, dccm.hex, and mailbox.hex. As a first pass, integrators may alternatively use the pre-built hexfiles for convenience (available for `iccm_lock` test). To do this, copy `iccm_lock.hex` to the run directory and rename to `program.hex`. `dccm.hex` should also be copied to the run directory, as-is. Use `touch iccm.hex mailbox.hex` to create empty hex files, as these are unnecessary for `iccm_lock` test. +4. [OPTIONAL] By default, this run flow will use the RISC-V toolchain to compile test firmware (according to TESTNAME) into program.hex, iccm.hex, dccm.hex, and mailbox.hex. As a first pass, integrators may alternatively use the pre-built hexfiles for convenience (available for `iccm_lock` test). To do this, copy `iccm_lock.hex` to the run directory and rename to `program.hex`. `dccm.hex` should also be copied to the run directory, as-is. Use `touch iccm.hex mailbox.hex` to create empty hex files, as these are unnecessary for `iccm_lock` test. 5. Run Caliptra/tools/scripts/Makefile, which provides steps to run a top-level simulation in Verilator - Example command: `make -C -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=${TESTNAME} debug=1 verilator` diff --git a/Release_Notes.md b/Release_Notes.md index 20bbbef97..60d949a03 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/12/08*_ +_*Last Update: 2024/01/18*_ -## Rev 1p0-rc2 ## +## Rev 1p0 ## -### Rev 1p0-rc2 release date: 2023/12/13 (1p0 version pending ROM release for official declaration) ### +### Rev 1p0 release date: 2024/01/18 ### - Caliptra Hardware Specification: Markdown conversion - Caliptra Integration specification update with synthesis warnings and jtag tck requirement - Caliptra README updates to clarify test cases and running with VCS diff --git a/docs/CaliptraHardwareSpecification.md b/docs/CaliptraHardwareSpecification.md index a40a39719..a69a2b219 100644 --- a/docs/CaliptraHardwareSpecification.md +++ b/docs/CaliptraHardwareSpecification.md @@ -2,7 +2,7 @@

Caliptra Hardware Specification

-

Version 1.0-rc2

+

Version 1.0

@@ -16,11 +16,7 @@ This document provides definitions and requirements for a Caliptra cryptographic # Caliptra Core -The following figure shows the Caliptra Core. - -*Figure 1: Caliptra Block Diagram* - -![](./images/Caliptra_HW_diagram.png) +For information on the Caliptra Core, see the [High level architecture](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html#high-level-architecture) section of [Caliptra: A Datacenter System on a Chip (SoC) Root of Trust (RoT)](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html). ## Boot FSM @@ -28,7 +24,7 @@ The Boot FSM detects that the SoC is bringing Caliptra out of reset. Part of thi The following figure shows the initial power-on arc of the Mailbox Boot FSM. -*Figure 2: Mailbox Boot FSM state diagram* +*Figure 1: Mailbox Boot FSM state diagram* ![](./images/HW_mbox_boot_fsm.png) @@ -40,7 +36,7 @@ BOOT\_DONE enables Caliptra reset de-assertion through a two flip-flop synchroni 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* +*Figure 2: Mailbox Boot FSM state diagram for FW update reset* ![](./images/mbox_boot_fsm_FW_update_reset.png) @@ -143,7 +139,8 @@ Software and local interrupts are not implemented in the first generation of Cal #### 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). +Caliptra's RISC-V processor has access to an internal register that allows configuration of the NMI vector. When an NMI occurs, the program counter jumps to the address indicated by the contents of this register. +For more information, see [NMI Vector](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.internal_nmi_vector). #### External interrupts @@ -153,7 +150,7 @@ Errors and notifications are allocated as interrupt events for each component, w 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. +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. The following table shows assignment of interrupt vectors to the corresponding IP block. The illustrated interrupt priority assignment is only an example, and does not correspond with actual priorities assigned in the final Caliptra firmware. These interrupt priorities are used in the validation firmware that tests the RTL, and are defined in [caliptra_defines.h](https://github.com/chipsalliance/caliptra-rtl/blob/main/src/integration/test_suites/includes/caliptra_defines.h). | IP/Peripheral | Interrupt vector | Interrupt priority example
(Increasing, Max 15) | | :-------------------------------------------------- | :--------------- | :---------------------------------------------- | @@ -196,7 +193,7 @@ For more details regarding the register interface to control the WDT, see the [r The following figure shows the two timers. -*Figure 4: Caliptra Watchdog Timer* +*Figure 3: Caliptra Watchdog Timer* ![](./images/WDT.png) @@ -210,7 +207,7 @@ The Caliptra microcontroller communicates with the mailbox through its internal ### 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. +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. See [Caliptra Core](#caliptra-core) for information. 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. @@ -232,7 +229,7 @@ For details, see the [Cryptographic subsystem architecture](#cryptographic-subsy ## 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. +Caliptra includes QSPI and UART peripherals that are used to facilitate alternative operating modes and debug. In the first generation, Caliptra does not support enabling the QSPI interface. 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 @@ -240,7 +237,7 @@ Caliptra implements a QSPI block that can communicate with 2 QSPI devices. This 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* +*Figure 4: QSPI flash controller* ![](./images/QSPI_flash.png) @@ -252,7 +249,7 @@ The structure of a command depends on the device and the command itself. In the 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* +*Figure 5: SPI read transaction segments* ![](./images/SPI_read.png) @@ -272,7 +269,7 @@ QSPI consists of up to four command segments in which the host: The following example shows the QSPI segments. -*Figure 7: QSPI segments* +*Figure 6: QSPI segments* ![](./images/QSPI_segments.png) @@ -307,7 +304,7 @@ CONFIGOPTS.CLKDIV = (400/(2\*100)) -1 = 1 The following figure shows CONFIGOPTS. -*Figure 8: CONFIGOPTS* +*Figure 7: CONFIGOPTS* ![](./images/CONFIGOPTS.png) @@ -355,7 +352,7 @@ Caliptra implements a UART block that can communicate with a serial device that 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* +*Figure 8: UART block* ![](./images/UART_block.png) @@ -365,7 +362,7 @@ Transactions flow through the UART block starting with an AHB-lite write to WDAT 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* +*Figure 9: Serial transmission frame* ![](./images/serial_transmission.png) @@ -396,38 +393,8 @@ The UART block architecture inputs and outputs are described in the following ta ## 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 | | +For more information on the mailbox protocol, see [Mailbox](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraIntegrationSpecification.md#mailbox) in the Caliptra Integration Specification. Mailbox registers accessible to the Caliptra microcontroller are defined in [internal-regs/mbox_csr](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.mbox_csr). + ## Security state @@ -516,7 +483,7 @@ The following applies to the clock gating feature: The following figure shows the timing information for clock gating. -*Figure 11: Clock gating timing* +*Figure 10: Clock gating timing* ![](./images/clock_gating_timing.png) @@ -526,23 +493,23 @@ Caliptra implements a true random number generator (TRNG) block for local use mo 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 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 [External-TRNG REQ HW API](#External-TRNG-REQ-HW-API). The following figure shows the integrated TRNG block. -*Figure 12: Integrated TRNG block* +*Figure 11: Integrated TRNG block* ![](./images/integrated_TRNG.png) The following figure shows the CSRNG block. -*Figure 13: CSRNG block* +*Figure 12: CSRNG block* ![](./images/CSRNG_block.png) The following figure shows the entropy source block. -*Figure 14: Entropy source block* +*Figure 13: Entropy source block* ![](./images/entropy_source_block.png) @@ -606,7 +573,7 @@ These are the top level signals defined in caliptra\_top. The following figure shows the top level signals defined in caliptra\_top. -*Figure 15: caliptra\_top signals* +*Figure 14: caliptra\_top signals* ![](./images/caliptra_top_signals.png) @@ -627,7 +594,7 @@ The following table provides descriptions of the entropy source signals. The following figure shows the entropy source signals. -*Figure 16: Entropy source signals* +*Figure 15: Entropy source signals* ![](./images/entropy_source_signals.png) @@ -685,7 +652,7 @@ Caliptra’s JTAG/TAP should be implemented as a TAP EP. JTAG is open if the deb 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* +*Figure 16: JTAG implementation* ![](./images/JTAG_implementation.png) @@ -706,7 +673,7 @@ The architecture of Caliptra cryptographic subsystem includes the following comp The high-level architecture of Caliptra cryptographic subsystem is shown in the following figure. -*Figure 18: Caliptra cryptographic subsystem TODO: fix this image* +*Figure 17: Caliptra cryptographic subsystem* ![](./images/crypto_subsystem.png) @@ -731,7 +698,7 @@ The message should be padded before feeding to the hash core. The input message 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* +*Figure 18: SHA512 input formatting* ![](./images/SHA512_input.png) @@ -743,7 +710,7 @@ The SHA512 core performs 80 iterative operations to process the hash value of th The SHA512 architecture has the finite-state machine as shown in the following figure. -*Figure 20: SHA512 FSM* +*Figure 19: SHA512 FSM* ![](./images/SHA512_fsm.png) @@ -772,7 +739,7 @@ The SHA512 address map is shown here: [sha512\_reg — clp Reference (chipsallia The following pseudocode demonstrates how the SHA512 interface can be implemented. -*Figure 21: SHA512 pseudocode* +*Figure 20: SHA512 pseudocode* ![](./images/SHA512_pseudo.png) @@ -850,7 +817,7 @@ The total size should be equal to 64 bits, short of a multiple of 512 because th The following figure shows SHA256 input formatting. -*Figure 22: SHA256 input formatting* +*Figure 21: SHA256 input formatting* ![](./images/SHA256_input.png) @@ -862,7 +829,7 @@ The SHA256 core performs 64 iterative operations to process the hash value of th The SHA256 architecture has the finite-state machine as shown in the following figure. -*Figure 23: SHA256 FSM* +*Figure 22: SHA256 FSM* ![](./images/SHA256_fsm.png) @@ -891,7 +858,7 @@ The SHA256 address map is shown here: [sha256\_reg — clp Reference (chipsallia The following pseudocode demonstrates how the SHA256 interface can be implemented. -*Figure 24: SHA256 pseudocode* +*Figure 23: SHA256 pseudocode* ![](./images/SHA256_pseudo.png) @@ -955,25 +922,25 @@ The message should be padded before feeding to the HMAC core. Internally, the i\ 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* +*Figure 24: HMAC input formatting* ![](./images/HMAC_input.png) The following figures show examples of input formatting for different message lengths. -*Figure 26: Message length of 1023 bits* +*Figure 25: Message length of 1023 bits* ![](./images/msg_1023.png) When the message is 1023 bits long, padding is given in the next block along with message size. -*Figure 27: 1 bit padding* +*Figure 26: 1 bit padding* ![](./images/1_bit.png) 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* +*Figure 27: Multi block message* ![](./images/msg_multi_block.png) @@ -984,7 +951,7 @@ Messages with a length greater than 1024 bits are broken down into N 1024-bit bl 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* +*Figure 28: HMAC-SHA-384-192 data flow* ![](./images/HMAC_SHA_384_192.png) @@ -992,7 +959,7 @@ The HMAC core performs the sha2-384 function to process the hash value of the gi The HMAC architecture has the finite-state machine as shown in the following figure. -*Figure 30: HMAC FSM* +*Figure 29: HMAC FSM* ![](./images/HMAC_FSM.png) @@ -1022,7 +989,7 @@ The HMAC address map is shown here: [hmac\_reg — clp Reference (chipsalliance. The following pseudocode demonstrates how the HMAC interface can be implemented. -*Figure 31: HMAC pseudocode* +*Figure 30: HMAC pseudocode* ![](./images/HMAC_pseudo.png) @@ -1142,7 +1109,7 @@ The hardware implementation supports deterministic ECDSA, 384 Bits (Prime Field) Secp384r1 parameters are shown in the following figure. -*Figure 32: Secp384r1 parameters* +*Figure 31: Secp384r1 parameters* ![](./images/secp384r1_params.png) @@ -1150,7 +1117,7 @@ Secp384r1 parameters are shown in the following figure. The ECDSA consists of three operations, shown in the following figure. -*Figure 33: ECDSA operations* +*Figure 32: ECDSA operations* ![](./images/ECDSA_ops.png) @@ -1185,7 +1152,7 @@ The signature (r, s) can be verified by Verify(pubKey ,h ,r, s) considering the The ECC top-level architecture is shown in the following figure. -*Figure 34: ECDSA architecture* +*Figure 33: ECDSA architecture* ![](./images/ECDSA_arch.png) @@ -1223,19 +1190,19 @@ The following pseudocode blocks demonstrate example implementations for KeyGen, #### KeyGen -*Figure 35: KeyGen pseudocode* +*Figure 34: KeyGen pseudocode* ![](./images/keygen_pseudo.png) #### Signing -*Figure 36: Signing pseudocode* +*Figure 35: Signing pseudocode* ![](./images/signing_pseudo.png) #### Verifying -*Figure 37: Verifying pseudocode* +*Figure 36: Verifying pseudocode* ![](./images/verify_pseudo.png) @@ -1301,7 +1268,7 @@ The state machine of HMAC\_DRBG utilization is shown in the following figure, in 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* +*Figure 37: HMAC\_DRBG utilization* ![](./images/HMAC_DRBG_util.png) @@ -1317,7 +1284,7 @@ In SCA random generator state: The data flow of the HMAC\_DRBG operation in keygen operation mode is shown in the following figure. -*Figure 39: HMAC\_DRBG data flow* +*Figure 38: HMAC\_DRBG data flow* ![](./images/HMAC_DRBG_data.png) @@ -1327,14 +1294,20 @@ Test vector leakage assessment (TVLA) provides a robust test using a 𝑡-test. 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* +*Figure 39: TVLA threshold as a function of the number of samples per trace* ![](./images/TVLA_threshold.png) -##### Keygen TVLA -TODO: provide content for this section +##### KeyGen TVLA + +We detected a leakage using TVLA in the HMAC_DRBG algorithm during ECC key generation, based on 150,000 power traces. The leakage originated from a part of the SHA512 function (w_data) that was not fully protected by masking. The same leakage is expected for HMAC operations. + +*Figure 40: seed/nonce-dependent leakage detection using TVLA for ECC keygen after 150,000 traces* + +![](./images/tvla_keygen.png) +This leakage is very unlikely to occur in practice, even though it exists in TVLA results. Therefore, we will address it in the next release. ##### Signing TVLA diff --git a/docs/CaliptraIntegrationSpecification.md b/docs/CaliptraIntegrationSpecification.md index d4a528bc2..1db5c8f2c 100644 --- a/docs/CaliptraIntegrationSpecification.md +++ b/docs/CaliptraIntegrationSpecification.md @@ -2,7 +2,7 @@

Caliptra Integration Specification

-

Version 1.0-rc2

+

Version 1.0

@@ -27,28 +27,20 @@ The blocks described in this document are either obtained from open-source GitHu | 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) | +| 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 1: 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* - -![](./images/Caliptra_HW_diagram.png) - -## 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. +For information on the Caliptra Core, see the [High level architecture](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html#high-level-architecture) section of [Caliptra: A Datacenter System on a Chip (SoC) Root of Trust (RoT)](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html). # SoC interface definition The following figure shows the SoC interface definition. -*Figure 2: SoC Interface Block Diagram* +*Figure 1: SoC Interface Block Diagram* ![](./images/Caliptra_soc_interface_block.png) @@ -73,6 +65,10 @@ The following table describes integration parameters. | 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. | +| USER_ICG | config_defines.svh | If added by an integrator, provides the name of the custom clock gating module that is used in [clk_gate.sv](../src/libs/rtl/clk_gate.sv). USER_ICG replaces the clock gating module, CALIPTRA_ICG, defined in [caliptra_icg.sv](../src/libs/rtl/caliptra_icg.sv). This substitution is only performed if integrators also define TECH_SPECIFIC_ICG. | +| TECH_SPECIFIC_ICG | config_defines.svh | Defining this causes the custom, integrator-defined clock gate module (indicated by the USER_ICG macro) to be used in place of the native Caliptra clock gate module. | +| USER_EC_RV_ICG | config_defines.svh | If added by an integrator, provides the name of the custom clock gating module that is used in the RISC-V core. USER_EC_RV_ICG replaces the clock gating module, TEC_RV_ICG, defined in [beh_lib.sv](../src/riscv_core/veer_el2/rtl/lib/beh_lib.sv). This substitution is only performed if integrators also define TECH_SPECIFIC_EC_RV_ICG. | +| TECH_SPECIFIC_EC_RV_ICG | config_defines.svh | Defining this causes the custom, integrator-defined clock gate module (indicated by the USER_EC_RV_ICG macro) to be used in place of the native RISC-V core clock gate module. | ## Interface @@ -174,8 +170,8 @@ The following tables describe the interface signals. | 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. | +| iTRNG_DATA | 4 | Input | Synchronous to clk | External source mode: Not used.
Internal source mode only: Physical True Random Noise Source (PTRNG for "Number Generator") digital bit stream from SoC, which is sampled when iTRNG_VALID is high. See the [Hardware Specification](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraHardwareSpecification.md#integrated-trng) for details on PTRNG expectations and iTRNG entropy capabilities. | +| iTRNG_VALID | 1 | Input | Synchronous to clk | External source mode: Not used.
Internal source mode only: RNG bit valid. This is valid per transaction. iTRNG_DATA can be sampled whenever this bit is high. The expected iTRNG_VALID output rate is about 50KHz. | ## Architectural registers and fuses @@ -196,7 +192,7 @@ Although fuse values (and the fuse done register) persist across a warm reset, S The following figure shows the reset rules and timing for cold boot flows. -*Figure 3: Reset rules and timing diagram* +*Figure 2: Reset rules and timing diagram* ![](./images/Caliptra_reset_timing.png) @@ -232,7 +228,7 @@ Caliptra firmware internally has the capability to force release the mailbox bas 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 +### Obfuscation 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. @@ -271,7 +267,7 @@ Caliptra in turn also uses the mailbox to pass information back to the SoC. The 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* +*Figure 3: Mailbox Boot FSM state diagram* ![](./images/Caliptra_mbox_boot_FSM.png) @@ -293,7 +289,7 @@ When a mailbox is populated by the SoC, initiation of the operation by writing t 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. \ +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 @@ -318,7 +314,7 @@ Mailboxes are generic data-passing structures with a specific protocol that defi 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* +*Figure 4: Sender protocol flow chart* ![](./images/Caliptra_mbox-sender.png) @@ -341,7 +337,7 @@ Caliptra will not initiate any mailbox commands that require a response from the The following figure shows the receiver protocol flow. -*Figure 6: Receiver protocol flowchart* +*Figure 5: Receiver protocol flowchart* ![](./images/Caliptra_mbox_receiver.png) @@ -484,6 +480,10 @@ Having an interface that is separate from the SoC mailbox ensures that this requ 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. +The ROM and firmware currently time out on the TRNG interface after 250,000 +attempts to read a DONE bit. This bit is set in the architectural registers, as +referenced in 3 in the preceding list. + # SRAM implementation ## Overview @@ -513,7 +513,7 @@ Table 4 indicates the signals contained in the memory interface. Direction is re The following figure shows the SRAM interface timing. -*Figure 7: SRAM interface timing* +*Figure 6: SRAM interface timing* ![](./images/Caliptra_SRAM_interface_timing.png) @@ -542,7 +542,7 @@ This example is applicable to scenarios where an integrator may need control of 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* +*Figure 7: Example machine check reliability implementation* ![](./images/Caliptra_machine_reliability.png) @@ -602,23 +602,31 @@ The following table describes 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 | +| Obfuscation Key | SoC backend flows shall generate obfuscation key with appropriate NIST compliance as dictated in the Caliptra RoT specification. | Statement of conformance | Required by UDS and Field Entropy threat model | +| Obfuscation Key | If not driven through PUF, SoC backend flows shall ECO the obfuscation key before tapeout. | Statement of conformance | Required by UDS and Field Entropy threat model | +| Obfuscation Key | Rotation of the obfuscation 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 | +| Obfuscation Key | SoC backend flows should not insert obfuscation key flops into the scan chain. | Synthesis report | Required by UDS and Field Entropy threat model | +| Obfuscation 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 | +| Obfuscation Key | SoC shall ensure that obfuscation key is available (and wires are stable) before Caliptra reset is de-asserted. | Statement of conformance | Functionality and security | +| Obfuscation Key | SoC shall implement protections for obfuscation key generation logic and protect against debug/sw/scandump visibility.
1. Any flops outside of Caliptra that store obfuscation key or parts of the key should be excluded from scandump.
2. SoC shall ensure that the obfuscation key is sent only to Caliptra through HW wires, and it is not visible anywhere outside of Caliptra. | Statement of conformance | Required for Caliptra 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 | +| Fuses | SoC shall expose an API for programming Field Entropy as described in the architecture documentation. SoC shall ensure that Field Entropy can only be programmed via this API and shall explicitly prohibit burning of discrete Field Entropy bits and re-burning of already burned Field Entropy entries. | Test on silicon | Required for Field Entropy | +| Fuses | SoC shall ensure that any debug read paths for fuses are disabled in PRODUCTION lifecycle state.| Test on silicon | Required for Field Entropy | +| Fuses | SoC shall ensure that UDS_SEED and Field Entropy supplied to Caliptra come directly from OTP fuses and there are no debug paths to inject new values.| Statement of conformance | Required for Caliptra Threat model | +| Fuses | SoC shall add integrity checks for Caliptra fuses as per SoC policy. | Statement of conformance | Reliability | +| Fuses | SoC should apply shielding/obfuscation measures to protect fuse macro. | Statement of conformance | Required for Caliptra Threat model | +| Fuses | SoCs that intend to undergo FIPS 140-3 zeroization shall expose zeroization API as described in zeroization requirements in architecture specification. SoC shall apply appropriate authentication for this API to protect against denial of service and side channel attacks. | Test on silicon | FIPS 140-3 certification | | 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 | +| Resets and Clocks | SoC shall ensure Caliptra's powergood is tied to SoC’s own powergood or any other reset that triggers SoC’s cold boot flow. | Statement of conformance | Required for Caliptra threat model | +| TRNG | SoC shall either provision Caliptra with a dedicated TRNG or shared TRNG. It is highly recommended to use dedicated ITRNG | 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 | @@ -645,6 +653,11 @@ The following table describes SoC integration requirements. | 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. | | | +| Manufacturing | SoC shall provision an IDevID certificate with fields that conform to the requirements described in [Provisioning IDevID during manufacturing](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#provisioning-idevid-during-manufacturing). | Statement of conformance | Functionality | +| Manufacturing | Caliptra relies on obfuscation for confidentiality of UDS_SEED. It is strongly advised to implement manufacturing policies to protect UDS_SEED as defense in depth measures.
1, Prevent leakage of UDS_SEED on manufacturing floor.
2. Implement policies to prevent cloning (programming same UDS_SEED into multiple devices).
3. Implement policies to prevent signing of spurious IDEVID certs. | Statement of conformance | Required for Caliptra Threat model | +| Chain of trust | SoC shall ensure all mutable code and configuration measurements are stashed into Caliptra. A statement of conformance lists what is considered mutable code and configuration vs. what is not. The statement also describes the start of the boot sequence of the SoC and how Caliptra is incorporated into it. | Statement of conformance | Required for Caliptra Threat model | +| Chain of trust | SoC shall limit the mutable code and configuration that persists across the Caliptra powergood reset. A statement of conformance lists what persists and why this persistence is necessary. | Statement of conformance | Required for Caliptra Threat model | +| Implementation | SoC shall apply size-only constraints on cells tagged with the "u__size_only__" string and shall ensure that these are not optimized in synthesis and PNR | Statement of conformance | Required for Caliptra Threat model | | 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* @@ -657,6 +670,23 @@ The following table describes SoC integration requirements. | 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 | || +## Integrator RTL modification requirements + +Several files contain code that may be specific to an integrator's implementation and should be overridden. This overridable code is either configuration parameters with integrator-specific values or modules that implement process-specific functionality. Code in these files should be modified or replaced by integrators using components from the cell library of their fabrication vendor. The following table describes recommended modifications for each file. + +*Table 19: Caliptra integrator custom RTL file list* + +| File | Description | +| :------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- | +| [config_defines.svh](../src/integration/rtl/config_defines.svh) | Enable Caliptra internal TRNG (if applicable).
Declare name of custom clock gate module by defining USER_ICG.
Enable custom clock gate by defining TECH_SPECIFIC_ICG. | +| [soc_ifc_pkg.sv](../src/soc_ifc/rtl/soc_ifc_pkg.sv) | Define PAUSER default behavior and (if applicable) override values. See [Integration Parameters](#integration-parameters). | +| [caliptra_icg.sv](../src/libs/rtl/caliptra_icg.sv) | Replace with technology-specific clock gater.
Modifying this file is not necessary if integrators override the clock gate module that is used by setting TECH_SPECIFIC_ICG. | +| [beh_lib.sv](../src/riscv_core/veer_el2/rtl/lib/beh_lib.sv) | Replace rvclkhdr/rvoclkhdr with technology-specific clock gater.
Modifying this file may not be necessary if integrators override the clock gate module that is used by setting TECH_SPECIFIC_EC_RV_ICG. | +| [caliptra_prim_flop_2sync.sv](../src/caliptra_prim/rtl/caliptra_prim_flop_2sync.sv) | Replace with technology-specific sync cell. | +| [caliptra_2ff_sync.sv](../src/libs/rtl/caliptra_2ff_sync.sv) | Replace with technology-specific sync cell. | +| [dmi_jtag_to_core_sync.v](../src/riscv_core/veer_el2/rtl/dmi/dmi_jtag_to_core_sync.v) | Replace with technology-specific sync cell. | + + # 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. @@ -671,7 +701,7 @@ In an unconstrained environment, several CDC violations are anticipated. CDC ana The following code snippet and schematic diagram illustrate JTAG originating CDC violations. -*Figure 9: Schematic diagram and code snippet showing JTAG-originating CDC violations* +*Figure 8: Schematic diagram and code snippet showing JTAG-originating CDC violations* ![](./images/Caliptra_CDC_JTAG_code_snippet.png) @@ -711,7 +741,7 @@ 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* +*Table 20: Netlist synthesis data* | **IP Name** | **Date** | **Path Group** | **Target Freq** | **QoR WNS** | **QoR Achieveable Freq** | | :--------- | :--------- | :--------- | :--------- | :--------- | :--------- | @@ -874,7 +904,7 @@ Fatal: The 'default' or 'others' must be last case in a case statement The following terminology is used in this document. -*Table 20: Terminology* +*Table 21: Terminology* | Abbreviation | Description | diff --git a/docs/images/crypto_subsystem.png b/docs/images/crypto_subsystem.png old mode 100644 new mode 100755 index cbcb64aee..da8db7d78 Binary files a/docs/images/crypto_subsystem.png and b/docs/images/crypto_subsystem.png differ diff --git a/docs/images/tvla_keygen.png b/docs/images/tvla_keygen.png new file mode 100644 index 000000000..169e39f4d Binary files /dev/null and b/docs/images/tvla_keygen.png differ diff --git a/src/integration/test_suites/infinite_loop/dump_and_compare.sh b/src/integration/test_suites/infinite_loop/dump_and_compare.sh index 594703ba0..1e6c6a0d3 100755 --- a/src/integration/test_suites/infinite_loop/dump_and_compare.sh +++ b/src/integration/test_suites/infinite_loop/dump_and_compare.sh @@ -16,7 +16,7 @@ set -ex # Invoke GDB and dump core registers -riscv64-unknown-elf-gdb -n --batch -x dump_registers.gdb >gdb.log +${GCC_PREFIX}-gdb -n --batch -x dump_registers.gdb >gdb.log # Parse the log, extract register values. Skip those which change as the # program executes since we don't know at which point we tap in. cat gdb.log | grep -E '^ra |^sp |^gp |^tp |^t[01256] |^s[0-9]+ |^a[0-9]+ |^\$[0-9]+' >regdump.txt diff --git a/src/integration/test_suites/infinite_loop/mem_access.sh b/src/integration/test_suites/infinite_loop/mem_access.sh index d800cc099..fb4a7e670 100755 --- a/src/integration/test_suites/infinite_loop/mem_access.sh +++ b/src/integration/test_suites/infinite_loop/mem_access.sh @@ -16,7 +16,7 @@ set -ex # Invoke GDB -riscv64-unknown-elf-gdb -n --batch -x mem_access.gdb >gdb.log +${GCC_PREFIX}-gdb -n --batch -x mem_access.gdb >gdb.log # Parse the log cat gdb.log | grep -E '^\$[0-9]+' >out.txt diff --git a/src/integration/test_suites/infinite_loop/peripheral_access.sh b/src/integration/test_suites/infinite_loop/peripheral_access.sh index 1f9d83cf5..e9d195662 100755 --- a/src/integration/test_suites/infinite_loop/peripheral_access.sh +++ b/src/integration/test_suites/infinite_loop/peripheral_access.sh @@ -16,7 +16,7 @@ set -ex # Invoke GDB -riscv64-unknown-elf-gdb -n --batch -x peripheral_access.gdb >gdb.log +${GCC_PREFIX}-gdb -n --batch -x peripheral_access.gdb >gdb.log # Parse the log cat gdb.log | grep -E '^\$[0-9]+' >out.txt diff --git a/tools/scripts/Makefile b/tools/scripts/Makefile index 03c9b10c5..65bc2941e 100644 --- a/tools/scripts/Makefile +++ b/tools/scripts/Makefile @@ -20,9 +20,14 @@ VERILATOR = verilator GCC_PREFIX = riscv64-unknown-elf BUILD_DIR = $(CURDIR) -rv_gcc_version = $(strip $(shell $(GCC_PREFIX)-gcc --version | head -1 | sed "s/$(GCC_PREFIX)-gcc (\w\+) //")) +# Ensure that RISC-V toolchain is installed +ifeq ($(shell which $(GCC_PREFIX)-gcc 2> /dev/null),) +$(error RISC-V toolchain not found, please refer to https://github.com/chipsalliance/caliptra-rtl?tab=readme-ov-file#riscv-toolchain-installation for more details) +endif + +rv_gcc_version = $(strip $(shell $(GCC_PREFIX)-gcc --version | head -1 | sed "s/$(GCC_PREFIX)-gcc (.*) //")) $(info rv_gcc_version is $(rv_gcc_version)) -ifeq (12.2.0, $(rv_gcc_version)) +ifeq "12.2.0" "$(word 1, $(sort 12.2.0 $(rv_gcc_version)))" ABI = -mabi=ilp32 -march=rv32imc_zicsr_zifencei else ABI = -mabi=ilp32 -march=rv32imc