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

  • The initial revision only supports an entropy source in the form of an LFSR (linear feedback shift register). This is a pseudo-random type of entropy source, as opposed to a truly random 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 should not have to change for the case where a random source of entropy is provided in a future revision.
  • Interrupts are supported:
    • Entropy bits are available.
    • An internal error has occurred.
  • No SP 800-90B defined health checks are done by this revision (these functions are left for the firmware to implement).
  • 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 firmware to orchestrate the majority of the function, getting helper services from specific hardware blocks. 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 firmware.

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. For this revision, the entropy generation can be very fast, based on programming. Other sources could be much slower. The support logic in the block will support entropy sources of any rate.

Once the required number of entropy bits have been collected, the firmware has two options of notification: an interrupt, or polling. For this revision, the ENTROPY_RDY bit will always be set if the ES_THRESH register is configured to a low value, so a firmware scheme of just reading the status bit to confirm that entropy is available is a good strategy. For slower sources, an interrupt may be a better use of CPU cycles.

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 consumption. This revision is a straightforward implementation using an LFSR. In principal, 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 enabling and initialization. The main difference between these steps is that enabling is a global block enable. The initialization step can be done at anytime while the block is enabled and running. Before setting the ENABLE bit, 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.

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 starts pulling out bits, continuously generated entropy source bits may be dropped from usage. The process of filling and draining the FIFO is the same, independent of what speed the entropy generation rate is at.

Once the ENTROPY_RDY 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 32 entries in the FIFO. An RTL parameter can be set to make this range smaller and save on gate count.

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_entropy_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. Once the ENABLE bit is set, subsequent loads of the seed into the LFSR will occur only when the INIT_ENT_SRC bit is set, and the state of the FIFO is full. The intent for this is that the FIFO is in a safe state, and any attempted seed updates to the LFSR will be ignored.

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, the ES_CTRL register, or the ES_SEED by firmware.

The ES_SEED register can be updated at any time while the entropy 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 ENTROPY_RDY bit in the ES_STATUS register will signal to the firmware when entropy bits should read from the ES_ENTROPY register. While the firmware is reading the FIFO, additional entropy bits could be captured by the FIFO as long as the 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 FIFO. New entropy bits can enter the FIFO at the tail concurrently.

Since the entropy flow is continuous, these is no tracking state machine required for the design. Instead, 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 FIFO at any time.

An additional feature is the ES_RATE register. The purpose of this register is to simulate slower entropy generation sources. This will aid firmware design and debug when trying to handle all entropy source types and rates.

Interrupts

The ENTROPY_SRC module has two interrupts: es_entropy_valid and es_entropy_fifo_err.

The es_entropy_valid interrupt should be used when a entropy source has been implemented that is relatively slow. For this revision, the entropy source can be very fast (at full rate), and polling the ENTROPY_RDY status bit should be done.

The es_entropy_fifo_err interrupt will fire when the entropy 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.

Entropy FIFO Operational Sequence

The following waveform show an example of how the entropy source is collected into the entropy FIFO. In this example, the FIFO parameter is set 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.

Programmers Guide

Initialization

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

void entropy_src_init(unsigned int seed) {

  // set the seed value
  *ES_SEED_REG = seed;

  // set the configuration enable bit
  *ES_CONF_REG = 0x1;

  // 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 ES_STATUS bit 0 (ENTROPY_RDY)
  return *ES_ENTROPY_REG;

}

Update Seed

The following code snippet demonstrates initializing the ENTROPY_SRC block for updating the seed after initialization has been done.

void entropy_src_seed_update(unsigned int seed) {

  // set the seed value
  *ES_SEED_REG = seed;

  // set the control initialization bit
  *ES_CTRL_REG = 0x1;

  // reset the control initialization bit
  *ES_CTRL_REG = 0x0;

}

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 0x3
31302928272625242322212019181716
 
1514131211109876543210
  es_entropy_fifo_err es_entropy_valid
BitsTypeResetNameDescription
0rw1c0x0es_entropy_validAsserted when entropy source bits are available.
1rw1c0x0es_entropy_fifo_errAsserted when a FIFO error occurs.


entropy_src.INTR_ENABLE @ + 0x4
Interrupt Enable Register
Reset default = 0x0, mask 0x3
31302928272625242322212019181716
 
1514131211109876543210
  es_entropy_fifo_err es_entropy_valid
BitsTypeResetNameDescription
0rw0x0es_entropy_validEnable interrupt when INTR_STATE.es_entropy_valid is set
1rw0x0es_entropy_fifo_errEnable interrupt when INTR_STATE.es_entropy_fifo_err is set


entropy_src.INTR_TEST @ + 0x8
Interrupt Test Register
Reset default = 0x0, mask 0x3
31302928272625242322212019181716
 
1514131211109876543210
  es_entropy_fifo_err es_entropy_valid
BitsTypeResetNameDescription
0wo0x0es_entropy_validWrite 1 to force INTR_STATE.es_entropy_valid to 1
1wo0x0es_entropy_fifo_errWrite 1 to force INTR_STATE.es_entropy_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_CTRL, 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_CONF @ + 0x10
ENTROPY_SRC configuration register
Reset default = 0x0, mask 0x1
Register enable = ES_REGEN
31302928272625242322212019181716
 
1514131211109876543210
  ENABLE
BitsTypeResetNameDescription
0rw0x0ENABLEMaster enable for the ENTROPY_SRC entropy generation function.


entropy_src.ES_REV @ + 0x14
ENTROPY_SRC revision register
Reset default = 0x10201, mask 0xffffff
31302928272625242322212019181716
  CHIP_TYPE
1514131211109876543210
HW_REVISION ABI_REVISION
BitsTypeResetNameDescription
7:0ro0x1ABI_REVISIONRead of this register shows the ABI of this block.
15:8ro0x2HW_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_ENTROPY @ + 0x18
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_CTRL @ + 0x1c
ENTROPY_SRC control register
Reset default = 0x0, mask 0x1
Register enable = ES_REGEN
31302928272625242322212019181716
 
1514131211109876543210
  INIT_ENT_SRC
BitsTypeResetNameDescription
0rw0x0INIT_ENT_SRCSetting this bit will initialize the entropy source function.


entropy_src.ES_STATUS @ + 0x20
ENTROPY_SRC status register
Reset default = 0x0, mask 0x1
31302928272625242322212019181716
 
1514131211109876543210
  ENTROPY_RDY
BitsTypeResetNameDescription
0ro0x0ENTROPY_RDYThis is set when the entropy source FIFO has met or exceeded the ES_THRESH value. This status bit will automatically clear once the FIFO depth drops below the threshold value. This bit will not set unless the block is enabled.


entropy_src.ES_FDEPTHST @ + 0x24
ENTROPY_SRC FIFO depth status register
Reset default = 0x0, mask 0x7f
31302928272625242322212019181716
 
1514131211109876543210
  ENTROPY_FIFO_DEPTH
BitsTypeResetNameDescription
6:0ro0x0ENTROPY_FIFO_DEPTHThis register will reflect the current depth of the entropy FIFO.


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


entropy_src.ES_RATE @ + 0x2c
ENTROPY_SRC entropy rate register
Reset default = 0x1, mask 0xffff
31302928272625242322212019181716
 
1514131211109876543210
ENTROPY_RATE
BitsTypeResetNameDescription
15:0rw0x1ENTROPY_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 @ + 0x30
ENTROPY_SRC seed register
Reset default = 0x12345678, mask 0xffffffff
Register enable = ES_REGEN
31302928272625242322212019181716
LFSR_SEED...
1514131211109876543210
...LFSR_SEED
BitsTypeResetNameDescription
31:0rw0x12345678LFSR_SEEDSeed used to load into the LFSR for the initial state. This field will not update if the ES_REGEN bit 0 is cleared.