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

(c4666f4)

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,
  kDifEntropySrcMainFsmStateSha3Process = 0x0f8,
  kDifEntropySrcMainFsmStateSha3Valid = 0x0bf,
  kDifEntropySrcMainFsmStateSha3Done = 0x198,
  kDifEntropySrcMainFsmStateAlertState = 0x1cd,
  kDifEntropySrcMainFsmStateAlertHang = 0x1fb,
  kDifEntropySrcMainFsmStateError = 0x73
}
 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,
  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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_lock (const dif_entropy_src_t *entropy_src)
 Locks out entropy source functionality. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_conditioner_start (const dif_entropy_src_t *entropy_src)
 Starts conditioner operation. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_entropy_src_conditioner_stop (const dif_entropy_src_t *entropy_src)
 Stops conditioner operation. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

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

Runtime configuration for an entropy source.

This struct describes runtime information for one-time configuration of the hardware.

◆ 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

SHA3 state machine states.

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

Enumeration Type Documentation

◆ 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

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_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

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

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_srcAn entropy source handle.
alertsThe 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_srcAn 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_srcAn 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_srcAn entropy source handle.
configRuntime configuration parameters.
enabledThe 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_srcAn entropy source handle.
errorThe 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_srcAn entropy source handle.
bufA buffer to push words from into the pipeline.
lenThe number of words to write from buf.
[out]writtenThe 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_srcAn entropy source handle.
configRuntime configuration parameters for firmware override.
enabledThe 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_srcAn entropy source handle.
enabledWhether 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_srcAn entropy source handle.
[out]countsOut-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_srcAn entropy source handle.
[out]debug_stateThe 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_srcAn entropy source handle.
[out]errorsThe 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_srcAn entropy source handle.
[out]fifo_depthThe 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_srcAn entropy source handle.
[out]statsOut-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_srcAn entropy source handle.
[out]stateThe 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_srcAn entropy source handle.
[out]alertsThe 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_srcAn entropy source handle.
[out]revisionOut-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_srcAn entropy source handle.
[out]has_overflowedWhether 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_srcAn entropy source handle.
configRuntime 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_srcAn 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_srcAn entropy source handle.
[out]is_fullWhether 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_srcAn entropy source handle.
[out]is_lockedOut-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_srcAn 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_srcAn entropy source handle.
[out]wordOut-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_srcAn entropy source handle.
[out]bufA buffer to fill with words from the pipeline.
lenThe 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_srcAn entropy source handle.
[out]bufA buffer to fill with words from the pipeline.
[in,out]lenA 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_srcAn entropy source handle.
enabledThe 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_srcAn entropy source handle.
Returns
The result of the operation.

Definition at line 17 of file dif_entropy_src.c.