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... | |
OTP Controller Device Interface Functions
Definition in file dif_otp_ctrl.h.
struct dif_otp_ctrl_config |
Runtime configuration for OTP.
This struct describes runtime information for one-time configuration of the hardware.
Definition at line 83 of file dif_otp_ctrl.h.
struct dif_otp_ctrl_status |
The overall status of the OTP controller.
See dif_otp_ctrl_get_status()
.
Definition at line 270 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 |
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 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.
typedef struct dif_otp_ctrl_status dif_otp_ctrl_status_t |
The overall status of the OTP controller.
enum dif_otp_ctrl_error |
A hardware-level error code, associated with a particular error defined in dif_otp_ctrl_status_t
.
Definition at line 216 of file dif_otp_ctrl.h.
A partition within OTP memory.
Definition at line 30 of file dif_otp_ctrl.h.
A hardware-level status code.
Definition at line 117 of file dif_otp_ctrl.h.
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.
otp | An OTP handle. |
Definition at line 71 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. |
Definition at line 56 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. | |
[out] | is_locked | Out-param for the locked state. |
Definition at line 121 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. | |
[out] | is_locked | Out-param for the locked state. |
Definition at line 98 of file dif_otp_ctrl.c.
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
.
otp | An OTP handle. |
config | Runtime configuration parameters. |
Definition at line 35 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. |
partition | The partition to digest and lock. |
digest | The digest to program (for SW partitions). |
Definition at line 628 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. |
partition | The partition to program. |
address | A partition-relative address to program. |
value | The value to program into the OTP. |
Definition at line 530 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. |
partition | The partition to program. |
address | A partition-relative address to program. |
value | The value to program into the OTP. |
Definition at line 580 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. | |
[out] | value | Out-param for the read value. |
Definition at line 491 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. | |
[out] | value | Out-param for the read value. |
Definition at line 509 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. |
partition | The partition to read from. |
address | A partition-relative address to read from. |
Definition at line 457 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. | |
partition | The partition to get a digest for. | |
[out] | digest | Out-param for the digest. |
Definition at line 739 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. | |
[out] | status | Out-param for the controller's status. |
Definition at line 196 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. | |
partition | The partition to check the digest of. | |
[out] | is_computed | Indicates if the digest has been computed. |
Definition at line 718 of file dif_otp_ctrl.c.
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 reentrant: calling it while functionality is locked will have no effect and return kDifOtpCtrlOk
.
otp | An OTP handle. |
Definition at line 108 of file dif_otp_ctrl.c.
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 reentrant: calling it while functionality is locked will have no effect and return kDifOtpCtrlOk
.
otp | An OTP handle. |
Definition at line 86 of file dif_otp_ctrl.c.
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 reentrant: calling it while functionality is locked will have no effect and return kDifOtpCtrlOk
.
otp | An OTP handle. |
partition | The SW partition to lock. |
Definition at line 153 of file dif_otp_ctrl.c.
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.
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. |
Definition at line 763 of file dif_otp_ctrl.c.
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.
otp | An OTP handle. | |
partition | the SW partition to check for locking. | |
[out] | is_locked | Out-param for the locked state. |
Definition at line 178 of file dif_otp_ctrl.c.
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.
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. |
Definition at line 431 of file dif_otp_ctrl.c.