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"

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.

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.

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.

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 , kDifEntropySrcMainFsmStateSha3Process = 0x0f8 , kDifEntropySrcMainFsmStateSha3Valid = 0x0bf , kDifEntropySrcMainFsmStateSha3Done = 0x198 , kDifEntropySrcMainFsmStateAlertState = 0x1cd , kDifEntropySrcMainFsmStateAlertHang = 0x1fb , kDifEntropySrcMainFsmStateError = 0x73 }
	Main FSM state. More...

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 , kDifEntropySrcAlertFipsFlagField = 1U << 17 , kDifEntropySrcAlertRngFipsField = 1U << 18 , kDifEntropySrcAlertAllAlerts = (1U << 19) - 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...

Functions
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.

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.

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.

OT_WARN_UNUSED_RESULT dif_result_t	dif_entropy_src_fw_override_sha3_start_insert (const dif_entropy_src_t *entropy_src, dif_toggle_t enabled)
	Configures whether to start the entropy source's SHA3 process and be ready to accept entropy data.

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.

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.

OT_WARN_UNUSED_RESULT dif_result_t	dif_entropy_src_lock (const dif_entropy_src_t *entropy_src)
	Locks out entropy source functionality.

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.

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.

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.

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.

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.

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.

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 health-test, unconditioned entropy.

OT_WARN_UNUSED_RESULT dif_result_t	dif_entropy_src_observe_fifo_nonblocking_read (const dif_entropy_src_t entropy_src, uint32_t buf, size_t *len)
	Performs a nonblocking read from the entropy pipeline through the observe FIFO, which contains post health-test, unconditioned entropy.

OT_WARN_UNUSED_RESULT dif_result_t	dif_entropy_src_fw_ov_data_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 firmware override FIFO.

OT_WARN_UNUSED_RESULT dif_result_t	dif_entropy_src_conditioner_start (const dif_entropy_src_t *entropy_src)
	Starts conditioner operation.

OT_WARN_UNUSED_RESULT dif_result_t	dif_entropy_src_conditioner_stop (const dif_entropy_src_t *entropy_src)
	Stops conditioner operation.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Detailed Description

Entropy Source Device Interface Functions

Definition in file dif_entropy_src.h.

Data Structure Documentation

◆ dif_entropy_src_fw_override_config

struct dif_entropy_src_fw_override_config

Firmware override parameters for an entropy source.

Definition at line 80 of file dif_entropy_src.h.

Data Fields

uint8_t buffer_threshold This field sets the depth of the observe FIFO hardware buffer used when the firmware override feature is enabled.

bool

entropy_insert_enable

Enables firmware to insert entropy bits back into the pre-conditioner FIFO via dif_entropy_src_fw_ov_data_write() calls.

This feature is useful when the firmware is required to implement additional health checks, and to perform known answer tests of the conditioner.

To take effect, this requires the firmware override feature to be enabled.

◆ dif_entropy_src_config

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 103 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 `fips_enable` is set to `True`, then at most one of either `route_to_firmware` or `bypass_conditioner` may be set, but will result in disabling the FIPS mode of operation from a hardware perspective.
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	fips_flag	If set, the produced output entropy is marked as FIPS compliant through the FIPS bit being set to high.
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	rng_fips	If set, the noise source is instructed to produce high quality entropy.
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.

◆ dif_entropy_src_health_test_config

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 221 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_health_test_configure()` will return `kDifBadArg`.
dif_entropy_src_test_t	test_type	The entropy source health test type to configure.

◆ dif_entropy_src_revision

struct dif_entropy_src_revision

Revision information for an entropy source.

The fields of this struct have an implementation-specific interpretation.

Definition at line 246 of file dif_entropy_src.h.

Data Fields
uint8_t	abi_revision
uint8_t	chip_type
uint8_t	hw_revision

◆ dif_entropy_src_health_test_stats

struct dif_entropy_src_health_test_stats

Statistics on entropy source health tests.

Definition at line 255 of file dif_entropy_src.h.

Data Fields
uint32_t	high_fails[kDifEntropySrcTestNumVariants]	The number of times a particular test has failed above the high threshold (contains both FIPS and bypass watermarks).
uint16_t	high_watermark[kDifEntropySrcTestNumVariants]	High watermark indicating the highest value emitted by a particular test.
uint32_t	low_fails[kDifEntropySrcTestNumVariants]	The number of times a particular test has failed below the low threshold. Note, some health tests do not have a low threshold. For these tests, this value will always be 0.
uint16_t	low_watermark[kDifEntropySrcTestNumVariants]	Low watermark indicating the lowest value emitted by a particular test (contains both FIPS and bypass watermarks). Note, some health tests do not emit a low watermark as there is no low threshold. For these tests, this value will always be UINT16_MAX.

◆ dif_entropy_src_alert_fail_counts

struct dif_entropy_src_alert_fail_counts

Statistics on entropy source health tests failures that triggered alerts.

Definition at line 285 of file dif_entropy_src.h.

Data Fields
uint8_t	high_fails[kDifEntropySrcTestNumVariants]	The number of test failures, due to the specific test execeeding the high threshold, that cause alerts to be fired.
uint8_t	low_fails[kDifEntropySrcTestNumVariants]	The number of test failures, due to the specific test execeeding the low threshold, that cause alerts to be fired. Note, some health tests do not have a low threshold. For these tests, this value will always be 0.
uint16_t	total_fails	The total number of test failures, across all test types, that contributed to the alerts fired.

◆ dif_entropy_src_debug_state

struct dif_entropy_src_debug_state

Debug status information.

Definition at line 323 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 `dif_entropy_src_sha3_state_t` for more details.
bool	sha3_squeezing	Whether the SHA3 preconditioner is in the squeezing state.

Typedef Documentation

◆ dif_entropy_src_config_t

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.

◆ dif_entropy_src_revision_t

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.

◆ dif_entropy_src_sha3_state_t

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.

Enumeration Type Documentation

◆ dif_entropy_src_alert_cause

enum dif_entropy_src_alert_cause

Recoverable alerts.

Enumerator
kDifEntropySrcAlertFipsEnableField	Triggered when the FIPS_ENABLE field in the CONF register is set to an unsupported value.
kDifEntropySrcAlertEntropyDataRegEnField	Triggered when the ENTROPY_DATA_REG_ENABLE field in the CONF register is set to an unsupported value.
kDifEntropySrcAlertModuleEnableField	Triggered when the MODULE_ENABLE field in the MODULE_ENABLE register is set to an unsupported value.
kDifEntropySrcAlertThresholdScopeField	Triggered when the THRESHOLD_SCOPE field in the CONF register is set to an unsupported value.
kDifEntropySrcAlertRngBitEnableField	Triggered when the RNG_BIT_ENABLE field in the CONF register is set to an unsupported value.
kDifEntropySrcAlertFwOvSha3StartField	Triggered when the FW_OV_SHA3_START field in the FW_OV_SHA3_START register is set to an unsupported value.
kDifEntropySrcAlertFwOvModeField	Triggered when the FW_OV_MODE field in the FW_OV_CONTROL register is set to an unsupported value.
kDifEntropySrcAlertFwOvEntropyInsertField	Triggered when the FW_OV_ENTROPY_INSERT field in the FW_OV_CONTROL register is set to an unsupported value.
kDifEntropySrcAlertEsRouteField	Triggered when the ES_ROUTE field in the ENTROPY_CONTROL register is set to an unsupported value.
kDifEntropySrcAlertEsTypeField	Triggered when the ES_TYPE field in the ENTROPY_CONTROL register is set to an unsupported value.
kDifEntropySrcAlertMainStateMachine	Triggered when the main state machine detects a threshold failure state.
kDifEntropySrcAlertDuplicateValue	Triggered when the internal entropy bus value is equal to the prior valid value on the bus, indicating a possible attack.
kDifEntropySrcAlertThresholdConfig	Triggered when the ALERT_THRESHOLD register is not configured properly, i.e., the upper field must be the exact inverse of the lower field.
kDifEntropySrcAlertFirmwareOverrideWrite	Triggered when the packer FIFO has been written but was full at the time and we are in FW_OV_MODE and FW_OV_ENTROPY_INSERT modes.
kDifEntropySrcAlertFirmwareOverrideDisable	Triggered when FW_OV_SHA3_START has been set to kMultiBitBool4False, without waiting for the bypass packer FIFO to clear.
kDifEntropySrcAlertFipsFlagField	Triggered when the FIPS_FLAG field in the CONF register is set to an unsupported value.
kDifEntropySrcAlertRngFipsField	Triggered when the RNG_FIPS field in the CONF register is set to an unsupported value.
kDifEntropySrcAlertAllAlerts	All alert reasons. This is useful when clearing all recoverable alerts at once.

Definition at line 365 of file dif_entropy_src.h.

◆ dif_entropy_src_error

enum dif_entropy_src_error

Error codes (non-recoverable).

Enumerator
kDifEntropySrcErrorRngFifoWrite	Triggered when a write error has been detected for the esrng FIFO.
kDifEntropySrcErrorRngFifoRead	Triggered when a read error has been detected for the esrng FIFO.
kDifEntropySrcErrorRngFifoState	Triggered when a state error has been detected for the esrng FIFO.
kDifEntropySrcErrorObserveFifoWrite	Triggered when a write error has been detected for the observe FIFO.
kDifEntropySrcErrorObserveFifoRead	Triggered when a read error has been detected for the observe FIFO.
kDifEntropySrcErrorObserveFifoState	Triggered when a state error has been detected for the observe FIFO.
kDifEntropySrcErrorFinalFifoWrite	Triggered when a write error has been detected for the esfinal FIFO.
kDifEntropySrcErrorFinalFifoRead	Triggered when a read error has been detected for the esfinal FIFO.
kDifEntropySrcErrorFinalFifoState	Triggered when a state error has been detected for the esfinal FIFO.
kDifEntropySrcErrorAckStateMachine	Triggered when an error has been detected for the acknowledgment stage state machine.
kDifEntropySrcErrorMainStateMachine	Triggered when an error has been detected for the main state machine.
kDifEntropySrcErrorHardenedCounter	Triggered when an error has been detected for a hardened counter.

Definition at line 461 of file dif_entropy_src.h.

◆ dif_entropy_src_main_fsm

enum dif_entropy_src_main_fsm

Main FSM state.

Definition at line 55 of file dif_entropy_src.h.

◆ dif_entropy_src_sha3_state

enum dif_entropy_src_sha3_state

SHA3 state machine states.

See hw/ip/kmac/rtl/sha3_pkg.sv for more details.

Definition at line 311 of file dif_entropy_src.h.

◆ dif_entropy_src_single_bit_mode

enum dif_entropy_src_single_bit_mode

A single-bit RNG mode, where only one bit is sampled.

Enumerator
kDifEntropySrcSingleBitMode0	Single-bit-mode, sampling the zeroth bit.
kDifEntropySrcSingleBitMode1	Single-bit-mode, sampling the first bit.
kDifEntropySrcSingleBitMode2	Single-bit-mode, sampling the second bit.
kDifEntropySrcSingleBitMode3	Single-bit-mode, sampling the third bit.
kDifEntropySrcSingleBitModeDisabled	Indicates that single-bit-mode is disabled.

Definition at line 29 of file dif_entropy_src.h.

◆ dif_entropy_src_test

enum dif_entropy_src_test

A statistical test on the bits emitted by an entropy source.

Enumerator
kDifEntropySrcTestRepetitionCount	An SP 800-90B repetition count test. This test screens for stuck bits, or a total failure of the noise source. This test fails if any sequence of bits repeats too many times in a row for too many samples.
kDifEntropySrcTestRepetitionCountSymbol	An SP 800-90B symbol repetition count test. This is similar to the above, test but is performed on a symbol, instead of bit, basis.
kDifEntropySrcTestAdaptiveProportion	An SP 800-90B adaptive proportion test. This test screens for statistical bias in the number of ones or zeros output by the noise source.
kDifEntropySrcTestBucket	A bucket test. This test looks for correlations between individual noise channels.
kDifEntropySrcTestMarkov	A "Markov" test. This test looks for unexpected first-order temporal correlations between individual noise channels.
kDifEntropySrcTestMailbox	A firmware-driven "mailbox" test. This test allows firmware to inspect 2kbit blocks of entropy, and signal potential concerns to the hardware.

Definition at line 170 of file dif_entropy_src.h.

Function Documentation

◆ dif_entropy_src_clear_recoverable_alerts()

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.

Parameters

entropy_src	An entropy source handle.
alerts	The alerts to be cleared (one or more `dif_entropy_src_alert_t`'s ORed together).

Returns: The result of the operation.

Definition at line 722 of file dif_entropy_src.c.

◆ dif_entropy_src_conditioner_start()

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_fw_ov_data_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.

Parameters

entropy_src An entropy source handle.

Returns: The result of the operation.

Definition at line 606 of file dif_entropy_src.c.

◆ dif_entropy_src_conditioner_stop()

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.

Parameters

entropy_src An entropy source handle.

Returns: The result of the operation.

Definition at line 626 of file dif_entropy_src.c.

◆ dif_entropy_src_configure()

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.

Parameters

entropy_src	An entropy source handle.
config	Runtime configuration parameters.
enabled	The enablement state of the entropy source.

Returns: The result of the operation.

Definition at line 51 of file dif_entropy_src.c.

◆ dif_entropy_src_error_force()

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.

Parameters

entropy_src	An entropy source handle.
error	The error to force (for testing purposes).

Returns: The result of the operation.

Definition at line 815 of file dif_entropy_src.c.

◆ dif_entropy_src_fw_ov_data_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_fw_ov_data_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 firmware override FIFO.

Entropy source must be configured with firmware override and insert mode enabled, otherwise the function will return kDifError.

Parameters

	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.

Returns: The result of the operation.

Definition at line 567 of file dif_entropy_src.c.

◆ dif_entropy_src_fw_override_configure()

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.

Parameters

entropy_src	An entropy source handle.
config	Runtime configuration parameters for firmware override.
enabled	The enablement state of the firmware override option.

Returns: The result of the operation.

Definition at line 155 of file dif_entropy_src.c.

◆ dif_entropy_src_fw_override_sha3_start_insert()

OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_fw_override_sha3_start_insert	(	const dif_entropy_src_t *	entropy_src,
		dif_toggle_t	enabled )

Configures whether to start the entropy source's SHA3 process and be ready to accept entropy data.

This is used in firmware override mode and should be enabled before writing to the override FIFO. Disable this after writing has finished to ensure the SHA3 block finishes processing and pushes the results to the esfinal FIFO.

Parameters

entropy_src	An entropy source handle.
enabled	Whether to start the SHA3 process.

Definition at line 186 of file dif_entropy_src.c.

◆ dif_entropy_src_get_alert_fail_counts()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	counts	Out-param for test failure data that triggers alerts.

Returns: The result of the operation.

Definition at line 393 of file dif_entropy_src.c.

◆ dif_entropy_src_get_debug_state()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	debug_state	The current debug state of the IP.

Returns: The result of the operation.

Definition at line 681 of file dif_entropy_src.c.

◆ dif_entropy_src_get_errors()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	errors	The errors that were triggered (one or more `dif_entropy_src_error_t`'s ORed together).

Returns: The result of the operation.

Definition at line 737 of file dif_entropy_src.c.

◆ dif_entropy_src_get_fifo_depth()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	fifo_depth	The FIFO depth.

Returns: The result of the operation.

Definition at line 669 of file dif_entropy_src.c.

◆ dif_entropy_src_get_health_test_stats()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	stats	Out-param for stats data.

Returns: The result of the operation.

Definition at line 316 of file dif_entropy_src.c.

◆ dif_entropy_src_get_main_fsm_state()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	state	The current FSM state.

Returns: The result of the operation.

Definition at line 858 of file dif_entropy_src.c.

◆ dif_entropy_src_get_recoverable_alerts()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	alerts	The alerts that were triggered (one or more `dif_entropy_src_alert_t`'s ORed together).

Returns: The result of the operation.

Definition at line 710 of file dif_entropy_src.c.

◆ dif_entropy_src_get_revision()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	revision	Out-param for revision data.

Returns: The result of the operation.

◆ dif_entropy_src_has_fifo_overflowed()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	has_overflowed	Whether the FIFO has overflowed, and data has been lost.

Returns: The result of the operation.

Definition at line 657 of file dif_entropy_src.c.

◆ dif_entropy_src_health_test_configure()

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.

Parameters

entropy_src	An entropy source handle.
config	Runtime configuration parameters for the health test.

Returns: The result of the operation.

Definition at line 201 of file dif_entropy_src.c.

◆ dif_entropy_src_is_entropy_available()

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.

Parameters

entropy_src An entropy source handle.

Returns: The result of the operation.

Definition at line 455 of file dif_entropy_src.c.

◆ dif_entropy_src_is_fifo_full()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	is_full	Whether the FIFO is full.

Returns: The result of the operation.

Definition at line 645 of file dif_entropy_src.c.

◆ dif_entropy_src_is_locked()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 294 of file dif_entropy_src.c.

◆ dif_entropy_src_lock()

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.

Parameters

entropy_src An entropy source handle.

Returns: The result of the operation.

Definition at line 281 of file dif_entropy_src.c.

◆ dif_entropy_src_non_blocking_read()

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.

Parameters

	entropy_src	An entropy source handle.
[out]	word	Out-param for the entropy word.

Returns: The result of the operation.

Definition at line 464 of file dif_entropy_src.c.

◆ dif_entropy_src_observe_fifo_blocking_read()

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 health-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.

Parameters

	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`.

Returns: The result of the operation.

Definition at line 487 of file dif_entropy_src.c.

◆ dif_entropy_src_observe_fifo_nonblocking_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_observe_fifo_nonblocking_read	(	const dif_entropy_src_t *	entropy_src,
		uint32_t *	buf,
		size_t *	len )

Performs a nonblocking read from the entropy pipeline through the observe FIFO, which contains post health-test, unconditioned entropy.

The entropy source must be configured with firmware override mode enabled. This function will read at most *len words from the observe FIFO and store them in buf if it is not NULL. If buf is NULL then the reads will be discarded instead. This function never blocks and returns as soon as the FIFO is empty. It updates *len to store the number of actually read words.

Parameters

	entropy_src	An entropy source handle.
[out]	buf	A buffer to fill with words from the pipeline.
[in,out]	len	A pointer to the maximum number of words to reads. This value is updated to contain the number of words acually read.

Returns: The result of the operation.

Definition at line 535 of file dif_entropy_src.c.

◆ dif_entropy_src_set_enabled()

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.

Parameters

entropy_src	An entropy source handle.
enabled	The enablement state to configure the entropy source in.

Returns: The result of the operation.

Definition at line 263 of file dif_entropy_src.c.

◆ dif_entropy_src_stop()

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.

Parameters

entropy_src An entropy source handle.

Returns: The result of the operation.

Definition at line 17 of file dif_entropy_src.c.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_entropy_src_fw_override_config

◆ dif_entropy_src_config

◆ dif_entropy_src_health_test_config

◆ dif_entropy_src_revision

◆ dif_entropy_src_health_test_stats

◆ dif_entropy_src_alert_fail_counts

◆ dif_entropy_src_debug_state

Typedef Documentation

◆ dif_entropy_src_config_t

◆ dif_entropy_src_revision_t

◆ dif_entropy_src_sha3_state_t

Enumeration Type Documentation

◆ dif_entropy_src_alert_cause

◆ dif_entropy_src_error

◆ dif_entropy_src_main_fsm

◆ dif_entropy_src_sha3_state

◆ dif_entropy_src_single_bit_mode

◆ dif_entropy_src_test

Function Documentation

◆ dif_entropy_src_clear_recoverable_alerts()

◆ dif_entropy_src_conditioner_start()

◆ dif_entropy_src_conditioner_stop()

◆ dif_entropy_src_configure()

◆ dif_entropy_src_error_force()

◆ dif_entropy_src_fw_ov_data_write()

◆ dif_entropy_src_fw_override_configure()

◆ dif_entropy_src_fw_override_sha3_start_insert()

◆ dif_entropy_src_get_alert_fail_counts()

◆ dif_entropy_src_get_debug_state()

◆ dif_entropy_src_get_errors()

◆ dif_entropy_src_get_fifo_depth()

◆ dif_entropy_src_get_health_test_stats()

◆ dif_entropy_src_get_main_fsm_state()

◆ dif_entropy_src_get_recoverable_alerts()

◆ dif_entropy_src_get_revision()

◆ dif_entropy_src_has_fifo_overflowed()

◆ dif_entropy_src_health_test_configure()

◆ dif_entropy_src_is_entropy_available()

◆ dif_entropy_src_is_fifo_full()

◆ dif_entropy_src_is_locked()

◆ dif_entropy_src_lock()

◆ dif_entropy_src_non_blocking_read()

◆ dif_entropy_src_observe_fifo_blocking_read()

◆ dif_entropy_src_observe_fifo_nonblocking_read()

◆ dif_entropy_src_set_enabled()

◆ dif_entropy_src_stop()