Entropy Source 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_entropy_src_autogen.h"
Go to the source code of this file.
Data Structures | |
struct | dif_entropy_src_fw_override_config |
Firmware override parameters for an entropy source. More... | |
struct | dif_entropy_src_config |
Runtime configuration for an entropy source. More... | |
struct | dif_entropy_src_health_test_config |
Criteria used by various entropy source health tests to decide whether the test has failed. More... | |
struct | dif_entropy_src_revision |
Revision information for an entropy source. More... | |
struct | dif_entropy_src_health_test_stats |
Statistics on entropy source health tests. More... | |
struct | dif_entropy_src_alert_fail_counts |
Statistics on entropy source health tests failures that triggered alerts. More... | |
struct | dif_entropy_src_debug_state |
Debug status information. More... | |
Typedefs | |
typedef enum dif_entropy_src_single_bit_mode | dif_entropy_src_single_bit_mode_t |
A single-bit RNG mode, where only one bit is sampled. | |
typedef enum dif_entropy_src_main_fsm | dif_entropy_src_main_fsm_t |
Main FSM state. | |
typedef struct dif_entropy_src_fw_override_config | dif_entropy_src_fw_override_config_t |
Firmware override parameters for an entropy source. | |
typedef struct dif_entropy_src_config | dif_entropy_src_config_t |
Runtime configuration for an entropy source. More... | |
typedef enum dif_entropy_src_test | dif_entropy_src_test_t |
A statistical test on the bits emitted by an entropy source. | |
typedef struct dif_entropy_src_health_test_config | dif_entropy_src_health_test_config_t |
Criteria used by various entropy source health tests to decide whether the test has failed. | |
typedef struct dif_entropy_src_revision | dif_entropy_src_revision_t |
Revision information for an entropy source. More... | |
typedef struct dif_entropy_src_health_test_stats | dif_entropy_src_health_test_stats_t |
Statistics on entropy source health tests. | |
typedef struct dif_entropy_src_alert_fail_counts | dif_entropy_src_alert_fail_counts_t |
Statistics on entropy source health tests failures that triggered alerts. | |
typedef enum dif_entropy_src_sha3_state | dif_entropy_src_sha3_state_t |
SHA3 state machine states. More... | |
typedef struct dif_entropy_src_debug_state | dif_entropy_src_debug_state_t |
Debug status information. | |
typedef enum dif_entropy_src_alert_cause | dif_entropy_src_alert_cause_t |
Recoverable alerts. | |
typedef enum dif_entropy_src_error | dif_entropy_src_error_t |
Error codes (non-recoverable). | |
Enumerations | |
enum | dif_entropy_src_single_bit_mode { kDifEntropySrcSingleBitMode0 = 0, kDifEntropySrcSingleBitMode1 = 1, kDifEntropySrcSingleBitMode2 = 2, kDifEntropySrcSingleBitMode3 = 3, kDifEntropySrcSingleBitModeDisabled = 4 } |
A single-bit RNG mode, where only one bit is sampled. More... | |
enum | dif_entropy_src_main_fsm { kDifEntropySrcMainFsmStateIdle = 0x0f5, kDifEntropySrcMainFsmStateBootHTRunning = 0x1d2, kDifEntropySrcMainFsmStateBootPostHTChk = 0x16e, kDifEntropySrcMainFsmStateBootPhaseDone = 0x08e, kDifEntropySrcMainFsmStateStartupHTStart = 0x02c, kDifEntropySrcMainFsmStateStartupPhase1 = 0x101, kDifEntropySrcMainFsmStateStartupPass1 = 0x1a5, kDifEntropySrcMainFsmStateStartupFail1 = 0x017, kDifEntropySrcMainFsmStateContHTStart = 0x040, kDifEntropySrcMainFsmStateContHTRunning = 0x1a2, kDifEntropySrcMainFsmStateFWInsertStart = 0x0c3, kDifEntropySrcMainFsmStateFWInsertMsg = 0x059, kDifEntropySrcMainFsmStateSha3MsgDone = 0x10f, kDifEntropySrcMainFsmStateSha3Prep = 0x0f8, kDifEntropySrcMainFsmStateSha3Process = 0x0bf, kDifEntropySrcMainFsmStateSha3Valid = 0x171, kDifEntropySrcMainFsmStateSha3Done = 0x198, kDifEntropySrcMainFsmStateSha3Quiesce = 0x1cd, kDifEntropySrcMainFsmStateAlertState = 0x1fb, kDifEntropySrcMainFsmStateAlertHang = 0x15c, kDifEntropySrcMainFsmStateError = 0x13d } |
Main FSM state. | |
enum | dif_entropy_src_test { kDifEntropySrcTestRepetitionCount = 0, kDifEntropySrcTestRepetitionCountSymbol = 1, kDifEntropySrcTestAdaptiveProportion = 2, kDifEntropySrcTestBucket = 3, kDifEntropySrcTestMarkov = 4, kDifEntropySrcTestMailbox = 5, kDifEntropySrcTestNumVariants = 6 } |
A statistical test on the bits emitted by an entropy source. More... | |
enum | dif_entropy_src_sha3_state { kDifEntropySrcSha3StateIdle = 0, kDifEntropySrcSha3StateAbsorb = 1, kDifEntropySrcSha3StateSqueeze = 2, kDifEntropySrcSha3StateManualRun = 3, kDifEntropySrcSha3StateFlush = 4, kDifEntropySrcSha3StateError = 5 } |
SHA3 state machine states. More... | |
enum | dif_entropy_src_alert_cause { kDifEntropySrcAlertFipsEnableField = 1U << 0, kDifEntropySrcAlertEntropyDataRegEnField = 1U << 1, kDifEntropySrcAlertModuleEnableField = 1U << 2, kDifEntropySrcAlertThresholdScopeField = 1U << 3, kDifEntropySrcAlertRngBitEnableField = 1U << 5, kDifEntropySrcAlertFwOvSha3StartField = 1U << 7, kDifEntropySrcAlertFwOvModeField = 1U << 8, kDifEntropySrcAlertFwOvEntropyInsertField = 1U << 9, kDifEntropySrcAlertEsRouteField = 1U << 10, kDifEntropySrcAlertEsTypeField = 1U << 11, kDifEntropySrcAlertMainStateMachine = 1U << 12, kDifEntropySrcAlertDuplicateValue = 1U << 13, kDifEntropySrcAlertThresholdConfig = 1U << 14, kDifEntropySrcAlertFirmwareOverrideWrite = 1U << 15, kDifEntropySrcAlertFirmwareOverrideDisable = 1U << 16, kDifEntropySrcAlertAllAlerts = (1U << 17) - 1 } |
Recoverable alerts. More... | |
enum | dif_entropy_src_error { kDifEntropySrcErrorRngFifoWrite = 1U << 0, kDifEntropySrcErrorRngFifoRead = 1U << 1, kDifEntropySrcErrorRngFifoState = 1U << 2, kDifEntropySrcErrorObserveFifoWrite = 1U << 3, kDifEntropySrcErrorObserveFifoRead = 1U << 4, kDifEntropySrcErrorObserveFifoState = 1U << 5, kDifEntropySrcErrorFinalFifoWrite = 1U << 6, kDifEntropySrcErrorFinalFifoRead = 1U << 7, kDifEntropySrcErrorFinalFifoState = 1U << 8, kDifEntropySrcErrorAckStateMachine = 1U << 9, kDifEntropySrcErrorMainStateMachine = 1U << 10, kDifEntropySrcErrorHardenedCounter = 1U << 11 } |
Error codes (non-recoverable). More... | |
Entropy Source Device Interface Functions
Definition in file dif_entropy_src.h.
struct dif_entropy_src_fw_override_config |
Firmware override parameters for an entropy source.
Definition at line 82 of file dif_entropy_src.h.
struct dif_entropy_src_config |
Runtime configuration for an entropy source.
This struct describes runtime information for one-time configuration of the hardware.
Definition at line 105 of file dif_entropy_src.h.
Data Fields | ||
---|---|---|
uint16_t | alert_threshold |
The number of health test failures that must occur before an alert is triggered. When set to 0, alerts are disabled. |
bool | bypass_conditioner |
If set, raw entropy will be sent to CSRNG, bypassing the conditioner block and disabling the FIPS flag. Note that the FIPS flag is different from running the block in FIPS mode. FIPS mode refers to running the entropy_src in continuous mode. Also note that if |
bool | fips_enable |
If set, FIPS compliant entropy will be generated by this module after being processed by an SP 800-90B compliant conditioning function. Software may opt for implementing FIPS mode of operation without hardware support by setting this field to false. In such case, software is responsible for implementing the conditioning function. |
bool | health_test_threshold_scope |
Controls the scope (either by-line or by-sum) of the health tests. If true, the Adaptive Proportion and Markov Tests will accumulate all RNG input lines into a single score, and thresholds will be applied to the sum of all the entropy input lines. If false, the RNG input lines are all scored individually. A statistical deviation in any one input line, be it due to coincidence or failure, will force rejection of the sample, and count toward the total alert count. |
uint16_t | health_test_window_size |
The size of the window used for health tests. Units: bits |
bool | route_to_firmware | If set, entropy will be routed to a firmware-visible register instead of being distributed to other hardware IPs. |
dif_entropy_src_single_bit_mode_t | single_bit_mode |
Specifies which single-bit-mode to use, if any at all. FIPS mode of operation is disabled in single-bit-mode of operation is selected. |
struct dif_entropy_src_health_test_config |
Criteria used by various entropy source health tests to decide whether the test has failed.
Definition at line 214 of file dif_entropy_src.h.
Data Fields | ||
---|---|---|
uint32_t | high_threshold | The high threshold for the health test (contains both FIPS and bypass thresholds). |
uint32_t | low_threshold |
The low threshold for the health test (contains both FIPS and bypass thresholds). If the corresponding health test has no low threshold, set to 0, otherwise |
dif_entropy_src_test_t | test_type | The entropy source health test type to configure. |
struct dif_entropy_src_revision |
Revision information for an entropy source.
The fields of this struct have an implementation-specific interpretation.
Definition at line 239 of file dif_entropy_src.h.
Data Fields | ||
---|---|---|
uint8_t | abi_revision | |
uint8_t | chip_type | |
uint8_t | hw_revision |
struct dif_entropy_src_health_test_stats |
Statistics on entropy source health tests.
Definition at line 248 of file dif_entropy_src.h.
struct dif_entropy_src_alert_fail_counts |
Statistics on entropy source health tests failures that triggered alerts.
Definition at line 278 of file dif_entropy_src.h.
struct dif_entropy_src_debug_state |
Debug status information.
Definition at line 316 of file dif_entropy_src.h.
Data Fields | ||
---|---|---|
uint8_t | entropy_fifo_depth |
Depth of the entropy source FIFO. Valid range: [0, 7] |
bool | main_fsm_boot_done | Whether the main FSM is in the boot done state. |
bool | main_fsm_is_idle | Whether the main FSM is in the idle state. |
bool | sha3_absorbed | Whether the SHA3 preconditioner is in the absorbed state. |
bool | sha3_block_processed | Whether the SHA3 preconditioner has completed processing the current block. |
bool | sha3_error | Whether the SHA3 preconditioner has is in an error state. |
dif_entropy_src_sha3_state_t | sha3_fsm_state |
The current state of the SHA3 preconditioner state machine. See |
bool | sha3_squeezing | Whether the SHA3 preconditioner is in the squeezing state. |
typedef struct dif_entropy_src_config dif_entropy_src_config_t |
Runtime configuration for an entropy source.
This struct describes runtime information for one-time configuration of the hardware.
typedef struct dif_entropy_src_revision dif_entropy_src_revision_t |
Revision information for an entropy source.
The fields of this struct have an implementation-specific interpretation.
typedef enum dif_entropy_src_sha3_state dif_entropy_src_sha3_state_t |
SHA3 state machine states.
See hw/ip/kmac/rtl/sha3_pkg.sv
for more details.
Recoverable alerts.
Definition at line 358 of file dif_entropy_src.h.
Error codes (non-recoverable).
Definition at line 444 of file dif_entropy_src.h.
SHA3 state machine states.
See hw/ip/kmac/rtl/sha3_pkg.sv
for more details.
Definition at line 304 of file dif_entropy_src.h.
A single-bit RNG mode, where only one bit is sampled.
Definition at line 29 of file dif_entropy_src.h.
enum dif_entropy_src_test |
A statistical test on the bits emitted by an entropy source.
Definition at line 163 of file dif_entropy_src.h.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_clear_fifo_overflow | ( | const dif_entropy_src_t * | entropy_src | ) |
Clears the firmware override read FIFO overflow status.
entropy_src | An entropy source handle. |
Definition at line 612 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_clear_recoverable_alerts | ( | const dif_entropy_src_t * | entropy_src, |
uint32_t | alerts | ||
) |
Clears the alerts that are recoverable.
entropy_src | An entropy source handle. |
alerts | The alerts to be cleared (one or more dif_entropy_src_alert_t 's ORed together). |
Definition at line 677 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_conditioner_start | ( | const dif_entropy_src_t * | entropy_src | ) |
Starts conditioner operation.
Initializes the conditioner. Use the dif_entropy_src_observe_fifo_write()
function to send data to the conditioner, and dif_entropy_src_conditioner_stop()
once ready to stop the conditioner operation.
This function is only available when firmware override mode is enabled. See dif_entropy_src_fw_override_configure()
for more details.
entropy_src | An entropy source handle. |
Definition at line 549 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_conditioner_stop | ( | const dif_entropy_src_t * | entropy_src | ) |
Stops conditioner operation.
The conditioner stops processing input data and deposits the result digest in the entropy source output buffer. This operation is only available in firmware override mode.
entropy_src | An entropy source handle. |
Definition at line 569 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_configure | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_config_t | config, | ||
dif_toggle_t | enabled | ||
) |
Configures entropy source with runtime information.
This function should only need to be called once for the lifetime of the entropy
handle.
entropy_src | An entropy source handle. |
config | Runtime configuration parameters. |
enabled | The enablement state of the entropy source. |
Definition at line 51 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_error_force | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_error_t | error | ||
) |
Forces the hardware to generate a error for testing purposes.
entropy_src | An entropy source handle. |
error | The error to force (for testing purposes). |
Definition at line 770 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_fw_override_configure | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_fw_override_config_t | config, | ||
dif_toggle_t | enabled | ||
) |
Configures entropy source firmware override feature with runtime information.
This function should only need to be called once for the lifetime of the entropy
handle.
entropy_src | An entropy source handle. |
config | Runtime configuration parameters for firmware override. |
enabled | The enablement state of the firmware override option. |
Definition at line 145 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_get_alert_fail_counts | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_alert_fail_counts_t * | counts | ||
) |
Queries the entropy source for health test failure statistics.
entropy_src | An entropy source handle. | |
[out] | counts | Out-param for test failure data that triggers alerts. |
Definition at line 368 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_get_debug_state | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_debug_state_t * | debug_state | ||
) |
Reads the debug status register.
entropy_src | An entropy source handle. | |
[out] | debug_state | The current debug state of the IP. |
Definition at line 636 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_get_errors | ( | const dif_entropy_src_t * | entropy_src, |
uint32_t * | errors | ||
) |
Reads the (nonrecoverable) error code status register.
entropy_src | An entropy source handle. | |
[out] | errors | The errors that were triggered (one or more dif_entropy_src_error_t 's ORed together). |
Definition at line 692 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_get_fifo_depth | ( | const dif_entropy_src_t * | entropy_src, |
uint32_t * | fifo_depth | ||
) |
Read the firmware override FIFO depth.
entropy_src | An entropy source handle. | |
[out] | fifo_depth | The FIFO depth. |
Definition at line 624 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_get_health_test_stats | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_health_test_stats_t * | stats | ||
) |
Queries the entropy source for health test statistics.
entropy_src | An entropy source handle. | |
[out] | stats | Out-param for stats data. |
Definition at line 291 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_get_main_fsm_state | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_main_fsm_t * | state | ||
) |
Reads the current main FSM state.
entropy_src | An entropy source handle. | |
[out] | state | The current FSM state. |
Definition at line 813 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_get_recoverable_alerts | ( | const dif_entropy_src_t * | entropy_src, |
uint32_t * | alerts | ||
) |
Reads the recoverable alert status register.
entropy_src | An entropy source handle. | |
[out] | alerts | The alerts that were triggered (one or more dif_entropy_src_alert_t 's ORed together). |
Definition at line 665 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_get_revision | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_revision_t * | revision | ||
) |
Queries the entropy_src source IP for its revision information.
entropy_src | An entropy source handle. | |
[out] | revision | Out-param for revision data. |
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_has_fifo_overflowed | ( | const dif_entropy_src_t * | entropy_src, |
bool * | has_overflowed | ||
) |
Checks whether the firmware override read FIFO has overflowed.
entropy_src | An entropy source handle. | |
[out] | has_overflowed | Whether the FIFO has overflowed, and data has been lost. |
Definition at line 600 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_health_test_configure | ( | const dif_entropy_src_t * | entropy_src, |
dif_entropy_src_health_test_config_t | config | ||
) |
Configures an entropy source health test feature with runtime information.
This function should only need to be called once for each health test that requires configuration for the lifetime of the entropy
handle.
entropy_src | An entropy source handle. |
config | Runtime configuration parameters for the health test. |
Definition at line 176 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_is_entropy_available | ( | const dif_entropy_src_t * | entropy_src | ) |
Checks to see if entropy is available for software consumption.
entropy_src | An entropy source handle. |
Definition at line 430 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_is_fifo_full | ( | const dif_entropy_src_t * | entropy_src, |
bool * | is_full | ||
) |
Checks whether the firmware override write FIFO is full.
entropy_src | An entropy source handle. | |
[out] | is_full | Whether the FIFO is full. |
Definition at line 588 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_is_locked | ( | const dif_entropy_src_t * | entropy_src, |
bool * | is_locked | ||
) |
Checks whether this entropy source is locked.
entropy_src | An entropy source handle. | |
[out] | is_locked | Out-param for the locked state. |
Definition at line 269 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_lock | ( | const dif_entropy_src_t * | entropy_src | ) |
Locks out entropy source functionality.
This function is reentrant: calling it while functionality is locked will have no effect and return kDifEntropySrcOk
.
entropy_src | An entropy source handle. |
Definition at line 256 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_non_blocking_read | ( | const dif_entropy_src_t * | entropy_src, |
uint32_t * | word | ||
) |
Reads a word of entropy from the entropy source.
entropy_src | An entropy source handle. | |
[out] | word | Out-param for the entropy word. |
Definition at line 439 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_observe_fifo_blocking_read | ( | const dif_entropy_src_t * | entropy_src, |
uint32_t * | buf, | ||
size_t | len | ||
) |
Performs a blocking read from the entropy pipeline through the observe FIFO, which contains post-test, unconditioned entropy.
The entropy source must be configured with firmware override mode enabled, and the len
parameter must be less than or equal to the FIFO threshold set in the firmware override parameters (that is, the threshold that triggers an interrupt). Additionally, buf
may be NULL
; in this case, reads will be discarded.
entropy_src | An entropy source handle. | |
[out] | buf | A buffer to fill with words from the pipeline. |
len | The number of words to read into buf . |
Definition at line 462 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_observe_fifo_write | ( | const dif_entropy_src_t * | entropy_src, |
const uint32_t * | buf, | ||
size_t | len, | ||
size_t * | written | ||
) |
Performs a write to the entropy pipeline through the observe FIFO.
Entropy source must be configured with firmware override and insert mode enabled, otherwise the function will return kDifError
.
entropy_src | An entropy source handle. | |
buf | A buffer to push words from into the pipeline. | |
len | The number of words to write from buf . | |
[out] | written | The number of words successfully written. |
Definition at line 510 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_set_enabled | ( | const dif_entropy_src_t * | entropy_src, |
dif_toggle_t | enabled | ||
) |
Enables/Disables the entropy source.
entropy_src | An entropy source handle. |
enabled | The enablement state to configure the entropy source in. |
Definition at line 238 of file dif_entropy_src.c.
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_stop | ( | const dif_entropy_src_t * | entropy_src | ) |
Stops the current mode of operation and disables the entropy_src module.
entropy_src | An entropy source handle. |
Definition at line 17 of file dif_entropy_src.c.