ENTROPY_SRC HWIP Technical Specification

Overview

This document specifies ENTROPY_SRC hardware IP functionality. This module conforms to the Comportable guideline for peripheral functionality.

Features

  • This revision supports a LFSR (linear feedback shift register) digital source, and provides an interface to an external rng (random noise generator) source. The LFSR is used as a digital, pseudo-random type of entropy source, while the rng external source is a true entropy source. A noise source and its relation to an entropy source are defined by SP 800-90B.
  • A set of registers is provided for firmware to manage and obtain entropy bits.
  • The set of registers is designed such that firmware can select between a digital or an rng entropy source.
  • Interrupts are supported:
    • Entropy bits are available for firmware consumption.
    • The external rng entropy source is available.
    • The internal health tests have detected a repetitive count test fail.
    • The internal health tests have detected an adaptive proportion test fail.
    • An internal FIFO error has occurred.
  • Two health checks that are defined by SP 800-90B are performed by this revision: Repetition Count and Adaptive Proportion tests.
  • No alerts are supported by this revision.

Description

This IP block provides an entropy source that is part of a larger solution to generate true random numbers (a TRNG mechanism). The general solution for TRNG relies on either hardware or firmware to implement this function, depending which functions are enabled by firmware or e-fuses. For purposes of reference in this document, the NIST term “noise” will be synonymous with the term “entropy”. Likewise, no conditioning function will be performed in this block. For the generation of entropy, this block provides the entropy bits needed for the entropy source solution as required by the RNG mechanism.

At a high-level, this ENTROPY_SRC block, when enabled, will continuously collect entropy bits from the entropy source into a FIFO that can be read from the TLUL bus, or sent out through a hardware interface. The rng source will generate a relative slow set of bit streams, in the tens of kilohertz range. The digital source can be programmed to be faster, or much slower if desired. A digital source rate of flexiable speed might be useful in demonstrating how the downstream applications use the entropy.

Once the threshold has been reached for collected entropy bits, the firmware has two options of notification: an interrupt, or polling. The es_entropy_valid bit will be set when the ES_THRESH register value is equal or less than the number of elements in the TLUL FIFO. Optionally, an interrupt may be a better use of CPU cycles. For the hardware interface, entropy bits will be transferred whenever the downstream consumer is ready to receive them.

Compatibility

This IP block does not have any direct hardware compatibility requirements. The firmware routines, as described by SP 800-90B, must be supported. However, as long as the function provided by the register set supports all of the call parameters, any compatibility requirements will be met.

Theory of Operations

As already described, this IP block will collect bits of entropy for firmware or hardware consumption. This revision supports both an LFSR for the digital implementation, and an external interface for the rng implementation. For the LRSR implementation, any polynomial may be used so long as it is primitive in Galois Field of order 2, or GF(2). However, preference should be given to polynomials with the fewest number of terms.

The first step is initialization and enabling. Before setting the ENABLE field, the LFSR seed input should be initialized, using the ES_SEED register. The ES_SEED register will transfer its value according to the initialization sequence. After the block is enabled and initialized, entropy bits will be collected up indefinitely until disabled. If rng mode is desired, the RNG_SRC_EN bit can be set at the same time as the ENABLE field can be set to enable rng mode.

It is assumed that any entropy source will drop bits. This means that the FIFO used to collect up the entropy bits will fill, and until the firmware or hardware starts pulling out bits, continuously generated entropy source bits may be dropped from usage. The process of filling and draining the FIFOs is the same, independent of what speed the entropy generation rate is at.

Once the es_entropy_valid status bit is set, the firmware will read the ES_ENTROPY register as many times as needed to get the required entropy bits, typically 128 bits or 256 bits at a time. For ease of firmware operation, the status bit does not need to be reset. A read of the ES_THRESH register could be done to verify how many entries are in the FIFO at the current time. The ES_THRESH register will determine when the status bit is set, or when the interrupt will assert if enabled. For this revision, this same ES_THRESH register has a range of between 1 and 4 entries in the TLUL FIFO.

For hardware consumption of entropy, if the HWIF FIFO is not empty, and the entropy consuming hardware is ready, then entropy bits will be transferred over the hardware entropy interface.

Health tests, when enabled in the ES_CONF register, will run continuously. Two tests are implemented in hardware, the repetition count test (RCT), and the adaptive proportion test (APT).

There are four health test blocks, one per inbound rng bus bit. Each health test block works independently from one another. The checks are done on the serial stream input, and an optional feature allows for passing entropy from a single bit stream source. Once the streams have passed the health tests, it becomes available for downstream consumption. If the health tests ever fail, the ES FIFO is prevented from receiving additional entropy bits up. The entropy health tests will continue until a clean stream is detected, at which time the ES FIFO will start collecting bits again. The ES_RCT_HEALTH register and the ES_APT_HEALTH register set the cutoff limits for the health tests.

The above process will be repeated for as long as entropy bits are to be collected. At any time, the enable bit can be cleared, and the entropy generation will halt immediately.

Block Diagram

ENTROPY_SRC Block Diagram

Hardware Interfaces

Referring to the Comportable guideline for peripheral device functionality, the module entropy_src has the following hardware interfaces defined.

Primary Clock: clk_i

Other Clocks: none

Bus Device Interface: tlul

Bus Host Interface: none

Peripheral Pins for Chip IO: none

Interrupts:

Interrupt NameDescription
es_entropy_validAsserted when entropy source bits are available.
es_rct_failedAsserted when the repetitive count test fails.
es_apt_failedAsserted when the adaptive proportion test fails.
es_fifo_errAsserted when a FIFO error occurs.

Security Alerts: none

Design Details

Initialization

After power-up, the ENTROPY_SRC block is disabled. In this state, the seed register will continuously be loaded into the LFSR. The seed register can be written without restriction, regardless of any state of any control bits.

A configuration/control register locking function is performed by the ES_REGEN register. Clearing the bit in this register will prevent future modification of the ES_CONF register or the ES_SEED by firmware.

The ES_SEED register can be updated at any time while the digital source FIFO is in operational mode. As long as the update sequence is followed by firmware, there will be no timing hazards when accessing these registers by the firmware.

Entropy Processing

When enabled, the ENTROPY_SRC block will generate entropy bits continuously. The es_entropy_valid bit signal to the firmware when entropy bits should read from the ES_ENTROPY register. While the firmware is reading the TLUL FIFO, additional entropy bits could be captured by the TLUL FIFO as long as the TLUL FIFO is not full. The firmware will do 32-bit register reads of the ES_ENTROPY register to retrieve the entropy bits. Each read will automatically pop an entry off the head of the TLUL FIFO. New entropy bits can enter the TLUL FIFO at the tail concurrently.

The hardware entropy interface will move entropy bits out of the HWIF FIFO when it is not empty and the downstream hardware is ready. The HWIF FIFO has lower priority than the TLUL FIFO, but is expected to have higher bandwidth demands. Because of this, higher priority is given to the TLUL FIFO so that it does not starve when the hardware entropy interface is consuming a high level of entropy bits.

The ES_THRESH register is used to set the point of notification to the firmware. Notification can be either by polling or by an interrupt. For debug, the ES_FDEPTHST register can be read to find out the current state of the TLUL FIFO at any time.

An additional feature is the ES_RATE register. The purpose of this register is to simulate faster or slower entropy generation sources when is digial source mode. This will aid firmware design and debug when trying to handle all entropy source types and rates. When in rng mode, this register must exactly match the sample rate required by the rng source, expected to be in the range of about 25 to 50 kilohertz.

Interrupts

The ENTROPY_SRC module has several interrupts: es_entropy_valid, es_rng_src_ok, es_rct_failed, es_apt_failed, and es_fifo_err`.

The es_entropy_valid interrupt should be used when a entropy source has been implemented that is relatively slow.

The es_rng_src_ok interrupt should be used when rng entropy mode has been selected. Once the external entropy source is operational, this interrupt will be triggered.

The es_rct_failed interrupt will trigger when the internal health test fails the repetitive count test.

The es_apt_failed interrupt will trigger when the internal health test fails the adaptive proportion test.

The es_fifo_err interrupt will fire when a non-rng FIFO has a malfunction. The conditions that cause this to happen are either when there is a push to a full FIFO or a pull from an empty FIFO.

TLUL FIFO Operational Sequence

The following waveform shows an example of how the entropy source is collected into the TLUL FIFO. In this example, the TLUL FIFO parameter is fixed to a depth of 4. The ES_THRESH register is set to a value of 2, and will trigger an interrupt when the FIFO has met this value. The FIFO in this example will fill quickly, then will drain as the firmware reads the ES_ENTROPY register. As the entropy bits are read out, new entropy bits, if available and valid, will immediately enter the FIFO.

Entropy Source Hardware Interface

The following waveform shows an example of how the entropy source hardware interface works, which is much like a FIFO.

RNG Hardware Interface

The following waveform shows an example of what the RNG timing looks like.

Programmers Guide

Initialization

The following code snippet demonstrates initializing the ENTROPY_SRC block for entropy bit generation.


void entropy_src_init(unsigned int seed, unsigned int thresh) {

  // set the seed value
  *ES_SEED_REG = seed;

  // set the threshold value
  *ES_THRESH_REG = thresh;

  // set the configuration enable bits (digial mode)
  *ES_CONF_REG = 0x1;

  // or set the configuration enable bits (rng mode)
  *ES_CONF_REG = 0x2;

  // the ENTROPY_SRC interrupts can optionally be enabled
}

Entropy Processing

The following code snippet demonstrates reading entropy bits from the ENTROPY_SRC block.


int entropy_src_entropy(unsigned int numEntropyBits) {

  // read numEntropyBits, check for ENTROPY_SRC_INTR_STATE bit 0 
  return *ES_ENTROPY_REG;

}

Error conditions

Need to alert the system of a FIFO overflow condition.

Register Table

entropy_src.INTR_STATE @ + 0x0
Interrupt State Register
Reset default = 0x0, mask 0xf
31302928272625242322212019181716
 
1514131211109876543210
  es_fifo_err es_apt_failed es_rct_failed es_entropy_valid
BitsTypeResetNameDescription
0rw1c0x0es_entropy_validAsserted when entropy source bits are available.
1rw1c0x0es_rct_failedAsserted when the repetitive count test fails.
2rw1c0x0es_apt_failedAsserted when the adaptive proportion test fails.
3rw1c0x0es_fifo_errAsserted when a FIFO error occurs.


entropy_src.INTR_ENABLE @ + 0x4
Interrupt Enable Register
Reset default = 0x0, mask 0xf
31302928272625242322212019181716
 
1514131211109876543210
  es_fifo_err es_apt_failed es_rct_failed es_entropy_valid
BitsTypeResetNameDescription
0rw0x0es_entropy_validEnable interrupt when INTR_STATE.es_entropy_valid is set
1rw0x0es_rct_failedEnable interrupt when INTR_STATE.es_rct_failed is set
2rw0x0es_apt_failedEnable interrupt when INTR_STATE.es_apt_failed is set
3rw0x0es_fifo_errEnable interrupt when INTR_STATE.es_fifo_err is set


entropy_src.INTR_TEST @ + 0x8
Interrupt Test Register
Reset default = 0x0, mask 0xf
31302928272625242322212019181716
 
1514131211109876543210
  es_fifo_err es_apt_failed es_rct_failed es_entropy_valid
BitsTypeResetNameDescription
0wo0x0es_entropy_validWrite 1 to force INTR_STATE.es_entropy_valid to 1
1wo0x0es_rct_failedWrite 1 to force INTR_STATE.es_rct_failed to 1
2wo0x0es_apt_failedWrite 1 to force INTR_STATE.es_apt_failed to 1
3wo0x0es_fifo_errWrite 1 to force INTR_STATE.es_fifo_err to 1


entropy_src.ES_REGEN @ + 0xc
Register write enable for all control registers
Reset default = 0x1, mask 0x1
31302928272625242322212019181716
 
1514131211109876543210
  ES_REGEN
BitsTypeResetNameDescription
0rw1c0x1ES_REGENWhen true, the ES_CONF, ES_RCT_HEALTH, ES_APT_HEALTH and ES_SEED registers can be modified. When false, they become read-only. Defaults true, write one to clear. Note that this needs to be cleared after initial configuration at boot in order to lock in the listed register settings.


entropy_src.ES_REV @ + 0x10
ENTROPY_SRC revision register
Reset default = 0x10101, mask 0xffffff
31302928272625242322212019181716
  CHIP_TYPE
1514131211109876543210
HW_REVISION ABI_REVISION
BitsTypeResetNameDescription
7:0ro0x1ABI_REVISIONRead of this register shows the ABI of this block.
15:8ro0x1HW_REVISIONRead of this register shows the revision of this block.
23:16ro0x1CHIP_TYPERead of this register shows the type of chip using this block.


entropy_src.ES_CONF @ + 0x14
ENTROPY_SRC configuration register
Reset default = 0x0, mask 0x773
Register enable = ES_REGEN
31302928272625242322212019181716
 
1514131211109876543210
  RNG_BIT_SEL RNG_BIT_EN   APT_EN RCT_EN RNG_SRC_EN   ENABLE
BitsTypeResetNameDescription
1:0rw0x0ENABLEMaster enable for the ENTROPY_SRC entropy generation function. This two bit field determines what source will be used for health check processing: 0b00: Disabled 0b01: LFSR mode enabled 0b10: RNG mode enabled 0b11: Reserved
3:2Reserved
4rw0x0RNG_SRC_ENSetting this bit enables the RNG entropy source.
5rw0x0RCT_ENSetting this bit enables the health test called Repetition Count Test.
6rw0x0APT_ENSetting this bit enables the health test called Adaptive Proportion Test.
7Reserved
8rw0x0RNG_BIT_ENSetting this bit enables the single RNG bit mode, where only one bit is sampled.
10:9rw0x0RNG_BIT_SELWhen the above bit iset, this field selects which bit from the RNG bus will be processed when in single RNG bit mode. This two bit field selects the RNG bit stream: 0b00: RNG bit 0 0b01: RNG bit 1 0b10: RNG bit 2 0b11: RNG bit 3


entropy_src.ES_RCT_HEALTH @ + 0x18
ENTROPY_SRC RCT health test register
Reset default = 0xb, mask 0xffff
Register enable = ES_REGEN
31302928272625242322212019181716
 
1514131211109876543210
RCT_MAX
BitsTypeResetNameDescription
15:0rw0xbRCT_MAXThis is the cutoff value for failures of the RCT health test.


entropy_src.ES_APT_HEALTH @ + 0x1c
ENTROPY_SRC APT health test register
Reset default = 0x4000298, mask 0xffffffff
Register enable = ES_REGEN
31302928272625242322212019181716
APT_WIN
1514131211109876543210
APT_MAX
BitsTypeResetNameDescription
15:0rw0x298APT_MAXThis is the cutoff value for failures of the APT health test.
31:16rw0x400APT_WINThis is the window value for testing of the APT health test.


entropy_src.ES_ENTROPY @ + 0x20
ENTROPY_SRC entropy source
Reset default = 0x0, mask 0xffffffff
31302928272625242322212019181716
ES_ENTROPY...
1514131211109876543210
...ES_ENTROPY
BitsTypeResetNameDescription
31:0ro0x0ES_ENTROPYA read of this register provides entropy needed for an entropy source.


entropy_src.ES_FIFO_STATUS @ + 0x24
ENTROPY_SRC fifo depth status register
Reset default = 0x0, mask 0x8001f077
31302928272625242322212019181716
DIAG   ES_DEPTH...
1514131211109876543210
...ES_DEPTH   HWIF_DEPTH   DIG_SRC_DEPTH
BitsTypeResetNameDescription
2:0ro0x0DIG_SRC_DEPTHThis is the depth of the digital source FIFO.
3Reserved
6:4ro0x0HWIF_DEPTHThis is the depth of the hardware interface FIFO.
11:7Reserved
16:12ro0x0ES_DEPTHThis is the depth of the ES FIFO.
30:17Reserved
31ro0x0DIAGThis bit is for internal debug only.


entropy_src.ES_FDEPTHST @ + 0x28
ENTROPY_SRC FIFO depth status register
Reset default = 0x0, mask 0x7
31302928272625242322212019181716
 
1514131211109876543210
  ENTROPY_FIFO_DEPTH
BitsTypeResetNameDescription
2:0ro0x0ENTROPY_FIFO_DEPTHThis register will reflect the current depth of the software entropy delivery or TLUL FIFO.


entropy_src.ES_THRESH @ + 0x2c
ENTROPY_SRC threshold register
Reset default = 0x0, mask 0x7
31302928272625242322212019181716
 
1514131211109876543210
  FIFO_THRESHOLD
BitsTypeResetNameDescription
2:0rw0x0FIFO_THRESHOLDThe entropy FIFO depth will be compared against this register value when setting the es_entropy_valid interrupt signal.


entropy_src.ES_RATE @ + 0x30
ENTROPY_SRC entropy rate register
Reset default = 0x4, mask 0xffff
31302928272625242322212019181716
 
1514131211109876543210
ENTROPY_RATE
BitsTypeResetNameDescription
15:0rw0x4ENTROPY_RATEThis register determines the rate that entropy bits will be supplied. Its purpose to is simulate slow entropy sources. A value of 1 will deliver full rate entropy. A value of 2 will cut a full entropy source in half. A value of 8 will cut the rate by 1/8th. The precise equation for entropy delivery is one clock cycle of entropy is generated every 1/(ENTROPY_RATE) equal to one. A value of 0 disables all entropy generation.


entropy_src.ES_SEED @ + 0x34
ENTROPY_SRC seed register
Reset default = 0xb, mask 0xf
Register enable = ES_REGEN
31302928272625242322212019181716
 
1514131211109876543210
  LFSR_SEED
BitsTypeResetNameDescription
3:0rw0xbLFSR_SEEDSeed used to load into the LFSR for the initial state. This field will not update if the ES_REGEN bit 0 is cleared.