Skip to content

Commit

Permalink
[doc] Fix entropy_src links to renamed registers
Browse files Browse the repository at this point in the history
The two registers that were renamed are:

1. `CONF.ENABLE` -> `MODULE_ENABLE` (moved in 51fde5a)
2. `REGEN` -> `REGWEN` (renamed in ef348c9)

Additionally, the previous URLs linked to the HJSON file. With the new
documentation setup, these links now point to the register HTML file.

Signed-off-by: James Wainwright <[email protected]>
  • Loading branch information
jwnrt authored and HU90m committed Sep 26, 2023
1 parent dab0eb8 commit d3326c1
Show file tree
Hide file tree
Showing 2 changed files with 5 additions and 7 deletions.
6 changes: 2 additions & 4 deletions hw/ip/entropy_src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,8 @@
This document specifies ENTROPY_SRC hardware IP functionality.
This module conforms to the [Comportable guideline for peripheral functionality.](../../../doc/contributing/hw/comportability/README.md)


## Features


- This revision provides an interface to an external physical random noise generator (also referred to as a physical true random number generator.
The PTRNG external source is a physical true random noise source.
A noise source and its relation to an entropy source are defined by [SP 800-90B.](https://csrc.nist.gov/publications/detail/sp/800-90b/final)
Expand Down Expand Up @@ -56,7 +54,7 @@ The repetition count test fails if any sequence of bits continuously asserts the
The thresholds for these tests should be chosen to achieve a low false-positive rate (&alpha;) given a conservative estimate of the manufacturing tolerances of the PTRNG noise source.
The combined choice of threshold and window size then determine the false-negative rate (&beta;), or the probability of missing statistical defects at any particular magnitude.

When the IP is disabled by clearing the `ENABLE` bit in [`CONF`](data/entropy_src.hjson#conf), all heath checks are disabled and all counters internal to the health checks are reset.
When the IP is disabled by clearing the [`MODULE_ENABLE`](./doc/registers.md#MODULE_ENABLE) register, all health checks are disabled and all counters internal to the health checks are reset.

In order to compensate for the fact our tests (like *all* realistic statistical tests) have finite resolution for detecting defects, we conservatively use 2048 bits of PTRNG noise source to construct each 384 bit conditioned entropy sample.
When passed through the conditioning block, the resultant entropy stream will be full entropy unless the PTRNG noise source has encountered some statistical defect serious enough to reduce the raw min-entropy to a level below 0.375 bits of entropy per output bit.
Expand Down Expand Up @@ -88,7 +86,7 @@ Boot-time mode also has the feature that it bypasses the SHA conditioning functi
For maximal flexibility in normal operation, the conditioning function can also be implemented by firmware.
When this firmware conditioning feature is activated, data read directly out of the noise source can be reinjected into the entropy pipeline via a TL-UL register after it has been processed by firmware.
It should be noted that this firmware algorithm must be vetted by NIST to satisfy the requirements for a full-entropy source.
This feature can also be disabled for security purposes, either by locking the feature via the [`REGEN`](data/entropy_src.hjson#regen) register at boot, or by a write to one-time programmable (OTP) memory.
This feature can also be disabled for security purposes, either by locking the feature via the [`REGWEN`](./doc/registers.md#regwen) register at boot, or by a write to one-time programmable (OTP) memory.

## Compatibility
This IP block does not have any direct hardware compatibility requirements.
Expand Down
6 changes: 3 additions & 3 deletions hw/ip/entropy_src/doc/theory_of_operation.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ As already described, this IP block will collect bits of entropy for firmware or
This revision supports only an external interface for a PTRNG noise source implementation.

The first step is initialization and enabling.
The PTRNG noise source mode is selected when the `ENABLE` field will be set.
The PTRNG noise source mode is selected when the [`MODULE_ENABLE`](registers.md#module_enable) field is set.
After the block is enabled and initialized, entropy bits will be collected up indefinitely until disabled.


Expand Down Expand Up @@ -89,7 +89,7 @@ This drop point will save on conditioner power, and still preserve `esfinal` FIF

The above process will be repeated for as long as entropy bits are to be collected and processed.

At any time, the `ENABLE` field can be cleared to halt the entropy generation (and health check testing).
At any time, the [`MODULE_ENABLE`](registers.md#module_enable) field can be cleared to halt the entropy generation (and health check testing).
See the Programmers Guide section for more details on the ENTROPY_SRC block disable sequence.

## Block Diagram
Expand All @@ -105,7 +105,7 @@ After power-up, the ENTROPY_SRC block is disabled.
For simplicity of initialization, only a single register write is needed to start functional operation of the ENTROPY_SRC block.
This assumes that proper defaults are chosen for thresholds, sampling rate, and other registers.

For security reasons, a configuration and control register locking function is performed by the [`REGEN`](registers.md#regen) register.
For security reasons, a configuration and control register locking function is performed by the [`REGWEN`](registers.md#regwen) register.
Clearing the bit in this register will prevent future modification of the [`CONF`](registers.md#conf) register or other writeable registers by firmware.

### Entropy Processing
Expand Down

0 comments on commit d3326c1

Please sign in to comment.