(dcee03a)

OTP Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Data Structures
struct	dif_otp_ctrl_params
	Hardware instantiation parameters for OTP. More...

struct	dif_otp_ctrl_config
	Runtime configuration for OTP. More...

struct	dif_otp_ctrl
	A handle to OTP. More...

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

Typedefs
typedef enum dif_otp_ctrl_toggle	dif_otp_ctrl_toggle_t
	A toggle state: enabled, or disabled. More...

typedef enum dif_otp_ctrl_partition	dif_otp_ctrl_partition_t
	A partition within OTP memory.

typedef struct dif_otp_ctrl_params	dif_otp_ctrl_params_t
	Hardware instantiation parameters for OTP. More...

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

typedef struct dif_otp_ctrl	dif_otp_ctrl_t
	A handle to OTP. More...

typedef enum dif_otp_ctrl_result	dif_otp_ctrl_result_t
	The result of an OTP operation.

typedef enum dif_otp_ctrl_lockable_result	dif_otp_ctrl_lockable_result_t
	The result of a lockable operation.

typedef enum dif_otp_ctrl_dai_result	dif_otp_ctrl_dai_result_t
	The result of a Direct Access Interface (DAI) operation.

typedef enum dif_otp_ctrl_digest_result	dif_otp_ctrl_digest_result_t
	The result of a digest operation.

typedef enum dif_otp_ctrl_irq	dif_otp_ctrl_irq_t
	An OTP interrupt request type.

typedef uint32_t	dif_otp_ctrl_irq_snapshot_t
	A snapshot of the enablement state of the interrupts 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_toggle { kDifOtpCtrlToggleEnabled, kDifOtpCtrlToggleDisabled }
	A toggle state: enabled, or disabled. More...

enum	dif_otp_ctrl_partition { kDifOtpCtrlPartitionCreatorSwCfg, kDifOtpCtrlPartitionOwnerSwCfg, kDifOtpCtrlPartitionHwCfg, kDifOtpCtrlPartitionLifeCycle, kDifOtpCtrlPartitionSecret0, kDifOtpCtrlPartitionSecret1, kDifOtpCtrlPartitionSecret2 }
	A partition within OTP memory. More...

enum	dif_otp_ctrl_result { kDifOtpCtrlOk = 0, kDifOtpCtrlError = 1, kDifOtpCtrlBadArg = 2 }
	The result of an OTP operation. More...

enum	dif_otp_ctrl_lockable_result { kDifOtpCtrlLockableOk = kDifOtpCtrlOk, kDifOtpCtrlLockableError = kDifOtpCtrlError, kDifOtpCtrlLockableBadArg = kDifOtpCtrlBadArg, kDifOtpCtrlLockableLocked }
	The result of a lockable operation. More...

enum	dif_otp_ctrl_dai_result { kDifOtpCtrlDaiOk = kDifOtpCtrlOk, kDifOtpCtrlDaiError = kDifOtpCtrlError, kDifOtpCtrlDaiBadArg = kDifOtpCtrlBadArg, kDifOtpCtrlDaiBusy, kDifOtpCtrlDaiBadPartition, kDifOtpCtrlDaiOutOfRange, kDifOtpCtrlDaiUnaligned }
	The result of a Direct Access Interface (DAI) operation. More...

enum	dif_otp_ctrl_digest_result { kDifOtpCtrlDigestOk = kDifOtpCtrlOk, kDifOtpCtrlDigestError = kDifOtpCtrlError, kDifOtpCtrlDigestBadArg = kDifOtpCtrlBadArg, kDifOtpCtrlDigestMissing }
	The result of a digest operation. More...

enum	dif_otp_ctrl_irq { kDifOtpCtrlIrqDone, kDifOtpCtrlIrqError }
	An OTP interrupt request type. More...

enum	dif_otp_ctrl_status_code { kDifOtpCtrlStatusCodeCreatorSwCfgError = 0, kDifOtpCtrlStatusCodeOwnerSwCfgError, kDifOtpCtrlStatusCodeHwCfgError, kDifOtpCtrlStatusCodeLifeCycleError, kDifOtpCtrlStatusCodeSecret0Error, kDifOtpCtrlStatusCodeSecret1Error, kDifOtpCtrlStatusCodeSecret2Error, kDifOtpCtrlStatusCodeDaiError, kDifOtpCtrlStatusCodeLciError, kDifOtpCtrlStatusCodeHasCauseLast = kDifOtpCtrlStatusCodeLciError, kDifOtpCtrlStatusCodeTimeoutError, kDifOtpCtrlStatusCodeLfsrError, kDifOtpCtrlStatusCodeScramblingError, kDifOtpCtrlStatusCodeKdfError, 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
DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_init (dif_otp_ctrl_params_t params, dif_otp_ctrl_t *otp)
	Creates a new handle for OTP. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_lockable_result_t	dif_otp_ctrl_configure (const dif_otp_ctrl_t *otp, dif_otp_ctrl_config_t config)
	Configures OTP with runtime information. More...

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

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

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_lock_config (const dif_otp_ctrl_t *otp)
	Locks out `dif_otp_ctrl_configure()` and the `dif_otp_ctrl_check_*()` functions. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_config_is_locked (const dif_otp_ctrl_t otp, bool is_locked)
	Checks whether `dif_otp_ctrl_configure()` and the `dif_otp_ctrl_check_*()` functions are locked-out. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_irq_is_pending (const dif_otp_ctrl_t otp, dif_otp_ctrl_irq_t irq, bool is_pending)
	Returns whether a particular interrupt is currently pending. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_irq_acknowledge (const dif_otp_ctrl_t *otp, dif_otp_ctrl_irq_t irq)
	Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_irq_get_enabled (const dif_otp_ctrl_t otp, dif_otp_ctrl_irq_t irq, dif_otp_ctrl_toggle_t state)
	Checks whether a particular interrupt is currently enabled or disabled. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_irq_set_enabled (const dif_otp_ctrl_t *otp, dif_otp_ctrl_irq_t irq, dif_otp_ctrl_toggle_t state)
	Sets whether a particular interrupt is currently enabled or disabled. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_irq_force (const dif_otp_ctrl_t *otp, dif_otp_ctrl_irq_t irq)
	Forces a particular interrupt, causing it to be serviced as if hardware had asserted it. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_irq_disable_all (const dif_otp_ctrl_t otp, dif_otp_ctrl_irq_snapshot_t snapshot)
	Disables all interrupts, optionally snapshotting all toggle state for later restoration. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_irq_restore_all (const dif_otp_ctrl_t otp, const dif_otp_ctrl_irq_snapshot_t snapshot)
	Restores interrupts from the given snapshot. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_digest_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_read_test (const dif_otp_ctrl_t otp, uint32_t address, uint32_t buf, size_t len)
	Performs a memory-mapped read of the TEST region. More...

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t	dif_otp_ctrl_write_test (const dif_otp_ctrl_t otp, uint32_t address, const uint32_t buf, size_t len)
	Performs a memory-mapped write of the TEST region. More...

Detailed Description

OTP Device Interface Functions

Definition in file dif_otp_ctrl.h.

Data Structure Documentation

◆ dif_otp_ctrl_params

struct dif_otp_ctrl_params

Hardware instantiation parameters for OTP.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 91 of file dif_otp_ctrl.h.

Data Fields
mmio_region_t	base_addr	The base address for the OTP hardware registers.

◆ 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 104 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

struct dif_otp_ctrl

A handle to OTP.

This type should be treated as opaque by users.

Definition at line 140 of file dif_otp_ctrl.h.

Data Fields
dif_otp_ctrl_params_t	params

◆ 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 428 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 <= kDifOtpCtrlStatusHasCauseLast, 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_irq_snapshot_t

typedef uint32_t dif_otp_ctrl_irq_snapshot_t

A snapshot of the enablement state of the interrupts for OTP.

This is an opaque type, to be used with the dif_otp_ctrl_irq_disable_all() and dif_otp_ctrl_irq_restore_all() functions.

Definition at line 276 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_params_t

typedef struct dif_otp_ctrl_params dif_otp_ctrl_params_t

Hardware instantiation parameters for OTP.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ 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().

◆ dif_otp_ctrl_t

typedef struct dif_otp_ctrl dif_otp_ctrl_t

A handle to OTP.

This type should be treated as opaque by users.

◆ dif_otp_ctrl_toggle_t

typedef enum dif_otp_ctrl_toggle dif_otp_ctrl_toggle_t

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

Enumeration Type Documentation

◆ dif_otp_ctrl_dai_result

enum dif_otp_ctrl_dai_result

The result of a Direct Access Interface (DAI) operation.

Enumerator
kDifOtpCtrlDaiOk	Indicates that the operation succeeded.
kDifOtpCtrlDaiError	Indicates some unspecified failure.
kDifOtpCtrlDaiBadArg	Indicates that some parameter passed into a function failed a precondition. When this value is returned, no hardware operations occurred.
kDifOtpCtrlDaiBusy	Indicates that the DAI is busy and can't accept another incomming command.
kDifOtpCtrlDaiBadPartition	Indicates that the given partition does not support this operation.
kDifOtpCtrlDaiOutOfRange	Indicates that the attempted DAI operation would go out of range of the requested partition.
kDifOtpCtrlDaiUnaligned	Indicates that the given address was not correctly aligned.

Definition at line 194 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_digest_result

enum dif_otp_ctrl_digest_result

The result of a digest operation.

Enumerator
kDifOtpCtrlDigestOk	Indicates that the operation succeeded.
kDifOtpCtrlDigestError	Indicates some unspecified failure.
kDifOtpCtrlDigestBadArg	Indicates that some parameter passed into a function failed a precondition. When this value is returned, no hardware operations occurred.
kDifOtpCtrlDigestMissing	Indicates that a digest lookup failed because the digest had not been programmed yet.

Definition at line 232 of file dif_otp_ctrl.h.

◆ 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 374 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_irq

enum dif_otp_ctrl_irq

An OTP interrupt request type.

Enumerator
kDifOtpCtrlIrqDone	Indicates that an asynchronous transaction completed.
kDifOtpCtrlIrqError	Indicates that an error has occurred in the OTP controller.

Definition at line 258 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_lockable_result

enum dif_otp_ctrl_lockable_result

The result of a lockable operation.

Enumerator
kDifOtpCtrlLockableOk	Indicates that the operation succeeded.
kDifOtpCtrlLockableError	Indicates some unspecified failure.
kDifOtpCtrlLockableBadArg	Indicates that some parameter passed into a function failed a precondition. When this value is returned, no hardware operations occurred.
kDifOtpCtrlLockableLocked	Indicates that this operation has been locked out, and can never succeed until hardware reset.

Definition at line 168 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_partition

enum dif_otp_ctrl_partition

A partition within OTP memory.

Enumerator
kDifOtpCtrlPartitionCreatorSwCfg	The creator software configuration area. This partition contains device-specific calibration data.
kDifOtpCtrlPartitionOwnerSwCfg	The owner software configuration area. This partition contains data to e.g. enable ROM hardening features.
kDifOtpCtrlPartitionHwCfg	The hardware configuration area.
kDifOtpCtrlPartitionLifeCycle	The device lifecycle area.
kDifOtpCtrlPartitionSecret0	Scrambled partition 0. This paritition contains TEST lifecycle state unlock tokens.
kDifOtpCtrlPartitionSecret1	Scrambled partition 1. This partition contains SRAM and flash scrambling keys.
kDifOtpCtrlPartitionSecret2	Scrambled partition 2. This partition contains the RMA unlock token and the CreatorRootKey.

Definition at line 43 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_result

enum dif_otp_ctrl_result

The result of an OTP operation.

Enumerator

kDifOtpCtrlOk

Indicates that the operation succeeded.

kDifOtpCtrlError

Indicates some unspecified failure.

kDifOtpCtrlBadArg

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 147 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_status_code

enum dif_otp_ctrl_status_code

A hardware-level status code.

Enumerator
kDifOtpCtrlStatusCodeCreatorSwCfgError	Indicates an error occurred in the `CreatorSwCfg` partition.
kDifOtpCtrlStatusCodeOwnerSwCfgError	Indicates an error occurred in the `OwnerSwCfg` partition.
kDifOtpCtrlStatusCodeHwCfgError	Indicates an error occurred in the `HwCfg` partition.
kDifOtpCtrlStatusCodeLifeCycleError	Indicates an error occurred in the `LifeCycle` 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.
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.
kDifOtpCtrlStatusCodeDaiIdle	Indicates that the direct access interface is idle.
kDifOtpCtrlStatusCodeCheckPending	Indicates that an integrity or consistency check is currently pending.

Definition at line 281 of file dif_otp_ctrl.h.

◆ dif_otp_ctrl_toggle

enum dif_otp_ctrl_toggle

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

Enumerator
kDifOtpCtrlToggleDisabled	The "disabled" state.

Definition at line 29 of file dif_otp_ctrl.h.

Function Documentation

◆ dif_otp_ctrl_check_consistency()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_lockable_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 74 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_check_integrity()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_lockable_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 57 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_config_is_locked()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_config_is_locked	(	const dif_otp_ctrl_t *	otp,
		bool *	is_locked
	)

Checks whether dif_otp_ctrl_configure() and 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 104 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_configure()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_lockable_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 36 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_digest()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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 706 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_program32()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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 607 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_program64()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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 657 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_read32_end()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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 568 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_read64_end()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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 586 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_dai_read_start()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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 paritions 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 534 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_get_digest()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_digest_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 758 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_get_status()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_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 317 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_init()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_init	(	dif_otp_ctrl_params_t	params,
		dif_otp_ctrl_t *	otp
	)

Creates a new handle for OTP.

This function does not actuate the hardware.

Parameters

	params	Hardware instantiation parameters.
[out]	otp	Out param for the initialized handle.

Returns: The result of the operation.

Definition at line 14 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_irq_acknowledge()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_irq_acknowledge	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_irq_t	irq
	)

Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.

Parameters

otp	An OTP handle.
irq	An interrupt type.

Returns: The result of the operation.

Definition at line 201 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_irq_disable_all()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_irq_disable_all	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_irq_snapshot_t *	snapshot
	)

Disables all interrupts, optionally snapshotting all toggle state for later restoration.

Parameters

	otp	An OTP handle.
[out]	snapshot	Out-param for the snapshot; may be `NULL`.

Returns: The result of the operation.

Definition at line 290 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_irq_force()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_irq_force	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_irq_t	irq
	)

Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

Parameters

otp	An OTP handle.
irq	An interrupt type.

Returns: The result of the operation.

Definition at line 272 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_irq_get_enabled()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_irq_get_enabled	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_irq_t	irq,
		dif_otp_ctrl_toggle_t *	state
	)

Checks whether a particular interrupt is currently enabled or disabled.

Parameters

	otp	An OTP handle.
	irq	An interrupt type.
[out]	state	Out-param toggle state of the interrupt.

Returns: The result of the operation.

Definition at line 219 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_irq_is_pending()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_irq_is_pending	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_irq_t	irq,
		bool *	is_pending
	)

Returns whether a particular interrupt is currently pending.

Parameters

	otp	An OTP handle.
	irq	An interrupt type.
[out]	is_pending	Out-param for whether the interrupt is pending.

Returns: The result of the operation.

Definition at line 182 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_irq_restore_all()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_irq_restore_all	(	const dif_otp_ctrl_t *	otp,
		const dif_otp_ctrl_irq_snapshot_t *	snapshot
	)

Restores interrupts from the given snapshot.

This function can be used with dif_otp_ctrl_irq_disable_all() to temporary interrupt save-and-restore.

Parameters

otp	An OTP handle.
snapshot	A snapshot to restore from.

Returns: The result of the operation.

Definition at line 306 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_irq_set_enabled()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_irq_set_enabled	(	const dif_otp_ctrl_t *	otp,
		dif_otp_ctrl_irq_t	irq,
		dif_otp_ctrl_toggle_t	state
	)

Sets whether a particular interrupt is currently enabled or disabled.

Parameters

otp	An OTP handle.
irq	An interrupt type.
state	The new toggle state for the interrupt.

Returns: The result of the operation.

Definition at line 239 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_lock_config()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_lock_config ( const dif_otp_ctrl_t * otp )

Locks out dif_otp_ctrl_configure() and the dif_otp_ctrl_check_*() functions.

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

Parameters

otp	An OTP handle.

Returns: The result of the operation.

Definition at line 91 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_lock_reading()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_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 reentrant: calling it while functionality is locked will have no effect and return kDifOtpCtrlOk.

Parameters

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

Returns: The result of the operation.

Definition at line 132 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_read_blocking()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_dai_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 812 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_read_test()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_read_test	(	const dif_otp_ctrl_t *	otp,
		uint32_t	address,
		uint32_t *	buf,
		size_t	len
	)

Performs a memory-mapped read of the TEST region.

In particular, this function will read len words, starting at address.

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.

Parameters

	otp	An OTP handle.
	address	The 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 838 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_reading_is_locked()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_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 150 of file dif_otp_ctrl.c.

◆ dif_otp_ctrl_write_test()

DIF_WARN_UNUSED_RESULT dif_otp_ctrl_result_t dif_otp_ctrl_write_test	(	const dif_otp_ctrl_t *	otp,
		uint32_t	address,
		const uint32_t *	buf,
		size_t	len
	)

Performs a memory-mapped write of the TEST region.

In particular, this function will write len words, starting at address.

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

Parameters

otp	An OTP handle.
address	An absolute address to write to.
buf	A buffer of words to write write values from.
len	The number of words to write.

Returns: The result of the operation.

Definition at line 851 of file dif_otp_ctrl.c.

(dcee03a)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_otp_ctrl_params

◆ dif_otp_ctrl_config

◆ dif_otp_ctrl

◆ dif_otp_ctrl_status

Typedef Documentation

◆ dif_otp_ctrl_config_t

◆ dif_otp_ctrl_irq_snapshot_t

◆ dif_otp_ctrl_params_t

◆ dif_otp_ctrl_status_t

◆ dif_otp_ctrl_t

◆ dif_otp_ctrl_toggle_t

Enumeration Type Documentation

◆ dif_otp_ctrl_dai_result

◆ dif_otp_ctrl_digest_result

◆ dif_otp_ctrl_error

◆ dif_otp_ctrl_irq

◆ dif_otp_ctrl_lockable_result

◆ dif_otp_ctrl_partition

◆ dif_otp_ctrl_result

◆ dif_otp_ctrl_status_code

◆ dif_otp_ctrl_toggle

Function Documentation

◆ dif_otp_ctrl_check_consistency()

◆ dif_otp_ctrl_check_integrity()

◆ dif_otp_ctrl_config_is_locked()

◆ dif_otp_ctrl_configure()

◆ dif_otp_ctrl_dai_digest()

◆ 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_init()

◆ dif_otp_ctrl_irq_acknowledge()

◆ dif_otp_ctrl_irq_disable_all()

◆ dif_otp_ctrl_irq_force()

◆ dif_otp_ctrl_irq_get_enabled()

◆ dif_otp_ctrl_irq_is_pending()

◆ dif_otp_ctrl_irq_restore_all()

◆ dif_otp_ctrl_irq_set_enabled()

◆ dif_otp_ctrl_lock_config()

◆ dif_otp_ctrl_lock_reading()

◆ dif_otp_ctrl_read_blocking()

◆ dif_otp_ctrl_read_test()

◆ dif_otp_ctrl_reading_is_locked()

◆ dif_otp_ctrl_write_test()