Earlgrey SiVal Test Development Guidelines

General Guidelines

TL;DR; It is currently not possible to directly connect opentitantool to a sim_dv binary to simulate sival tests with a Rust component. In the absence of that mechanism, it is hence recommended to write sival tests in a DV-friendly way. This ensures that porting and running these tests in sim_dv becomes straightforward, should the need arise to debug a test in simulation during sival. To that end a set of guidelines and recommendations are presented in this document to enhance portability of tests among platforms.

As a general guidance, for tests that should run in DV, the following recommendations apply:

Prefer simple self-contained tests

Keep the test as simple and device centric where possible. This means that interaction with the host should be minimized and the control flow and checks should be implemented mostly on the device side. It is however useful to send detailed test status and checksums to the host side for verification using LOG_INFO for example.

Maintain sim_dv patterns

If the test to be developed is an existing sim_dv test that needs to be converted, the existing vseq’s interaction pattern should be followed.

• Backdoor writes should be replaced with ujson mem commands.
• When translating vseq’s that synchronize using the cfg.sw_test_status_vif, use the test status update printed out through LOG_INFO (UART) on the host side.

Limit the use of complex structures to communicate with the host

Serialization and deserialization of data is time consuming in DV. Moreover, the DV environment does not currently have support for the ujson mechanism.

• Restrict the use of ujson payloads to complex tests that cannot be implemented in another way.

• Prefer the use of simpler communication methods such as UART, GPIOs or the ujson mem command mechanism.

• Complex test examples include:

  • Long running tests that are unsuitable for simulation due to their runtime.
  • Tests relying on structured data such as complex cryptographic tests
  • Tests of I/O IPs that require structured data

Support test_rom and rom targets

SiVal test targets must be emulated using the production rom, but test_rom configurations are required for simulation environments to save time. Make sure to run test cases with both configurations on the FPGA.

Limit the number of OTP transitions

OTP transitions are usually restricted to test cases that can only be run inside a secure environment. This is because devices in non-PROD life cycle stages are considered open samples. In addition to this, there is limited access to silicon in larger quantities during early bring up. Test execution thus needs to be planned such that test cases are executed on a given OTP configuration without requiring OTP writes:

• Verify test expectations against the device’s lifecycle stage, preferring one test Bazel target per life cycle configuration.
• A similar approach is required for differing OTP configurations. Use custom OTP images in Bazel as dependencies in test cases, so that it is easier to determine how many configurations are needed for SiVal activities. Consider migrating DV test targets to use OTP images generated by Bazel (low priority).
• The exception to these rules are manufacturing and provisioning test cases which are required to walk through various life cycle stages and OTP settings.

OTP Images

Silicon bring-up and validation activities have to be planned in a way that minimizes the number of OTP configurations given that there may be limited availability of samples during early post-silicon stages.

//hw/ip/otp_ctrl/data/earlgrey_a0_skus/sival/BUILD contains the OTP configurations used in Silicon Validation (SiVal) for the EarlGrey design.

:otp_img_test_unlocked0_manuf_empty

Represents the initial DUT test unlocked state, which is only applicable for test_unlocked0 life cycle state. All other test unlocked states require the SECRET0 partition to be configured.

ROM execution is disabled in this configuration. JTAG should be used to bootstrap code into SRAM or FLASH.

:otp_img_test_locked0_manuf_initialized

Represents a DUT with the SECRET0 partition initialized in the test_locked0 life cycle state. This configuration will be generally used to lock the DUT before shipping to the Final Test (FT) test house.

:otp_img_test_unlocked{1..7}_manuf_initialized

Represents an initialized DUT configuration. Available on test_unlock states 1-7. An initialized DUT contains the following partitions configured:

• SECRET0
• CREATOR_SW_CFG
• OWNER_SW_CFG

Notes:

1. ROM execution is enabled in this configuration.
2. JTAG use may require setting the ROM in bootstrap mode to avoid getting watchdog timeouts.
3. Flash scrambling is disabled during manufacturing process at this stage. Use OTP images with the manuf_personalized suffix to test flash scrambling.

:otp_img_{lc_state}_manuf_individualized

Represents an individualized DUT configuration. Available on the following life cycle states:

• test_unlocked{1..7}
• dev
• prod
• prod_end

The following OTP partitions are configured:

• SECRET0
• CREATOR_SW_CFG
• OWNER_SW_CFG
• HW_CFG

The following HW_CFG settings are hardcoded. Other settings will be tested inside a secure environment.

Notes:

1. ROM execution is enabled in this configuration.
2. JTAG use may require setting the ROM in bootstrap mode to avoid getting watchdog timeouts.
3. Flash scrambling is disabled during manufacturing process at this stage. Use OTP images with the manuf_personalized suffix to test flash scrambling.

:otp_img_{lc_state}_manuf_personalized

Represents a personalized DUT configuration. Available on the following life cycle states:

• dev
• prod
• prod_end

The following OTP partitions are configured:

• SECRET0
• SECRET1
• SECRET2
• CREATOR_SW_CFG
• OWNER_SW_CFG
• HW_CFG

Emulation Targets

//hw/top_earlgrey/BUILD contains the targets used for silicon emulation for the EarlGrey design. The following sections describe the targets in more detail.

:fpga_cw310_sival

FPGA configuration used to emulate silicon targets. This rule can be used by targets that require execution at the rom_ext stage level in flash, as well as SRAM programs. Use the fpga_cw310_sival_rom_ext execution environment to emulate silicon targets containing a rom_ext stage.

Configuration:

{
    rom = "//sw/device/silicon_creator/rom:rom_with_fake_keys",
    otp = "//hw/ip/otp_ctrl/data/earlgrey_a0_skus/sival_bringup:otp_img_prod_manuf_personalized",
}

:fpga_cw310_sival_rom_ext

FPGA configuration used to emulate silicon targets containing a rom_ext stage. This is the recommended option for test cases that implemented to run in prod or prod_end life cycle states.

Silicon Targets

//hw/top_earlgrey/BUILD defines targets for silicon execution. The following sections describe the targets in more detail.

:silicon_creator

This execution environment can be used by targets that require execution at the rom_ext stage level as well as SRAM programs. Use the silicon_owner_sival_rom_ext execution environment to target silicon configurations where the test must be loaded by a rom_ext.

This execution environment is restricted to devices in one of the following life cycle stages:

• test_unlocked{1..7}
• dev
• rma

This is because PROD signing keys are restricted to offline signing, and by policy PROD keys are only targeted for production environments.

This execution environment requires a physical signing token. See NitroKey token configuration for more details.

See instructions on how to run the SiVal test suites with this execution environment.

:silicon_owner_sival_rom_ext

This execution environment is used to execute on silicon targets containing a rom_ext stage. This is the recommended option for test cases that implemented to run in prod or prod_end life cycle states.

This execution environment requires access to the OpenTitan Cloud KMS service. See CloudKMS for more details.

See instructions on how to run the SiVal test suites with this execution environment.

See ROM_EXT for SiVal for more details on the ROM_EXT configuration.