Programmer’s Guide

During provisioning and manufacturing, SW interacts with the OTP controller mostly through the Direct Access Interface (DAI), which is described below. Afterwards during production, SW is expected to perform only read accesses via the exposed CSRs and CSR windows, since all write access to the partitions has been locked down.

The following sections provide some general guidance, followed by an explanation of the DAI and a detailed OTP memory map. Typical programming sequences are explained at the end of the Programmer’s guide.

General Guidance

Initialization

The OTP controller initializes automatically upon power-up and is fully operational by the time the processor boots. The only initialization steps that SW should perform are:

  1. Check that the OTP controller has successfully initialized by reading STATUS. I.e., make sure that none of the ERROR bits are set, and that the DAI is idle (STATUS.DAI_IDLE).
  2. Set up the periodic background checks:

If needed, one-off integrity and consistency checks can be triggered via CHECK_TRIGGER. If this functionality is not needed, it is recommended to lock down the trigger register via CHECK_TRIGGER_REGWEN.

Later on during the boot process, SW may also choose to block read access to the SW managed partitions via the associated partition lock registers, e.g. CREATOR_SW_CFG_READ_LOCK or OWNER_SW_CFG_READ_LOCK.

Reset Considerations

It is important to note that values in OTP can be corrupted if a reset occurs during a programming operation. This should be of minor concern for SW, however, since all partitions except for the LIFE_CYCLE partition are being provisioned in secure and controlled environments, and not in the field. The LIFE_CYCLE partition is the only partition that is modified in the field - but that partition is entirely owned by the life cycle controller and not by SW.

Programming Already Programmed Regions

OTP words cannot be programmed twice, and doing so may damage the memory array. Hence the OTP controller performs a blank check and returns an error if a write operation is issued to an already programmed location.

Potential Side-Effects on Flash via Life Cycle

It should be noted that the locked status of the partition holding the creator root key (i.e., the value of the SECRET2_DIGEST_0) determines the ID_STATUS of the device, which in turn determines SW accessibility of creator seed material in flash and OTP. That means that creator-seed-related collateral needs to be provisioned to Flash before the OTP digest lockdown mechanism is triggered, since otherwise accessibility to the corresponding flash region is lost. See the life cycle controller documentation for more details.

Direct Access Interface

OTP has to be programmed via the Direct Access Interface, which is comprised of the following CSRs:

CSR NameDescription
DIRECT_ACCESS_WDATA_0Low 32bit word to be written.
DIRECT_ACCESS_WDATA_1High 32bit word to be written.
DIRECT_ACCESS_RDATA_0Low 32bit word that has been read.
DIRECT_ACCESS_RDATA_1High 32bit word that has been read.
DIRECT_ACCESS_ADDRESSbyte address for the access.
DIRECT_ACCESS_CMDCommand register to trigger a read or a write access.
DIRECT_ACCESS_REGWENWrite protection register for DAI.

See further below for a detailed Memory Map of the address space accessible via the DAI.

Readout Sequence

A typical readout sequence looks as follows:

  1. Check whether the DAI is idle by reading the STATUS register.
  2. Write the byte address for the access to DIRECT_ACCESS_ADDRESS. Note that the address is aligned with the granule, meaning that either 2 or 3 LSBs of the address are ignored, depending on whether the access granule is 32 or 64bit.
  3. Trigger a read command by writing 0x1 to DIRECT_ACCESS_CMD.
  4. Poll the STATUS until the DAI state goes back to idle. Alternatively, the otp_operation_done interrupt can be enabled up to notify the processor once an access has completed.
  5. If the status register flags a DAI error, additional handling is required (see Section on Error handling).
  6. If the region accessed has a 32bit access granule, the 32bit chunk of read data can be read from DIRECT_ACCESS_RDATA_0. If the region accessed has a 64bit access granule, the 64bit chunk of read data can be read from the DIRECT_ACCESS_RDATA_0 and DIRECT_ACCESS_RDATA_1 registers.
  7. Go back to 1. and repeat until all data has been read.

The hardware will set DIRECT_ACCESS_REGWEN to 0x0 while an operation is pending in order to temporarily lock write access to the CSRs registers.

Programming Sequence

A typical programming sequence looks as follows:

  1. Check whether the DAI is idle by reading the STATUS register.
  2. If the region to be accessed has a 32bit access granule, place a 32bit chunk of data into DIRECT_ACCESS_WDATA_0. If the region to be accessed has a 64bit access granule, both the DIRECT_ACCESS_WDATA_0 and DIRECT_ACCESS_WDATA_1 registers have to be used.
  3. Write the byte address for the access to DIRECT_ACCESS_ADDRESS. Note that the address is aligned with the granule, meaning that either 2 or 3 LSBs of the address are ignored, depending on whether the access granule is 32 or 64bit.
  4. Trigger a write command by writing 0x2 to DIRECT_ACCESS_CMD.
  5. Poll the STATUS until the DAI state goes back to idle. Alternatively, the otp_operation_done interrupt can be enabled up to notify the processor once an access has completed.
  6. If the status register flags a DAI error, additional handling is required (see Section on Error handling).
  7. Go back to 1. and repeat until all data has been written.

The hardware will set DIRECT_ACCESS_REGWEN to 0x0 while an operation is pending in order to temporarily lock write access to the CSRs registers.

Note that SW is responsible for keeping track of already programmed OTP word locations during the provisioning phase. It is imperative that SW does not write the same word location twice, since this can lead to ECC inconsistencies, thereby potentially rendering the device useless.

Digest Calculation Sequence

The hardware digest computation for the hardware and secret partitions can be triggered as follows:

  1. Check whether the DAI is idle by reading the STATUS register.
  2. Write the partition base address to DIRECT_ACCESS_ADDRESS.
  3. Trigger a digest calculation command by writing 0x4 to DIRECT_ACCESS_CMD.
  4. Poll the STATUS until the DAI state goes back to idle. Alternatively, the otp_operation_done interrupt can be enabled up to notify the processor once an access has completed.
  5. If the status register flags a DAI error, additional handling is required (see Section on Error handling).

The hardware will set DIRECT_ACCESS_REGWEN to 0x0 while an operation is pending in order to temporarily lock write access to the CSRs registers.

It should also be noted that the effect of locking a partition via the digest only takes effect after the next system reset. To prevent integrity check failures SW must therefore ensure that no more programming operations are issued to the affected partition after initiating the digest calculation sequence.

Software Integrity Handling

As opposed to buffered partitions, the digest and integrity handling of unbuffered partitions is entirely up to software. The only hardware-assisted feature in unbuffered partitions is the digest lock, which locks write access to an unbuffered partition once a nonzero value has been programmed to the 64bit digest location.

In a similar vein, it should be noted that the system-wide bus-integrity metadata does not travel alongside the data end-to-end in the OTP controller (i.e., the bus-integrity metadata bits are not stored into the OTP memory array). This means that data written to and read from the OTP macro is not protected by the bus integrity feature at all stages. In case of buffered partitions this does not pose a concern since data integrity in these partitions is checked via the hardware assisted digest mechanism. In case of unbuffered partitions however, the data integrity checking is entirely up to software. I.e., if data is read from an unbuffered partition (either through the DAI or CSR windows), software should perform an integrity check on that data.

Error Handling

The agents that can access the OTP macro (DAI, LCI, buffered/unbuffered partitions) expose detailed error codes that can be used to root cause any failure. The error codes are defined in the table below, and the corresponding otp_err_e enum type can be found in the otp_ctrl_pkg. The table also lists which error codes are supported by which agent.

Errors that are not “recoverable” are severe errors that move the corresponding partition or DAI/LCI FSM into a terminal error state, where no more commands can be accepted (a system reset is required to restore functionality in that case). Errors that are “recoverable” are less severe and do not cause the FSM to jump into a terminal error state.

Note that error codes that originate in the physical OTP macro are prefixed with Macro*.

Error CodeEnum NameRecoverableDAILCIUnbufBufDescription
0x0NoError-xxxxNo error has occurred.
0x1MacroErrornoxxxxReturned if the OTP macro command did not complete successfully due to a macro malfunction.
0x2MacroEccCorrErroryesx-xxA correctable ECC error has occurred during a read operation in the OTP macro.
0x3MacroEccUncorrErrornox-x*xAn uncorrectable ECC error has occurred during a read operation in the OTP macro. Note (*): This error is collapsed into MacroEccCorrError if the partition is a vendor test partition. It then becomes a recoverable error.
0x4MacroWriteBlankErroryes / no*xx--This error is returned if a write operation attempted to clear an already programmed bit location. Note (*): This error is recoverable if encountered in the DAI, but unrecoverable if encountered in the LCI.
0x5AccessErroryesx-x-An access error has occurred (e.g. write to write-locked region, or read to a read-locked region).
0x6CheckFailErrorno--xxAn unrecoverable ECC, integrity or consistency error has been detected.
0x7FsmStateErrornoxxxxThe FSM has been glitched into an invalid state, or escalation has been triggered and the FSM has been moved into a terminal error state.

All non-zero error codes listed above trigger an otp_error interrupt. In addition, all unrecoverable OTP Macro* errors (codes 0x1, 0x3) trigger a fatal_macro_error alert, while all remaining unrecoverable errors trigger a fatal_check_error alert.

If software receives an otp_error interrupt, but all error codes read back as 0x0 (NoError), this should be treated as a fatal error condition, and the system should be shut down as soon as possible.

Note that while the MacroWriteBlankError is marked as a recoverable error, the affected OTP word may be in an inconsistent state after this error has been returned. This can cause several issues when the word is accessed again (either as part of a regular read operation, as part of the readout at boot, or as part of a background check). It is important that SW ensures that each word is only written once, since this can render the device useless.

Direct Access Memory Map

The table below provides a detailed overview of the items stored in the OTP partitions. Some of the items that are buffered in registers is readable via memory mapped CSRs, and these CSRs are linked in the table below. Items that are not linked can only be accessed via the direct programming interface (if the partition is not locked via the corresponding digest). It should be noted that CREATOR_SW_CFG and OWNER_SW_CFG are accessible through a memory mapped window, and content of these partitions is not buffered. Hence, a read access to those windows will take in the order of 10-20 cycles until the read returns.

Sizes below are specified in multiples of 32bit words.

IndexPartitionSize [B]Access GranuleItemByte AddressSize [B]
0VENDOR_TEST6432bitSCRATCH0x00056
64bitVENDOR_TEST_DIGEST0x0388
1CREATOR_SW_CFG42432bitCREATOR_SW_CFG_AST_CFG0x040156
32bitCREATOR_SW_CFG_AST_INIT_EN0x0DC4
32bitCREATOR_SW_CFG_ROM_EXT_SKU0x0E04
32bitCREATOR_SW_CFG_SIGVERIFY_RSA_MOD_EXP_IBEX_EN0x0E44
32bitCREATOR_SW_CFG_SIGVERIFY_RSA_KEY_EN0x0E88
32bitCREATOR_SW_CFG_SIGVERIFY_SPX_EN0x0F04
32bitCREATOR_SW_CFG_SIGVERIFY_SPX_KEY_EN0x0F48
32bitCREATOR_SW_CFG_FLASH_DATA_DEFAULT_CFG0x0FC4
32bitCREATOR_SW_CFG_FLASH_INFO_BOOT_DATA_CFG0x1004
32bitCREATOR_SW_CFG_FLASH_HW_INFO_CFG_OVERRIDE0x1044
32bitCREATOR_SW_CFG_RNG_EN0x1084
32bitCREATOR_SW_CFG_JITTER_EN0x10C4
32bitCREATOR_SW_CFG_RET_RAM_RESET_MASK0x1104
32bitCREATOR_SW_CFG_MANUF_STATE0x1144
32bitCREATOR_SW_CFG_ROM_EXEC_EN0x1184
32bitCREATOR_SW_CFG_CPUCTRL0x11C4
32bitCREATOR_SW_CFG_MIN_SEC_VER_ROM_EXT0x1204
32bitCREATOR_SW_CFG_MIN_SEC_VER_BL00x1244
32bitCREATOR_SW_CFG_DEFAULT_BOOT_DATA_IN_PROD_EN0x1284
32bitCREATOR_SW_CFG_RMA_SPIN_EN0x12C4
32bitCREATOR_SW_CFG_RMA_SPIN_CYCLES0x1304
32bitCREATOR_SW_CFG_RNG_REPCNT_THRESHOLDS0x1344
32bitCREATOR_SW_CFG_RNG_REPCNTS_THRESHOLDS0x1384
32bitCREATOR_SW_CFG_RNG_ADAPTP_HI_THRESHOLDS0x13C4
32bitCREATOR_SW_CFG_RNG_ADAPTP_LO_THRESHOLDS0x1404
32bitCREATOR_SW_CFG_RNG_BUCKET_THRESHOLDS0x1444
32bitCREATOR_SW_CFG_RNG_MARKOV_HI_THRESHOLDS0x1484
32bitCREATOR_SW_CFG_RNG_MARKOV_LO_THRESHOLDS0x14C4
32bitCREATOR_SW_CFG_RNG_EXTHT_HI_THRESHOLDS0x1504
32bitCREATOR_SW_CFG_RNG_EXTHT_LO_THRESHOLDS0x1544
32bitCREATOR_SW_CFG_RNG_ALERT_THRESHOLD0x1584
32bitCREATOR_SW_CFG_RNG_HEALTH_CONFIG_DIGEST0x15C4
32bitCREATOR_SW_CFG_SRAM_KEY_RENEW_EN0x1604
64bitCREATOR_SW_CFG_DIGEST0x1E08
2OWNER_SW_CFG65632bitOWNER_SW_CFG_ROM_ERROR_REPORTING0x1E84
32bitOWNER_SW_CFG_ROM_BOOTSTRAP_DIS0x1EC4
32bitOWNER_SW_CFG_ROM_ALERT_CLASS_EN0x1F04
32bitOWNER_SW_CFG_ROM_ALERT_ESCALATION0x1F44
32bitOWNER_SW_CFG_ROM_ALERT_CLASSIFICATION0x1F8320
32bitOWNER_SW_CFG_ROM_LOCAL_ALERT_CLASSIFICATION0x33864
32bitOWNER_SW_CFG_ROM_ALERT_ACCUM_THRESH0x37816
32bitOWNER_SW_CFG_ROM_ALERT_TIMEOUT_CYCLES0x38816
32bitOWNER_SW_CFG_ROM_ALERT_PHASE_CYCLES0x39864
32bitOWNER_SW_CFG_ROM_ALERT_DIGEST_PROD0x3D84
32bitOWNER_SW_CFG_ROM_ALERT_DIGEST_PROD_END0x3DC4
32bitOWNER_SW_CFG_ROM_ALERT_DIGEST_DEV0x3E04
32bitOWNER_SW_CFG_ROM_ALERT_DIGEST_RMA0x3E44
32bitOWNER_SW_CFG_ROM_WATCHDOG_BITE_THRESHOLD_CYCLES0x3E84
32bitOWNER_SW_CFG_ROM_KEYMGR_ROM_EXT_MEAS_EN0x3EC4
32bitOWNER_SW_CFG_MANUF_STATE0x3F04
32bitOWNER_SW_CFG_ROM_RSTMGR_INFO_EN0x3F44
32bitOWNER_SW_CFG_ROM_EXT_BOOTSTRAP_EN0x3F84
64bitOWNER_SW_CFG_DIGEST0x4708
3ROT_CREATOR_AUTH_CODESIGN47232bitROT_CREATOR_AUTH_CODESIGN_ECDSA_KEY00x47868
32bitROT_CREATOR_AUTH_CODESIGN_ECDSA_KEY10x4BC68
32bitROT_CREATOR_AUTH_CODESIGN_ECDSA_KEY20x50068
32bitROT_CREATOR_AUTH_CODESIGN_ECDSA_KEY30x54468
32bitROT_CREATOR_AUTH_CODESIGN_SPX_KEY00x58840
32bitROT_CREATOR_AUTH_CODESIGN_SPX_KEY10x5B040
32bitROT_CREATOR_AUTH_CODESIGN_SPX_KEY20x5D840
32bitROT_CREATOR_AUTH_CODESIGN_SPX_KEY30x60040
32bitROT_CREATOR_AUTH_CODESIGN_BLOCK_SHA2_256_HASH0x62832
64bitROT_CREATOR_AUTH_CODESIGN_DIGEST0x6488
4ROT_CREATOR_AUTH_STATE4032bitROT_CREATOR_AUTH_STATE_ECDSA_KEY00x6504
32bitROT_CREATOR_AUTH_STATE_ECDSA_KEY10x6544
32bitROT_CREATOR_AUTH_STATE_ECDSA_KEY20x6584
32bitROT_CREATOR_AUTH_STATE_ECDSA_KEY30x65C4
32bitROT_CREATOR_AUTH_STATE_SPX_KEY00x6604
32bitROT_CREATOR_AUTH_STATE_SPX_KEY10x6644
32bitROT_CREATOR_AUTH_STATE_SPX_KEY20x6684
32bitROT_CREATOR_AUTH_STATE_SPX_KEY30x66C4
64bitROT_CREATOR_AUTH_STATE_DIGEST0x6708
5HW_CFG07232bitDEVICE_ID0x67832
32bitMANUF_STATE0x69832
64bitHW_CFG0_DIGEST0x6B88
6HW_CFG11632bitEN_SRAM_IFETCH0x6C01
32bitEN_CSRNG_SW_APP_READ0x6C11
64bitHW_CFG1_DIGEST0x6C88
7SECRET04064bitTEST_UNLOCK_TOKEN0x6D016
64bitTEST_EXIT_TOKEN0x6E016
64bitSECRET0_DIGEST0x6F08
8SECRET18864bitFLASH_ADDR_KEY_SEED0x6F832
64bitFLASH_DATA_KEY_SEED0x71832
64bitSRAM_DATA_KEY_SEED0x73816
64bitSECRET1_DIGEST0x7488
9SECRET28864bitRMA_TOKEN0x75016
64bitCREATOR_ROOT_KEY_SHARE00x76032
64bitCREATOR_ROOT_KEY_SHARE10x78032
64bitSECRET2_DIGEST0x7A08
10LIFE_CYCLE8832bitLC_TRANSITION_CNT0x7A848
32bitLC_STATE0x7D840

Note that since the content in the SECRET* partitions are scrambled using a 64bit PRESENT cipher, read and write access through the DAI needs to occur at a 64bit granularity. Also, all digests (no matter whether they are SW or HW digests) have an access granule of 64bit.

The table below lists digests locations, and the corresponding locked partitions.

Digest NameAffected PartitionCalculated by HW
VENDOR_TEST_DIGESTVENDOR_TESTno
CREATOR_SW_CFG_DIGESTCREATOR_SW_CFGno
OWNER_SW_CFG_DIGESTOWNER_SW_CFGno
ROT_CREATOR_AUTH_CODESIGN_DIGESTROT_CREATOR_AUTH_CODESIGNno
ROT_CREATOR_AUTH_STATE_DIGESTROT_CREATOR_AUTH_STATEno
HW_CFG0_DIGESTHW_CFG0yes
HW_CFG1_DIGESTHW_CFG1yes
SECRET0_DIGESTSECRET0yes
SECRET1_DIGESTSECRET1yes
SECRET2_DIGESTSECRET2yes

Write access to the affected partition will be locked if the digest has a nonzero value.

For the software partition digests, it is entirely up to software to decide on the digest algorithm to be used. Hardware will determine the lock condition only based on whether a non-zero value is present at that location or not.

For the hardware partitions, hardware calculates this digest and uses it for background verification. Digest calculation can be triggered via the DAI.

Finally, it should be noted that the RMA_TOKEN and CREATOR_ROOT_KEY_SHARE0 / CREATOR_ROOT_KEY_SHARE1 items can only be programmed when the device is in the DEV, PROD, PROD_END and RMA stages. Please consult the life cycle controller documentation documentation for more information.

Examples

Provisioning Items

The following represents a typical provisioning sequence for items in all partitions (except for the LIFE_CYCLE partition, which is not software-programmable):

  1. Program the item in 32bit or 64bit chunks via the DAI.
  2. Read back and verify the item via the DAI.
  3. If the item is exposed via CSRs or a CSR window, perform a full-system reset and verify whether those fields are correctly populated.

Note that any unrecoverable errors during the programming steps, or mismatches during the readback and verification steps indicate that the device might be malfunctioning (possibly due to fabrication defects) and hence the device may have to be scrapped. This is however rare and should not happen after fabrication testing.

Locking Partitions

Once a partition has been fully populated, write access to that partition has to be permanently locked. For the HW_CFG* and SECRET* partitions, this can be achieved as follows:

  1. Trigger a digest calculation via the DAI.
  2. Read back and verify the digest location via the DAI.
  3. Perform a full-system reset and verify that the corresponding CSRs exposing the 64bit digest have been populated (HW_CFG_DIGEST_0, SECRET0_DIGEST_0, SECRET1_DIGEST_0 or SECRET2_DIGEST_0).

It should be noted that locking only takes effect after a system reset since the affected partitions first have to re-sense the digest values. Hence, it is critical that SW ensures that no more data is written to the partition to be locked after triggering the hardware digest calculation. Otherwise, the device will likely be rendered inoperable as this can lead to permanent digest mismatch errors after system reboot.

For the CREATOR_SW_CFG and OWNER_SW_CFG partitions, the process is similar, but computation and programming of the digest is entirely up to software:

  1. Compute a 64bit digest over the relevant parts of the partition, and program that value to CREATOR_SW_CFG_DIGEST_0 or OWNER_SW_CFG_DIGEST_0 via the DAI. Note that digest accesses through the DAI have an access granule of 64bit.
  2. Read back and verify the digest location via the DAI.
  3. Perform a full-system reset and verify that the corresponding digest CSRs CREATOR_SW_CFG_DIGEST_0 or OWNER_SW_CFG_DIGEST_0 have been populated with the correct 64bit value.

Note that any unrecoverable errors during the programming steps, or mismatches during the read-back and verification steps indicate that the device might be malfunctioning (possibly due to fabrication defects) and hence the device may have to be scrapped. This is however rare and should not happen after fabrication testing.

Device Interface Functions (DIFs)

Additional Notes

OTP IP Assumptions

It is assumed the OTP IP employed in production has reasonable physical defense characteristics. Specifically which defensive features will likely be use case dependent, but at a minimum they should have the properties below. Note some properties are worded with “SHALL” and others with “SHOULD”. “SHALL” refers to features that must be present, while “SHOULD” refers to features that are ideal, but optional.

  • The contents shall not be observable via optical microscopy (for example anti-fuse technology).
  • The IP lifetime shall not be limited by the amount of read cycles performed.
  • If the IP contains field programmability (internal charge pumps and LDOs), there shall be mechanisms in place to selectively disable this function based on device context.
  • If the IP contains redundant columns, rows, pages or banks for yield improvement, it shall provide a mechanism to lock down arbitrary manipulation of page / bank swapping during run-time.
  • The IP shall be clear on what bits must be manipulated by the user, what bits are automatically manipulated by hardware (for example ECC or redundancy) and what areas the user can influence.
  • The IP shall be compatible, through the use of a proprietary wrapper or shim, with an open-source friendly IO interface.
  • The IP should functionally support the programming of already programmed bits without information leakage.
  • The IP should offer SCA resistance:
    • For example, the content may be stored differentially.
    • For example, the sensing exhibits similar power signatures no matter if the stored bit is 0 or 1.
  • The IP interface shall be memory-like if beyond a certain size.
  • When a particular location is read, a fixed width output is returned; similar when a particular location is programmed, a fixed width input is supplied.
  • The IP does not output all stored bits in parallel.
  • The contents should be electrically hidden. For example, it should be difficult for an attacker to energize the fuse array and observe how the charge leaks.
  • The IP should route critical nets at lower metal levels to avoid probing.
  • The IP should contain native detectors for fault injection attacks.
  • The IP should contain mechanisms to guard against interrupted programming - either through malicious intent or unexpected power loss and glitched address lines.
  • The IP should contain mechanisms for error corrections (single bit errors).
    • For example ECC or redundant bits voting / or-ing.
    • As error correction mechanisms are technology dependent, that information should not be exposed to the open-source controller, instead the controller should simply receive information on whether a read / program was successful.
  • The IP should have self-test functionality to assess the health of the storage and analog structures.
  • The IP may contain native PUF-like functionality.