(678d12b676)

OTP Controller Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_otp_ctrl_autogen.h"

Go to the source code of this file.

Data Structures
struct	dif_otp_ctrl_config
	Runtime configuration for OTP. More...

struct	dif_otp_ctrl_status
	The overall status of the OTP controller. More...

Typedefs
typedef enum dif_otp_ctrl_partition	dif_otp_ctrl_partition_t
	A partition within OTP memory.

typedef struct dif_otp_ctrl_config	dif_otp_ctrl_config_t
	Runtime configuration for OTP. More...

typedef enum dif_otp_ctrl_status_code	dif_otp_ctrl_status_code_t
	A hardware-level status code.

typedef enum dif_otp_ctrl_error	dif_otp_ctrl_error_t
	A hardware-level error code, associated with a particular error defined in `dif_otp_ctrl_status_t`.

typedef struct dif_otp_ctrl_status	dif_otp_ctrl_status_t
	The overall status of the OTP controller. More...

Enumerations
enum	dif_otp_ctrl_partition { kDifOtpCtrlPartitionVendorTest , kDifOtpCtrlPartitionCreatorSwCfg , kDifOtpCtrlPartitionOwnerSwCfg , kDifOtpCtrlPartitionRotCreatorAuthCodesign , kDifOtpCtrlPartitionRotCreatorAuthState , kDifOtpCtrlPartitionHwCfg0 , kDifOtpCtrlPartitionHwCfg1 , kDifOtpCtrlPartitionSecret0 , kDifOtpCtrlPartitionSecret1 , kDifOtpCtrlPartitionSecret2 , kDifOtpCtrlPartitionLifeCycle }
	A partition within OTP memory. More...

enum	dif_otp_ctrl_status_code { kDifOtpCtrlStatusCodeVendorTestError = 0 , kDifOtpCtrlStatusCodeCreatorSwCfgError , kDifOtpCtrlStatusCodeOwnerSwCfgError , kDifOtpCtrlStatusCodeRotCreatorAuthCodesignError , kDifOtpCtrlStatusCodeRotCreatorAuthStateError , kDifOtpCtrlStatusCodeHwCfg0Error , kDifOtpCtrlStatusCodeHwCfg1Error , kDifOtpCtrlStatusCodeSecret0Error , kDifOtpCtrlStatusCodeSecret1Error , kDifOtpCtrlStatusCodeSecret2Error , kDifOtpCtrlStatusCodeLifeCycleError , kDifOtpCtrlStatusCodeDaiError , kDifOtpCtrlStatusCodeLciError , kDifOtpCtrlStatusCodeHasCauseLast = kDifOtpCtrlStatusCodeLciError , kDifOtpCtrlStatusCodeTimeoutError , kDifOtpCtrlStatusCodeLfsrError , kDifOtpCtrlStatusCodeScramblingError , kDifOtpCtrlStatusCodeKdfError , kDifOtpCtrlStatusCodeBusIntegError , kDifOtpCtrlStatusCodeDaiIdle , kDifOtpCtrlStatusCodeCheckPending }
	A hardware-level status code. More...

enum	dif_otp_ctrl_error { kDifOtpCtrlErrorOk , kDifOtpCtrlErrorMacroUnspecified , kDifOtpCtrlErrorMacroRecoverableRead , kDifOtpCtrlErrorMacroUnrecoverableRead , kDifOtpCtrlErrorMacroBlankCheckFailed , kDifOtpCtrlErrorLockedAccess , kDifOtpCtrlErrorBackgroundCheckFailed , kDifOtpCtrlErrorFsmBadState }
	A hardware-level error code, associated with a particular error defined in `dif_otp_ctrl_status_t`. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_configure (const dif_otp_ctrl_t *otp, dif_otp_ctrl_config_t config)
	Configures OTP with runtime information. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_check_integrity (const dif_otp_ctrl_t *otp)
	Runs an integrity check on the OTP hardware. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_check_consistency (const dif_otp_ctrl_t *otp)
	Runs a consistency check on the OTP hardware. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_dai_lock (const dif_otp_ctrl_t *otp)
	Locks out access to the direct access interface registers. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_dai_is_locked (const dif_otp_ctrl_t otp, bool is_locked)
	Checks whether access to the direct access interface is locked. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_lock_config (const dif_otp_ctrl_t *otp)
	Locks out `dif_otp_ctrl_configure()` function. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_config_is_locked (const dif_otp_ctrl_t otp, bool is_locked)
	Checks whether `dif_otp_ctrl_configure()` function is locked-out. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_lock_check_trigger (const dif_otp_ctrl_t *otp)
	Locks out `dif_otp_ctrl_check_*()` functions. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_check_trigger_is_locked (const dif_otp_ctrl_t otp, bool is_locked)
	Checks whether the `dif_otp_ctrl_check_*()` functions are locked-out. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_lock_reading (const dif_otp_ctrl_t *otp, dif_otp_ctrl_partition_t partition)
	Locks out reads to a SW partition. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_reading_is_locked (const dif_otp_ctrl_t otp, dif_otp_ctrl_partition_t partition, bool is_locked)
	Checks whether reads to a SW partition are locked out. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_get_status (const dif_otp_ctrl_t otp, dif_otp_ctrl_status_t status)
	Gets the current status of the OTP controller. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_relative_address (dif_otp_ctrl_partition_t partition, uint32_t abs_address, uint32_t *relative_address)
	Calculates a `relative_address` with respect to a `partition` start address. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_dai_read_start (const dif_otp_ctrl_t *otp, dif_otp_ctrl_partition_t partition, uint32_t address)
	Schedules a read on the Direct Access Interface. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_dai_read32_end (const dif_otp_ctrl_t otp, uint32_t value)
	Gets the result of a completed 32-bit read operation on the Direct Access Interface. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_dai_read64_end (const dif_otp_ctrl_t otp, uint64_t value)
	Gets the result of a completed 64-bit read operation on the Direct Access Interface. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_dai_program32 (const dif_otp_ctrl_t *otp, dif_otp_ctrl_partition_t partition, uint32_t address, uint32_t value)
	Schedules a 32-bit write on the Direct Access Interface. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_dai_program64 (const dif_otp_ctrl_t *otp, dif_otp_ctrl_partition_t partition, uint32_t address, uint64_t value)
	Schedules a 64-bit write on the Direct Access Interface. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_dai_digest (const dif_otp_ctrl_t *otp, dif_otp_ctrl_partition_t partition, uint64_t digest)
	Schedules a hardware digest operation on the Direct Access Interface. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_is_digest_computed (const dif_otp_ctrl_t otp, dif_otp_ctrl_partition_t partition, bool is_computed)
	Checks if the digest value for the given partition has been computed. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_get_digest (const dif_otp_ctrl_t otp, dif_otp_ctrl_partition_t partition, uint64_t digest)
	Gets the buffered digest value for the given partition. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otp_ctrl_read_blocking (const dif_otp_ctrl_t otp, dif_otp_ctrl_partition_t partition, uint32_t address, uint32_t buf, size_t len)
	Performs a memory-mapped read of the given partition, if it supports them. More...

Detailed Description

OTP Controller Device Interface Functions

Definition in file dif_otp_ctrl.h.

Data Structure Documentation

◆ dif_otp_ctrl_config

struct dif_otp_ctrl_config

Runtime configuration for OTP.

This struct describes runtime information for one-time configuration of the hardware.

Definition at line 135 of file dif_otp_ctrl.h.

Data Fields

uint32_t

check_timeout

The timeout for an integrity or consistency check to succeed, in cycles.

100'000 is recommended as a minimum safe value.

uint32_t

consistency_period_mask

A mask for the pseudo-random consistency check period.

The value of this mask limits the period of the consistency check; when the pseudo-random period is computed, this mask is applied to limit it. For example, a value of 0x3ff'ffff would correspond to a maximum period of about 716s at 24MHz.

A value of zero disables the check.

uint32_t

integrity_period_mask

A mask for the pseudo-random integrity check period.

The value of this mask limits the period of the integrity check; when the pseudo-random period is computed, this mask is applied to limit it. For example, a value of 0x3'ffff would correspond to a maximum period of about 2.8s at 24MHz.

A value of zero disables the check.

◆ dif_otp_ctrl_status

struct dif_otp_ctrl_status

The overall status of the OTP controller.

See dif_otp_ctrl_get_status().

Definition at line 334 of file dif_otp_ctrl.h.

Data Fields

dif_otp_ctrl_error_t

causes[kDifOtpCtrlStatusCodeHasCauseLast+1]

A list of root causes for each error status code.

If the error status code error is present in codes, and error <= kDifOtpCtrlStatusCodeHasCauseLast, then causes[error] will contain its root cause.

uint32_t

codes

Currently active statuses, given as a bit vector.

To check whether a particular status code was returned, write

bool has_code = (status.codes >> kMyStatusCode) & 1;

Note that it is possible to quickly check that the controller is idle and error-free by writing

bool is_ok = status.codes == (1 << kDifOtpStatusCodeDaiIdle);

Typedef Documentation

◆ dif_otp_ctrl_config_t

typedef struct dif_otp_ctrl_config dif_otp_ctrl_config_t

Runtime configuration for OTP.

This struct describes runtime information for one-time configuration of the hardware.

◆ dif_otp_ctrl_status_t

typedef struct dif_otp_ctrl_status dif_otp_ctrl_status_t

The overall status of the OTP controller.

See dif_otp_ctrl_get_status().

Enumeration Type Documentation

◆ dif_otp_ctrl_error

enum dif_otp_ctrl_error

A hardware-level error code, associated with a particular error defined in dif_otp_ctrl_status_t.

Enumerator
kDifOtpCtrlErrorOk	Indicates no error.
kDifOtpCtrlErrorMacroUnspecified	Indicates that an OTP macro command was invalid or did not complete successfully. This error indicates non-recoverable hardware malfunction.
kDifOtpCtrlErrorMacroRecoverableRead	Indicates a recoverable error during a read operation. A followup read should work as expected.
kDifOtpCtrlErrorMacroUnrecoverableRead	Indicates an unrecoverable error during a read operation. This error indicates non-recoverable hardware malfunction.
kDifOtpCtrlErrorMacroBlankCheckFailed	Indicates that the blank write check failed during a write operation.
kDifOtpCtrlErrorLockedAccess	Indicates a locked memory region was accessed.
kDifOtpCtrlErrorBackgroundCheckFailed	Indicates a parity, integrity or consistency check failed in the buffer registers. This error indicates non-recoverable hardware malfunction.
kDifOtpCtrlErrorFsmBadState	Indicates that the FSM of the controller is in a bad state or that the controller's FSM has been moved into its terminal state due to escalation via the alert subsystem. This error indicates that the device has been glitched by an attacker.

Definition at line 280 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_partition

enum dif_otp_ctrl_partition

A partition within OTP memory.

Enumerator
kDifOtpCtrlPartitionVendorTest	Vendor test partition. This is reserved for manufacturing smoke checks. The OTP wrapper control logic inside prim_otp is allowed to read/write to this region. ECC uncorrectable errors seen on the functional prim_otp interface will not lead to an alert for this partition. Instead, such errors will be reported as correctable ECC errors.
kDifOtpCtrlPartitionCreatorSwCfg	Software configuration partition. This is for device-specific calibration data, e.g, clock, LDO, RNG, and configuration settings set by the ROM.
kDifOtpCtrlPartitionOwnerSwCfg	Software configuration partition. This contains data that changes software behavior in the ROM, for example enabling defensive features in ROM or selecting failure modes if verification fails.
kDifOtpCtrlPartitionRotCreatorAuthCodesign	This OTP partition is used to store four P-256 keys and four Sphincs+ keys. The partition requires 464 bytes of software visible storage. The partition is locked at manufacturing time to protect against malicious write attempts.
kDifOtpCtrlPartitionRotCreatorAuthState	This OTP partition is used to capture the state of each key slot. Each key can be in one of the following states: BLANK, ENABLED, DISABLED. The encoded values are such that transitions between BLANK -> ENABLED -> DISABLED are possible without causing ECC errors (this is a mechanism similar to how we manage life cycle state transitions). The partition is left unlocked to allow STATE updates in the field. The ROM_EXT is required to lock access to the OTP Direct Access Interface to prevent DoS attacks from malicious code executing on Silicon Owner partitions. DAI write locking is available in EarlGrey.
kDifOtpCtrlPartitionHwCfg0	Hardware configuration 0 partition. This contains a device identifier and manufacturing state.
kDifOtpCtrlPartitionHwCfg1	Hardware configuration 1 partition. This contains several hardware feature switches.
kDifOtpCtrlPartitionSecret0	Secret partition 0. This contains TEST lifecycle unlock tokens.
kDifOtpCtrlPartitionSecret1	Secret partition 1. This contains SRAM and flash scrambling keys.
kDifOtpCtrlPartitionSecret2	Secret partition 2. This contains RMA unlock token, creator root key, and creator seed.
kDifOtpCtrlPartitionLifeCycle	Lifecycle partition. This contains lifecycle transition count and state. This partition cannot be locked since the life cycle state needs to advance to RMA in-field. Note that while this partition is not marked secret, it is not readable nor writeable via the DAI. Only the LC controller can access this partition, and even via the LC controller it is not possible to read the raw manufacturing life cycle state in encoded form, since that encoding is considered a netlist secret. The LC controller only exposes a decoded version of this state.

Definition at line 32 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_status_code

enum dif_otp_ctrl_status_code

A hardware-level status code.

Enumerator
kDifOtpCtrlStatusCodeVendorTestError	Indicates an error occurred in the `VendorTest` partition.
kDifOtpCtrlStatusCodeCreatorSwCfgError	Indicates an error occurred in the `CreatorSwCfg` partition.
kDifOtpCtrlStatusCodeOwnerSwCfgError	Indicates an error occurred in the `OwnerSwCfg` partition.
kDifOtpCtrlStatusCodeRotCreatorAuthCodesignError	Indicates an error occurred in the `RotCreatorAuthCodesign` partition.
kDifOtpCtrlStatusCodeRotCreatorAuthStateError	Indicates an error occurred in the `RotCreatorAuthState` partition.
kDifOtpCtrlStatusCodeHwCfg0Error	Indicates an error occurred in the `HwCfg0` partition.
kDifOtpCtrlStatusCodeHwCfg1Error	Indicates an error occurred in the `HwCfg1` partition.
kDifOtpCtrlStatusCodeSecret0Error	Indicates an error occurred in the `Secret0` partition.
kDifOtpCtrlStatusCodeSecret1Error	Indicates an error occurred in the `Secret1` partition.
kDifOtpCtrlStatusCodeSecret2Error	Indicates an error occurred in the `Secret2` partition.
kDifOtpCtrlStatusCodeLifeCycleError	Indicates an error occurred in the `LifeCycle` partition.
kDifOtpCtrlStatusCodeDaiError	Indicates an error occurred in the direct access interface.
kDifOtpCtrlStatusCodeLciError	Indicates an error occurred in the lifecycle interface.
kDifOtpCtrlStatusCodeHasCauseLast	This is not a status code; rather, it represents the last error code which has a corresponding "cause" register. See `dif_otp_ctrl_status_t` for information on how to use this.
kDifOtpCtrlStatusCodeTimeoutError	Indicates that an integrity or consistency check has timed out. This error is unrecoverable.
kDifOtpCtrlStatusCodeLfsrError	Indicates that the LFSR that generates pseudo-random integrity and consistency checks is in a bad state. This error is unrecoverable.
kDifOtpCtrlStatusCodeScramblingError	Indicates that the scrambling hardware is in a bad state. This error is unrecoverable.
kDifOtpCtrlStatusCodeKdfError	Indicates that the key derivation hardware is in a bad state. This error is unrecoverable.
kDifOtpCtrlStatusCodeBusIntegError	Indicates a bus integrity error. This error will raise an alert.
kDifOtpCtrlStatusCodeDaiIdle	Indicates that the direct access interface is idle.
kDifOtpCtrlStatusCodeCheckPending	Indicates that an integrity or consistency check is currently pending.

Definition at line 169 of file dif_otp_ctrl.h.

Function Documentation

◆ dif_otp_ctrl_check_consistency()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_check_consistency ( const dif_otp_ctrl_t * otp )

Runs a consistency check on the OTP hardware.

This function can be used to trigger a consistency check independent of the pseudo-random hardware-generated checks.

Parameters

otp	An OTP handle.

Returns: The result of the operation.

Definition at line 73 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_check_integrity()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_check_integrity ( const dif_otp_ctrl_t * otp )

Runs an integrity check on the OTP hardware.

This function can be used to trigger an integrity check independent of the pseudo-random hardware-generated checks.

Parameters

otp	An OTP handle.

Returns: The result of the operation.

Definition at line 58 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_check_trigger_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_check_trigger_is_locked	(	const dif_otp_ctrl_t *	otp,
		bool *	is_locked
	)

Checks whether the dif_otp_ctrl_check_*() functions are locked-out.

Parameters

	otp	An OTP handle.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 150 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_config_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_config_is_locked	(	const dif_otp_ctrl_t *	otp,
		bool *	is_locked
	)

Checks whether dif_otp_ctrl_configure() function is locked-out.

Parameters

	otp	An OTP handle.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 127 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_configure	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_config_t	config
	)

Configures OTP with runtime information.

This function should need to be called at most once for the lifetime of otp.

Parameters

otp	An OTP handle.
config	Runtime configuration parameters.

Returns: The result of the operation.

Definition at line 37 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_digest()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_dai_digest	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition,
		uint64_t	digest
	)

Schedules a hardware digest operation on the Direct Access Interface.

This operation will also lock writes for the given partition.

If partition is a SW partition, digest must be non-zero; if it is a partition with a hardware-managed digest, digest must be zero (since the digest will be generated by the hardware). An error is returned if either precondition is not met.

This function does not work with the lifecycle state partition, and will return an error in that case.

Parameters

otp	An OTP handle.
partition	The partition to digest and lock.
digest	The digest to program (for SW partitions).

Returns: The result of the operation.

Definition at line 612 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_dai_is_locked	(	const dif_otp_ctrl_t *	otp,
		bool *	is_locked
	)

Checks whether access to the direct access interface is locked.

Note that besides locking the DAI out until the next reset using the dif_otp_ctrl_dai_lock function, the DAI is also temporarily locked by the HW itself when it is busy processing a DAI command. In such a case, the kDifOtpCtrlStatusCodeDaiIdle status bit will be set to 0 as well.

Parameters

	otp	An OTP handle.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 101 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_lock()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_dai_lock ( const dif_otp_ctrl_t * otp )

Locks out access to the direct access interface registers.

This function is idempotent: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

otp	An OTP handle.

Returns: The result of the operation.

Definition at line 88 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_program32()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_dai_program32	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition,
		uint32_t	address,
		uint32_t	value
	)

Schedules a 32-bit write on the Direct Access Interface.

Writes are performed relative to a partition; address should be given relative to the start of partition. An error is returned for out-of-bounds access.

Furthermore, address must be four-byte-aligned, and partition must not be a secret partition. An error is returned if neither condition is met.

Note that this function cannot be used to program the digest at the end of a SW partition; dif_otp_ctrl_dai_digest() must be used instead.

Parameters

otp	An OTP handle.
partition	The partition to program.
address	A partition-relative address to program.
value	The value to program into the OTP.

Returns: The result of the operation.

Definition at line 527 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_program64()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_dai_program64	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition,
		uint32_t	address,
		uint64_t	value
	)

Schedules a 64-bit write on the Direct Access Interface.

Writes are performed relative to a partition; address should be given relative to the start of partition. An error is returned for out-of-bounds access.

Furthermore, address must be eight-byte-aligned, and partition must be a secret partition. An error is returned if neither condition is met.

Parameters

otp	An OTP handle.
partition	The partition to program.
address	A partition-relative address to program.
value	The value to program into the OTP.

Returns: The result of the operation.

Definition at line 571 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_read32_end()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_dai_read32_end	(	const dif_otp_ctrl_t *	otp,
		uint32_t *	value
	)

Gets the result of a completed 32-bit read operation on the Direct Access Interface.

Whether this function or its 64-bit variant should be called is dependent on the most recent partition read from.

Parameters

	otp	An OTP handle.
[out]	value	Out-param for the read value.

Returns: The result of the operation.

Definition at line 502 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_read64_end()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_dai_read64_end	(	const dif_otp_ctrl_t *	otp,
		uint64_t *	value
	)

Gets the result of a completed 64-bit read operation on the Direct Access Interface.

Whether this function or its 32-bit variant should be called is dependent on the most recent partition read from.

Parameters

	otp	An OTP handle.
[out]	value	Out-param for the read value.

Returns: The result of the operation.

Definition at line 513 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_read_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_dai_read_start	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition,
		uint32_t	address
	)

Schedules a read on the Direct Access Interface.

Reads are performed relative to a partition; address should be given relative to the start of partition. An error is returned for out-of-bounds access.

Furthermore, address must be well-aligned: it must be four-byte aligned for normal partitions and eight-byte-aligned for secret partitions. An error is returned for unaligned access.

Parameters

otp	An OTP handle.
partition	The partition to read from.
address	A partition-relative address to read from.

Returns: The result of the operation.

Definition at line 475 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_get_digest()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_get_digest	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition,
		uint64_t *	digest
	)

Gets the buffered digest value for the given partition.

Note that this value is only updated when the device is reset; if the digest has not been computed yet, or has been computed but not since device reset, this function will return an error.

The lifecycle partition does not have a digest and will result in an error being returned.

Parameters

	otp	An OTP handle.
	partition	The partition to get a digest for.
[out]	digest	Out-param for the digest.

Returns: The result of the operation.

Definition at line 728 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_get_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_get_status	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_status_t *	status
	)

Gets the current status of the OTP controller.

Parameters

	otp	An OTP handle.
[out]	status	Out-param for the controller's status.

Returns: The result of the operation.

Definition at line 228 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_is_digest_computed()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_is_digest_computed	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition,
		bool *	is_computed
	)

Checks if the digest value for the given partition has been computed.

Once a digest has been computed for a partition, the partition is write-locked (additionally, read-locked if the partition is secret).

The lifecycle partition does not have a digest, and checking if this region has a computed digest will return an error.

Parameters

	otp	An OTP handle.
	partition	The partition to check the digest of.
[out]	is_computed	Indicates if the digest has been computed.

Returns: The result of the operation.

Definition at line 707 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_lock_check_trigger()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_lock_check_trigger ( const dif_otp_ctrl_t * otp )

Locks out dif_otp_ctrl_check_*() functions.

This function is idempotent: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

otp	An OTP handle.

Returns: The result of the operation.

Definition at line 137 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_lock_config()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_lock_config ( const dif_otp_ctrl_t * otp )

Locks out dif_otp_ctrl_configure() function.

This function is idempotent: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

otp	An OTP handle.

Returns: The result of the operation.

Definition at line 115 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_lock_reading()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_lock_reading	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition
	)

Locks out reads to a SW partition.

This function should only be called on SW partitions; doing otherwise will return an error.

Note that this is distinct from the write-locking performed by calling dif_otp_ctrl_dai_digest(). In particular, the effects of this function will not persist past a system reset.

This function is idempotent: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

otp	An OTP handle.
partition	The SW partition to lock.

Returns: The result of the operation.

Definition at line 192 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_read_blocking()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_read_blocking	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition,
		uint32_t	address,
		uint32_t *	buf,
		size_t	len
	)

Performs a memory-mapped read of the given partition, if it supports them.

In particular, this function will read len words, starting at address, relative to the start of partition.

The same caveats for dif_otp_ctrl_dai_read_start() apply to address; in addition, address + len must also be in-range and must not overflow.

This function will block until the read completes, unlike Direct Access Interface functions.

Parameters

	otp	An OTP handle.
	partition	The partition to read from.
	address	A partition-relative address to read from.
[out]	buf	A buffer of words to write read values to.
	len	The number of words to read.

Returns: The result of the operation.

Definition at line 752 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_reading_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_reading_is_locked	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_partition_t	partition,
		bool *	is_locked
	)

Checks whether reads to a SW partition are locked out.

This function should only be called on SW partitions; doing otherwise will return an error.

Parameters

	otp	An OTP handle.
	partition	the SW partition to check for locking.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 210 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_relative_address()

OT_WARN_UNUSED_RESULT dif_result_t dif_otp_ctrl_relative_address	(	dif_otp_ctrl_partition_t	partition,
		uint32_t	abs_address,
		uint32_t *	relative_address
	)

Calculates a relative_address with respect to a partition start address.

Parameters

	partition	The partition to use to calculate the reference start address.
	abs_address	Input address relative to the OTP memory start address.
[out]	relative_address	The result relative address with respect to the `partition` start address.

Returns: The result of the operation.

Definition at line 449 of file dif_otp_ctrl.c.

(678d12b676)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_otp_ctrl_config

◆ dif_otp_ctrl_status

Typedef Documentation

◆ dif_otp_ctrl_config_t

◆ dif_otp_ctrl_status_t

Enumeration Type Documentation

◆ dif_otp_ctrl_error

◆ dif_otp_ctrl_partition

◆ dif_otp_ctrl_status_code

Function Documentation

◆ dif_otp_ctrl_check_consistency()

◆ dif_otp_ctrl_check_integrity()

◆ dif_otp_ctrl_check_trigger_is_locked()

◆ dif_otp_ctrl_config_is_locked()

◆ dif_otp_ctrl_configure()

◆ dif_otp_ctrl_dai_digest()

◆ dif_otp_ctrl_dai_is_locked()

◆ dif_otp_ctrl_dai_lock()

◆ dif_otp_ctrl_dai_program32()

◆ dif_otp_ctrl_dai_program64()

◆ dif_otp_ctrl_dai_read32_end()

◆ dif_otp_ctrl_dai_read64_end()

◆ dif_otp_ctrl_dai_read_start()

◆ dif_otp_ctrl_get_digest()

◆ dif_otp_ctrl_get_status()

◆ dif_otp_ctrl_is_digest_computed()

◆ dif_otp_ctrl_lock_check_trigger()

◆ dif_otp_ctrl_lock_config()

◆ dif_otp_ctrl_lock_reading()

◆ dif_otp_ctrl_read_blocking()

◆ dif_otp_ctrl_reading_is_locked()

◆ dif_otp_ctrl_relative_address()