Skip to content

Commit

Permalink
[Docs] Updated release notes and doc version for 1.1 (#496)
Browse files Browse the repository at this point in the history 
* Updated release notes and doc version for 1.1

* Initial pass for Caliptra Release Checklist doc

* Updated release notes

* Few more updates, release date

* Updated with HMAC enhancements

* Update rev-date, env var recommendation, directory structure

* Add instructions to override hw config makefile variables

* Update release notes with latest lint changes/KV-JTAG fixes

* Review feedback -- grammar

* Updates from feedback - capitalization, dates, Key Vault spacing

* Updates from feedback - should vs must, expanded VCS sim steps

* Rev date

* Update from feedback - tense

* Replace lint rule list with generic verbiage

* Add FPGA val item

* Updated dates
  • Loading branch information
@calebofearth
calebofearth authored Jul 3, 2024
1 parent 5659a02 commit f98295a
Show file tree
Hide file tree
Showing 5 changed files with 156 additions and 164 deletions.
58 changes: 43 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ See the License for the specific language governing permissions and<BR>
limitations under the License.*_<BR>

# **Caliptra Hands-On Guide** #
_*Last Update: 2024/04/01*_
_*Last Update: 2024/07/02*_


## **Tools Used** ##
Expand Down Expand Up @@ -89,21 +89,24 @@ with the provided Makefile for compiling test C programs.
## **ENVIRONMENT VARIABLES** ##
Required for simulation:<BR>
`CALIPTRA_WORKSPACE`: Defines the absolute path to the directory where the Verilator "scratch" output directory will be created. Recommended to define as the absolute path to the directory that contains the Project repository root (called "Caliptra" or "caliptra-rtl")<BR>
`CALIPTRA_ROOT`: Defines the absolute path to the Project repository root (called "Caliptra" or "caliptra-rtl"). Recommended to define as `${CALIPTRA_WORKSPACE}/Caliptra`.<BR>
`CALIPTRA_ROOT`: Defines the absolute path to the Project repository root (called "Caliptra" or "caliptra-rtl"). Recommended to define as `${CALIPTRA_WORKSPACE}/caliptra-rtl`.<BR>

Required for Firmware (i.e. Test suites) makefile:<BR>
`TESTNAME`: Contains the name of one of the tests listed inside the `src/integration/test_suites` folder; only used for `caliptra_top_tb` tests<BR>

## **Repository Overview** ##
```
Caliptra
caliptra-rtl
|-- LICENSE
|-- README.md
|-- Release_Notes.md
|-- SECURITY.md
|-- docs
| |-- Caliptra_Integration_Specification.pdf
| |-- Caliptra_Hardware_Specification.pdf
| `-- Caliptra_TestPlan.xlsx
| |-- CaliptraHardwareSpecification.md
| |-- CaliptraIntegrationSpecification.md
| |-- CaliptraReleaseChecklist.md
| |-- Caliptra_TestPlan.xlsx
| `-- images
|-- src
| |-- aes
| |-- ahb_lite_bus
Expand Down Expand Up @@ -142,7 +145,7 @@ The "Integration" sub-component contains the top-level fileset for Caliptra. `sr


## **Verilog File Lists** ##
Verilog file lists are generated via VCS and included in the config directory for each unit. New files added to the design should be included in the vf list. They can be included manually or by using VCS to regenerate the vf file. File lists define the compilation sources (including all dependencies) required to build and simulate a given module or testbench, and should be used for simulation, lint, and synthesis.
Verilog file lists are generated via VCS and included in the config directory for each unit. New files added to the design must be included in the vf list. They can be included manually or by using VCS to regenerate the vf file. File lists define the compilation sources (including all dependencies) required to build and simulate a given module or testbench, and should be used by integrators for simulation, lint, and synthesis.

## **Scripts Description** ##

Expand All @@ -163,24 +166,49 @@ Verilog file lists are generated via VCS and included in the config directory fo

### Caliptra Top VCS Steps: ###
1. Setup tools, add to PATH (ensure RISC-V toolchain is also available)
2. Define all environment variables above
1. 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 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}`
- See [Regression Tests](#Regression-Tests) for information about available tests
1. Create a run folder for build outputs (and cd to it)
1. Either use the provided Makefile or execute each of the following steps manually to run VCS simulations
1. Makefile usage:
- Example command:
`make -C <path/to/run/folder> -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=${TESTNAME} vcs`
- NOTE: `TESTNAME=${TESTNAME}` is optional; if not provided, test defaults to value of TESTNAME environment variable, then to `iccm_lock`
- NOTE: Users may wish to produce a run log by piping the make command to a tee command, e.g.:
`make ... <args> ... | tee <path/to/run/folder>/vcs.log`
- NOTE: The following macro values may be overridden to define the hardware configuration that is built. Default values in the Makefile are shown with each macro:
- CALIPTRA_INTERNAL_QSPI=1
- CALIPTRA_INTERNAL_UART=1
- CALIPTRA_INTERNAL_I3C=0
- CALIPTRA_INTERNAL_TRNG=1
- E.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile CALIPTRA_INTERNAL_QSPI=0 CALIPTRA_INTERNAL_UART=0 CALIPTRA_INTERNAL_I3C=0 CALIPTRA_INTERNAL_TRNG=1 vcs`
1. Remaining steps describe how to manually run the individual steps for a VCS simulation
1. [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.
1. 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`
6. Compile complete project using `src/integration/config/caliptra_top_tb.vf` as a compilation target in VCS. When running the `vcs` command to generate simv, users should ensure that `caliptra_top_tb` is explicitly specified as the top-level component in their command to ensure this is the sole "top" that gets simulated.
7. Copy the test generator scripts to the run output directory:
- NOTE: The following macro values must be overridden to match the value provided (later) during hardware compilation. The full L0 regression suite includes tests that will fail if the firmware and hardware configuration has a discrepancy. Default values in the Makefile are shown with each macro:
- CALIPTRA_INTERNAL_QSPI=1
- CALIPTRA_INTERNAL_UART=1
- CALIPTRA_INTERNAL_I3C=0
- CALIPTRA_INTERNAL_TRNG=1
- E.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile CALIPTRA_INTERNAL_QSPI=0 CALIPTRA_INTERNAL_UART=0 CALIPTRA_INTERNAL_I3C=0 CALIPTRA_INTERNAL_TRNG=1 program.hex`
1. Compile complete project using `src/integration/config/caliptra_top_tb.vf` as a compilation target in VCS. When running the `vcs` command to generate simv, users should ensure that `caliptra_top_tb` is explicitly specified as the top-level component in their command to ensure this is the sole "top" that gets simulated.
- NOTE: The following macro values must be defined (or omitted) to match the value provided during firmware compilation. The full L0 regression suite includes tests that will fail if the firmware and hardware configuration has a discrepancy.
- CALIPTRA_INTERNAL_QSPI
- CALIPTRA_INTERNAL_UART
- CALIPTRA_INTERNAL_I3C
- CALIPTRA_INTERNAL_TRNG
1. Copy the test generator scripts to the run output directory:
- [src/ecc/tb/ecdsa_secp384r1.exe](src/ecc/tb/ecdsa_secp384r1.exe)
* Necessary for [randomized_pcr_signing](src/integration/test_suites/randomized_pcr_signing)
* OPTIONAL otherwise
- [src/doe/tb/doe_test_gen.py](src/doe/tb/doe_test_gen.py)
* Allows use of randomized secret field inputs during testing.
* Required when using the `+RAND_DOE_VALUES` plusarg during simulation
* Also required for several smoke tests that require randomized DOE IV, such as smoke_test_doe_scan, smoke_test_doe_rand, smoke_test_doe_cg
8. Simulate project with `caliptra_top_tb` as the top target
1. Simulate project with `caliptra_top_tb` as the top target

### Caliptra Top Verilator Steps: ###
1. Setup tools, add to PATH (ensure Verilator, GCC, and RISC-V toolchain are available)
Expand Down
64 changes: 57 additions & 7 deletions Release_Notes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,63 @@ See the License for the specific language governing permissions and<BR>
limitations under the License.*_<BR>

# **Release Notes** #
_*Last Update: 2024/01/18*_
_*Last Update: 2024/07/02*_

## Rev 1p0 ##
## Rev 1p1 ##

### Rev 1p0 release date: 2024/01/18 ###
#### Rev 1p1 release date: 2024/07/02 ####
- Caliptra Hardware Specification: Updated with LMS accelerator, ECC radix changes, Key Vault updates
- Caliptra Integration Specification updates to add clarity
- Caliptra README updates to tool versions, simulation instructions
- Update RDL register descriptions for clarity, accuracy in generated reg document
- Verification
- Update zeroize assertions
- Add X check assertions to all register files
- New assertions and firmware tests for LMS accelerator
- Formal Verification (#493):
- ECC Montgomery updated to recent changes
- SHA512\_masked update to entropy instead of LFSR
- SHA256 LMS extension verified
- Fixes for UVM caliptra\_top test scenarios
- Mailbox SRAM initialization
- Assorted fixes for sequence access contention, error-checking, randomization constraints
- Added early mailbox command flow to emulate stash measurement functionality
- Fixes for UVM Key Vault test scenarios
- Update clear\_secrets prediction
- RTL
- ECC radix48
- LMS accelerator
- SHA512 masking
- HMAC and HMAC\_DRBG enhancements
- Masking for SHA512
- Modifications for clean Lint
* Replace casez with case
* Replace 2-state with 4-state typedefs, parameters, enums
* Replace 'reg' with 'logic' type
* Radix fixes for many signals
* Logical/boolean operator fixes
* Logic reorganization to resolve undriven ICache signals in RV core
* Fixes for redundant logic in RV core
* Logically equivalent code adjustments to resolve potential index-out-of-bounds errors
* Declare synthesizable package functions as automatic
* Declare names for unnamed generate blocks
- Update PeakRDL tool version and regenerate reg files to resolve lint issues
- Update HW\_REV\_ID bit-map and configure value to 1.1

#### Bug Fixes ####
[RTL] Add connection for JTAG TDO enable signal #415 #425
[ENTROPY\_SRC] Entropy source sfifo signal unable to exit reset #503 #506
[PV] Async reset condition missing for `nonce_offset_i` #339 #444 #483
[HMAC] Fixed leakage issue in HMAC #325 #429
[KV] Resolve a potential vulnerability in Key Vault usage #528
[JTAG] VeeR JTAG access only with debug unlocked; Caliptra JTAG access with debug unlocked or manufacturing #528
[JTAG] Enable JTAG interface to be used while boot FSM is halted at breakpoint #541

## Previous Releases ##

### Rev 1p0 ###

#### 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
Expand All @@ -27,17 +79,15 @@ _*Last Update: 2024/01/18*_
- Adding ECC, DOE, HMAC_DRBG and SHA512_masked formal Assertion IP
- JTAG with clock gating test cases
- Fixes for UVM caliptra_top test scenarios
- Fixes for UVM KeyVault test scenarios
- Fixes for UVM Key Vault test scenarios
- Updated synthesis tool from Design Compiler to Fusion Compiler (sanity checks only)
- RTL
- Remove TODO comments on caliptra_top ports
- Remove JTAG IDCODE command from RISC-V processor

### Bug Fixes ###
#### Bug Fixes ####
[MBOX] Fix ICCM Uncorrectable ECC error driving hw_error_non_fatal bit for LSU reads

## Previous Releases ##

### Rev 1p0-rc1 ###

#### Rev 1p0-rc1 release date: 2023/11/03 (1p0 version pending ROM release for official declaration) ###
Expand Down
2 changes: 1 addition & 1 deletion docs/CaliptraHardwareSpecification.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

<p style="text-align: center;">Caliptra Hardware Specification</p>

<p style="text-align: center;">Version 1.0</p>
<p style="text-align: center;">Version 1.1</p>

<div style="page-break-after: always"></div>

Expand Down
142 changes: 1 addition & 141 deletions docs/CaliptraIntegrationSpecification.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -920,147 +920,7 @@ The target foundry technology node is an industry standard, moderately advanced

# 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
A standardized set of lint rules is used to sign off on each release. The lint policy may be provided directly to integrators upon request to ensure lint is clean in the SoC.

# Terminology

Expand Down
Loading

0 comments on commit f98295a

Please sign in to comment.