| trngpsv Vitis Drivers API Documentation

- Overview
- APIs
- File List
- Examples

trngpsv Documentation

The Xilinx True Random Number Generator (TRNG) module in Versal - PMC TRNG consists of an entropy source, a deterministic random bit generator (DRBG) and health test logic, which tests the randomness of the generated data. The entropy source for the unit is an array of Ring Oscillators.

The Versal PMC TRNG is envisaged to operate in three basic modes: DRNG, PTRNG and HRNG modes. Each of these can be operated with or without Derivative Function (DF), resulting in a total of 6 different modes of operation.

NIST SP-800-90A practically requires the true random generators based on CTR_DRBG to include a derivation function (DF). This is expected to be implemented inside the Silicon (TRNG IP). However, the version of the IP used in Versal PMC doesn't have this implementation. Hence, a software implementation of the DF is done in this driver.

DRNG mode: Deterministic Random Number Generator mode. In this mode, the DRBG portion of the TRNG is used. User provides the (external) seed in this mode. PTRNG mode: Physical True Random Number Generator mode (aka Entropy mode). In this mode digitized Entropy source is output as random number. HRNG mode: Hybrid Random Number Generator mode. This is combination of above two modes in which the Entropy source is used to provide the seed, which is fed to the DRBG, which in turn generates the random number.

DRNG mode with DF: It may not be common usecase to use the DF with DRNG as the general expectation would be that the seed would have sufficient entropy. However, the below guideline from section 10.2.1 of NIST SP-800-90A implies that need for DF for DRNG mode too: "..the DRBG mechanism is specified to allow an implementation tradeoff with respect to the use of this derivation function. The use of the derivation function is optional if either an approved RBG or an entropy source provides full entropy output when entropy input is requested by the DRBG mechanism. Otherwise, the derivation function shall be used". Sufficient large entropy data from user is fed to DF to generate the seed which will be loaded into the external seed registers. From here, it is similar to regular DRNG mode.

PTRNG mode with DF: This mode is similar to PTRNG mode, however, the entropy data from the core output registers are accumulated and fed to the DF (instead of directly consuming it). The output of the DF would be final random data. In this mode, the output of DF is not seed but the random data.

HRNG mode with DF: This mode is the combination of the above two modes. The entropy data is fed to the DF to produce seed. This seed is loaded to the external seed registers which provide seed to the DRBG.

During operation, the driver will be one of the 4 stages as mentioned below. Transition from UNINITIALIZED to HEALTHY happens through the Instantiation process. The state of Uninitialized can be reached from any other state by Uninstantiate operation. ERROR state reached through SW error conditions or through indication of CTF (caused by Certification Randomness Test failure), whereas the CATASTROPHIC_ERROR state results from DTF (i.e. hardware failure).

More description of the driver operation for each function can be found in the xtrngpsv.c file.

This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.00  ssc  09/05/21 First release
    1.1   ssc  03/24/22 New error code XTRNGPSV_ERROR_GLITCH and doxygen fixes
    1.4   mmd  07/10/23 Included header file for crypto algorithm information
          ng   06/30/23 Added support for system device-tree flow