Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_otp_ctrl.h File Reference

(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"

Go to the source code of this file.

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

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

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

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

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

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

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

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

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

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

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

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

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

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
otpAn 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
otpAn 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
otpAn OTP handle.
[out]is_lockedOut-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
otpAn OTP handle.
configRuntime 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
otpAn OTP handle.
partitionThe partition to digest and lock.
digestThe 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
otpAn OTP handle.
partitionThe partition to program.
addressA partition-relative address to program.
valueThe 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
otpAn OTP handle.
partitionThe partition to program.
addressA partition-relative address to program.
valueThe 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
otpAn OTP handle.
[out]valueOut-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
otpAn OTP handle.
[out]valueOut-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
otpAn OTP handle.
partitionThe partition to read from.
addressA 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
otpAn OTP handle.
partitionThe partition to get a digest for.
[out]digestOut-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
otpAn OTP handle.
[out]statusOut-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()

Creates a new handle for OTP.

This function does not actuate the hardware.

Parameters
paramsHardware instantiation parameters.
[out]otpOut 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
otpAn OTP handle.
irqAn 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
otpAn OTP handle.
[out]snapshotOut-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
otpAn OTP handle.
irqAn 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
otpAn OTP handle.
irqAn interrupt type.
[out]stateOut-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
otpAn OTP handle.
irqAn interrupt type.
[out]is_pendingOut-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
otpAn OTP handle.
snapshotA 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
otpAn OTP handle.
irqAn interrupt type.
stateThe 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
otpAn 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
otpAn OTP handle.
partitionThe 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
otpAn OTP handle.
partitionThe partition to read from.
addressA partition-relative address to read from.
[out]bufA buffer of words to write read values to.
lenThe 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
otpAn OTP handle.
addressThe address to read from.
[out]bufA buffer of words to write read values to.
lenThe 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
otpAn OTP handle.
partitionthe SW partition to check for locking.
[out]is_lockedOut-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
otpAn OTP handle.
addressAn absolute address to write to.
bufA buffer of words to write write values from.
lenThe number of words to write.
Returns
The result of the operation.

Definition at line 851 of file dif_otp_ctrl.c.