| trngpsv Vitis Drivers API Documentation

- Overview
- APIs
- File List
- Examples

Macros | Enumerations | Functions
Overview

## Macros
#define | XTRNGPSV_BURST_SIZE 16U
| QCNT of 4 * 4 bytes (reg width)= 16 bytes. More...
#define | XTRNGPSV_NUM_INIT_REGS 12U
| No. More...
#define | XTRNGPSV_BYTES_PER_REG 4U
| Number of bytes register (i.e. More...
#define | XTRNGPSV_ENTROPY_SEED_LEN_BYTES 64U
| Entropy SEED length in terms of security strength. More...
#define | XTRNGPSV_SEC_STRENGTH_SHIFT 5U
| Shift value in terms of security strength. More...
#define | XTRNGPSV_MAX_QCNT_MASK 0x800U
| Mask value for maximum QCNT (i.e 4U << 9U) More...
#define | XTRNGPSV_WORD_ALIGN_MASK 0x03U
| Mask to check whether the address is word aligned. More...
#define | XTRNGPSV_RESEED_TIMEOUT 15000U
| Reseed timeout in micro-seconds. More...
#define | XTRNGPSV_GENERATE_TIMEOUT 8000U
| Generate timeout in micro-seconds. More...
#define | PRNGMODE_RESEED 0U
| PRNG in Reseed mode. More...
#define | PRNGMODE_GEN TRNG_CTRL_PRNGMODE_MASK
| PRNG in Generate mode. More...
#define | XTRNGPSV_MIN_SEEDLIFE 1U
| Minimum seed life. More...
#define | XTRNGPSV_MAX_SEEDLIFE 0x1000000000000U
| Maximum seed life 2^^48. More...
#define | XTRNGPSV_MIN_DFLENMUL 2U
| Minimum DF Length Multiplier.This assumes additional multiplier of 1 for nonce. More...
#define | XTRNGPSV_MAX_DFLENMUL 9U
| Maximum DF Length Multiplier. More...
#define | ALL_A_PATTERN_32 0xAAAAAAAAU
| Pattern of 10101010... More...
#define | ALL_5_PATTERN_32 0x55555555U
| Pattern of 01010101... More...
#define | RESET_DELAY 10U
| Delay used in Reset operations. More...
#define | XTRNGPSV_SEC_STRENGTH_BYTES 32U
| Security strength in bytes. More...
#define | XTRNGPSV_SEC_STRENGTH_LEN 8U
| Security strength in Words. More...
#define | XTRNGPSV_PERS_STR_LEN 12U
| Personalization string length in dwords. More...
#define | XTRNGPSV_PERS_STR_LEN_BYTES 48U
| Personalization string length in bytes. More...
#define | XTRNGPSV_SEED_LEN 12U
| Seed length in dwords. More...
#define | XTRNGPSV_SEED_LEN_BYTES 48U
| Seed length in bytes. More...
#define | XTRNGPSV_GEN_LEN_BYTES 32U
| No. More...
#define | RAND_BUF_LEN 4U
| No. More...
#define | MAX_PRE_DF_LEN_BYTES 160U
| With max DFLenMul of 9 (9+1)*128= 1280 bits. More...
#define | MAX_PRE_DF_LEN_WORDS 40U
| With max DFLenMul of 9 (9+1)*128= 1280 bits. More...
#define | DF_SEED 0U
| to indicate DF called for seed More...
#define | DF_RAND 1U
| to indicate DF called for random number More...
#define | DF_IP_IV_LEN 4U
| Input IV Length for DF. More...
#define | BYTES_PER_BLOCK 16U
| No. More...
#define | DF_PAD_DATA_LEN 8U
| Length of Padding data used for DF calculation. More...
#define | XTRNGPSV_SUCCESS (s32)XST_SUCCESS
| SUCCESS definition of TRNGPSV driver. More...
#define | XTRNGPSV_FAILURE (s32)XST_FAILURE
| FAILURE definition of TRNGPSV driver. More...
#define | XTRNGPSV_TRUE (u32)TRUE
| Boolean TRUE definition of TRNGPSV driver. More...
#define | XTRNGPSV_FALSE (u32)FALSE
| Boolean FALSE definition of TRNGPSV driver. More...
#define | XTRNGPSV_SWAP_ENDIAN Xil_EndianSwap32
| Macro to swap endianness of 32 bit data. More...
#define | DF_PAD_VAL 0x80U
| Value to be written to first byte of Padding data. More...
#define | DF_KEY_LEN 32U
| Length of key for DF. More...

## Enumerations
enum | XTrngpsv_ErrorCodes { XTRNGPSV_ERROR_INVALID_PARAM = 0x10, XTRNGPSV_ERROR_INVALID_STATE, XTRNGPSV_ERROR_UNNECESSARY_PARAM, XTRNGPSV_ERROR_GLITCH, XTRNGPSV_ERROR_NOT_UNINSTANTIATED = 0x20, XTRNGPSV_ERROR_INVALID_USRCFG_MODE, XTRNGPSV_ERROR_INVALID_USRCFG_SEEDLIFE, XTRNGPSV_ERROR_INVALID_USRCFG_PREDRES, XTRNGPSV_ERROR_NO_SEED_INSTANTIATE, XTRNGPSV_ERROR_INVALID_USRCFG_DFDIS, XTRNGPSV_ERROR_INVALID_USRCFG_DFLENMUL, XTRNGPSV_ERROR_USRCFG_CPY, XTRNGPSV_ERROR_INVALID_USRCFG_PERSPRES, XTRNGPSV_ERROR_INVALID_USRCFG_SEEDPRES, XTRNGPSV_ERROR_UNNECESSARY_PARAM_INSTANTIATE, XTRNGPSV_ERROR_NO_SEED = 0x30, XTRNGPSV_ERROR_SEED_INVALID_MODE, XTRNGPSV_ERROR_SAME_SEED, XTRNGPSV_ERROR_INVALID_RESEED_DFLENMUL, XTRNGPSV_ERROR_CERTF, XTRNGPSV_ERROR_CERTF_SW_A5_PATTERN, XTRNGPSV_ERROR_RESEED_TIMEOUT, XTRNGPSV_ERROR_CPY_RESEED, XTRNGPSV_ERROR_INSUFFICIENT_RANDBUF = 0x40, XTRNGPSV_ERROR_PREDRES_MISMATCH, XTRNGPSV_ERROR_RESEEDING_REQUIRED, XTRNGPSV_ERROR_RESEED_REQD_PREDRES, XTRNGPSV_ERROR_INVALID_GEN_PREDRES, XTRNGPSV_ERROR_CATASTROPHIC_DTF, XTRNGPSV_ERROR_CATASTROPHIC_DTF_SW, XTRNGPSV_ERROR_GENERATE_TIMEOUT, XTRNGPSV_ERROR_INVALID_RANDBUF_ADDR, XTRNGPSV_ERROR_DF_CPY = 0x50, XTRNGPSV_ERROR_DF_SETUP_KEY_FAILED, XTRNGPSV_ERROR_DF_MEMSET, XTRNGPSV_ERROR_DF_MEMMOVE, XTRNGPSV_ERROR_HEALTHTEST_INVALID_MODE = 0x60, XTRNGPSV_ERROR_KAT_MISMATCH, XTRNGPSV_ERROR_USRCFG_CPY_KAT }
enum | XTrngpsv_State { XTRNGPSV_UNINITIALIZED = 0, XTRNGPSV_HEALTHY, XTRNGPSV_ERROR, XTRNGPSV_CATASTROPHIC }
enum | XTrngpsv_Mode { XTRNGPSV_HRNG = 0, XTRNGPSV_DRNG, XTRNGPSV_PTRNG }

## Functions
s32 | XTrngpsv_Instantiate (XTrngpsv *InstancePtr, const XTrngpsv_UsrCfg *ConfigurValues)
| This function further initializes i.e. More...
s32 | XTrngpsv_Reseed (XTrngpsv *InstancePtr, const u8 *ExtSeedPtr, u32 DFLenMul)
| This function reseeds the TRNG in DRNG, HRNG modes. More...
s32 | XTrngpsv_Generate (XTrngpsv *InstancePtr, u8 *RandBufPtr, u32 RandBufSize, u8 PredResistanceEn)
| This the function which actually generates and provides random bits to the caller. More...
s32 | XTrngpsv_Uninstantiate (XTrngpsv *InstancePtr)
| This function is used to put the TRNG in reset state, and clear the instance data including configuration, status. More...
XTrngpsv_Config * | XTrngpsv_LookupConfig (u16 DeviceId)
| This function returns a reference to an XTrng_Config structure based on the DeviceId. More...
s32 | XTrngpsv_DF (XTrngpsv *InstancePtr, u8 *DFOutput, u32 DF_Flag, const u8 *PersStrPtr)
| This function implements the Derivative Function (per NIST SP80090A) by distilling the entropy available in a lot of bits at its input (DFInput) into a smaller number of bits on the output (DFOutput), thus bringing entropy per bit to 1. More...
s32 | XTrngpsv_RunKAT (XTrngpsv *InstancePtr)
| KAT can be run at startup and on demand. More...
s32 | XTrngpsv_RunHealthTest (XTrngpsv *InstancePtr)
| Health tests are entropy tests and hence should be run when the configured mode is of PTRNG or HRNG mode. More...

## Register definitions
#define | TRNG_STATUS 0x00000004U
| TRNG status offset. More...
#define | TRNG_STATUS_QCNT_MASK 0x00000e00U
| TRNG QCNT mask. More...
#define | TRNG_STATUS_CERTF_MASK 0x00000008U
| TRNG CERTF mask. More...
#define | TRNG_STATUS_DTF_MASK 0x00000002U
| TRNG DTF mask. More...
#define | TRNG_STATUS_DONE_MASK 0x00000001U
| TRNG status done mask. More...
#define | TRNG_CTRL 0x00000008U
| TRNG control offset. More...
#define | TRNG_CTRL_EUMODE_MASK 0x00000100U
| Entropy data collection mode mask. More...
#define | TRNG_CTRL_PRNGMODE_MASK 0x00000080U
| Pseudo random number mode mask. More...
#define | TRNG_CTRL_PRNGSTART_MASK 0x00000020U
| PRNG start mask. More...
#define | TRNG_CTRL_PRNGXS_MASK 0x00000008U
| PRNG seed source mask. More...
#define | TRNG_CTRL_TRSSEN_MASK 0x00000004U
| True random seed source enable mask. More...
#define | TRNG_CTRL_PRNGSRST_MASK 0x00000001U
| PRNG soft reset mask. More...
#define | TRNG_EXT_SEED_0 0x00000040U
| TRNG external seed 0 offset. More...
#define | TRNG_PER_STRNG_0 0x00000080U
| Below registers are not directly referenced in driver but are accessed accessed with offset from TRNG_EXT_SEED_0. More...
#define | TRNG_CORE_OUTPUT 0x000000C0U
| Below registers are not directly referenced in driver but are accessed accessed with offset from TRNG_PER_STRNG_0. More...
#define | TRNG_RESET 0x000000D0U
| TRNG reset offset. More...
#define | TRNG_RESET_VAL_MASK 0x00000001U
| TRNG default reset value. More...
#define | TRNG_OSC_EN 0x000000D4U
| TRNG oscillator enable offset. More...
#define | TRNG_OSC_EN_VAL_MASK 0x00000001U
| TRNG default oscillator enable value. More...

## Constant definitions for parameters used for Health and KAT tests
#define | HEALTH_TEST_SEEDLIFE 10U
| Constant definitions for Health and KAT tests. More...
#define | HEALTH_TEST_DFLENMUL 7U
#define | KAT_SEEDLIFE 5U
#define | KAT_DFLENMUL 2U

## Macro Definition Documentation

#define ALL_5_PATTERN_32 0x55555555U

Pattern of 01010101...

#define ALL_A_PATTERN_32 0xAAAAAAAAU

Pattern of 10101010...

#define BYTES_PER_BLOCK 16U

No.

of bytes per block, equivalent to 128 bits

Referenced by XTrngpsv_Generate(), and XTrngpsv_RunKAT().

#define DF_IP_IV_LEN 4U

Input IV Length for DF.

#define DF_KEY_LEN 32U

Length of key for DF.

Referenced by XTrngpsv_DF().

#define DF_PAD_DATA_LEN 8U

Length of Padding data used for DF calculation.

#define DF_PAD_VAL 0x80U

Value to be written to first byte of Padding data.

Referenced by XTrngpsv_DF().

#define DF_RAND 1U

to indicate DF called for random number

Referenced by XTrngpsv_Generate().

#define DF_SEED 0U

to indicate DF called for seed

Referenced by XTrngpsv_DF().

#define HEALTH_TEST_SEEDLIFE 10U

Constant definitions for Health and KAT tests.

Referenced by XTrngpsv_RunHealthTest().

#define MAX_PRE_DF_LEN_BYTES 160U

With max DFLenMul of 9 (9+1)*128= 1280 bits.

#define MAX_PRE_DF_LEN_WORDS 40U

With max DFLenMul of 9 (9+1)*128= 1280 bits.

#define PRNGMODE_GEN TRNG_CTRL_PRNGMODE_MASK

PRNG in Generate mode.

Referenced by XTrngpsv_Generate().

#define PRNGMODE_RESEED 0U

PRNG in Reseed mode.

#define RAND_BUF_LEN 4U

No.

of 32 bit words

#define RESET_DELAY 10U

Delay used in Reset operations.

#define TRNG_CORE_OUTPUT 0x000000C0U

Below registers are not directly referenced in driver but are accessed accessed with offset from TRNG_PER_STRNG_0.

Register: TRNG_PER_STRNG_1 0x00000084U Register: TRNG_PER_STRNG_2 0x00000088U Register: TRNG_PER_STRNG_3 0x0000008CU Register: TRNG_PER_STRNG_4 0x00000090U Register: TRNG_PER_STRNG_5 0x00000094U Register: TRNG_PER_STRNG_6 0x00000098U Register: TRNG_PER_STRNG_7 0x0000009CU Register: TRNG_PER_STRNG_8 0x000000A0U Register: TRNG_PER_STRNG_9 0x000000A4U Register: TRNG_PER_STRNG_10 0x000000A8U Register: TRNG_PER_STRNG_11 0x000000ACUTRNG core output offset

#define TRNG_CTRL 0x00000008U

TRNG control offset.

Referenced by XTrngpsv_Generate().

#define TRNG_CTRL_EUMODE_MASK 0x00000100U

Entropy data collection mode mask.

Referenced by XTrngpsv_Generate().

#define TRNG_CTRL_PRNGMODE_MASK 0x00000080U

Pseudo random number mode mask.

#define TRNG_CTRL_PRNGSRST_MASK 0x00000001U

PRNG soft reset mask.

#define TRNG_CTRL_PRNGSTART_MASK 0x00000020U

PRNG start mask.

#define TRNG_CTRL_PRNGXS_MASK 0x00000008U

PRNG seed source mask.

Referenced by XTrngpsv_Generate().

#define TRNG_CTRL_TRSSEN_MASK 0x00000004U

True random seed source enable mask.

Referenced by XTrngpsv_Generate().

#define TRNG_EXT_SEED_0 0x00000040U

TRNG external seed 0 offset.

Referenced by XTrngpsv_Uninstantiate().

#define TRNG_OSC_EN 0x000000D4U

TRNG oscillator enable offset.

Referenced by XTrngpsv_Generate().

#define TRNG_OSC_EN_VAL_MASK 0x00000001U

TRNG default oscillator enable value.

Referenced by XTrngpsv_Generate().

#define TRNG_PER_STRNG_0 0x00000080U

Below registers are not directly referenced in driver but are accessed accessed with offset from TRNG_EXT_SEED_0.

Register: TRNG_EXT_SEED_1 0x00000044U Register: TRNG_EXT_SEED_2 0x00000048U Register: TRNG_EXT_SEED_3 0x0000004CU Register: TRNG_EXT_SEED_4 0x00000050U Register: TRNG_EXT_SEED_5 0x00000054U Register: TRNG_EXT_SEED_6 0x00000058U Register: TRNG_EXT_SEED_7 0x0000005CU Register: TRNG_EXT_SEED_8 0x00000060U Register: TRNG_EXT_SEED_9 0x00000064U Register: TRNG_EXT_SEED_10 0x00000068U Register: TRNG_EXT_SEED_11 0x0000006CUTRNG personalization string 0 offset

Referenced by XTrngpsv_Uninstantiate().

#define TRNG_RESET 0x000000D0U

TRNG reset offset.

#define TRNG_RESET_VAL_MASK 0x00000001U

TRNG default reset value.

#define TRNG_STATUS 0x00000004U

TRNG status offset.

#define TRNG_STATUS_CERTF_MASK 0x00000008U

TRNG CERTF mask.

#define TRNG_STATUS_DONE_MASK 0x00000001U

TRNG status done mask.

#define TRNG_STATUS_DTF_MASK 0x00000002U

TRNG DTF mask.

#define TRNG_STATUS_QCNT_MASK 0x00000e00U

TRNG QCNT mask.

#define XTRNGPSV_BURST_SIZE 16U

QCNT of 4 * 4 bytes (reg width)= 16 bytes.

#define XTRNGPSV_BYTES_PER_REG 4U

Number of bytes register (i.e.

32/8)

#define XTRNGPSV_ENTROPY_SEED_LEN_BYTES 64U

Entropy SEED length in terms of security strength.

#define XTRNGPSV_FAILURE (s32)XST_FAILURE

FAILURE definition of TRNGPSV driver.

Referenced by XTrngpsv_DF(), XTrngpsv_Generate(), XTrngpsv_Instantiate(), XTrngpsv_Reseed(), XTrngpsv_RunHealthTest(), XTrngpsv_RunKAT(), and XTrngpsv_Uninstantiate().

#define XTRNGPSV_FALSE (u32)FALSE

Boolean FALSE definition of TRNGPSV driver.

Referenced by XTrngpsv_Generate(), XTrngpsv_Instantiate(), XTrngpsv_Reseed(), XTrngpsv_RunHealthTest(), and XTrngpsv_RunKAT().

#define XTRNGPSV_GEN_LEN_BYTES 32U

No.

of bytes per Generate request

Referenced by XTrngpsv_DF(), and XTrngpsv_RunKAT().

#define XTRNGPSV_GENERATE_TIMEOUT 8000U

Generate timeout in micro-seconds.

#define XTRNGPSV_MAX_DFLENMUL 9U

Maximum DF Length Multiplier.

Referenced by XTrngpsv_Instantiate(), and XTrngpsv_Reseed().

#define XTRNGPSV_MAX_QCNT_MASK 0x800U

Mask value for maximum QCNT (i.e 4U << 9U)

#define XTRNGPSV_MAX_SEEDLIFE 0x1000000000000U

Maximum seed life 2^^48.

Referenced by XTrngpsv_Instantiate().

#define XTRNGPSV_MIN_DFLENMUL 2U

Minimum DF Length Multiplier.This assumes additional multiplier of 1 for nonce.

Referenced by XTrngpsv_Instantiate().

#define XTRNGPSV_MIN_SEEDLIFE 1U

Minimum seed life.

Referenced by XTrngpsv_Instantiate().

#define XTRNGPSV_NUM_INIT_REGS 12U

No.

of SEED and PERS STRING registers each

#define XTRNGPSV_PERS_STR_LEN 12U

Personalization string length in dwords.

Referenced by XTrngpsv_Uninstantiate().

#define XTRNGPSV_PERS_STR_LEN_BYTES 48U

Personalization string length in bytes.

Referenced by XTrngpsv_DF(), and XTrngpsv_RunKAT().

#define XTRNGPSV_RESEED_TIMEOUT 15000U

Reseed timeout in micro-seconds.

#define XTRNGPSV_SEC_STRENGTH_BYTES 32U

Security strength in bytes.

Referenced by XTrngpsv_DF(), and XTrngpsv_Generate().

#define XTRNGPSV_SEC_STRENGTH_LEN 8U

Security strength in Words.

#define XTRNGPSV_SEC_STRENGTH_SHIFT 5U

Shift value in terms of security strength.

#define XTRNGPSV_SEED_LEN 12U

Seed length in dwords.

Referenced by XTrngpsv_Uninstantiate().

#define XTRNGPSV_SEED_LEN_BYTES 48U

Seed length in bytes.

Referenced by XTrngpsv_DF(), XTrngpsv_Reseed(), and XTrngpsv_RunKAT().

#define XTRNGPSV_SUCCESS (s32)XST_SUCCESS

SUCCESS definition of TRNGPSV driver.

Referenced by XTrngpsv_DF(), XTrngpsv_Generate(), XTrngpsv_Instantiate(), XTrngpsv_Reseed(), XTrngpsv_RunHealthTest(), XTrngpsv_RunKAT(), and XTrngpsv_Uninstantiate().

#define XTRNGPSV_SWAP_ENDIAN Xil_EndianSwap32

Macro to swap endianness of 32 bit data.

Referenced by XTrngpsv_DF().

#define XTRNGPSV_TRUE (u32)TRUE

Boolean TRUE definition of TRNGPSV driver.

Referenced by XTrngpsv_Generate(), XTrngpsv_Instantiate(), XTrngpsv_Reseed(), and XTrngpsv_RunKAT().

#define XTRNGPSV_WORD_ALIGN_MASK 0x03U

Mask to check whether the address is word aligned.

Referenced by XTrngpsv_Generate().

## Enumeration Type Documentation

enum XTrngpsv_ErrorCodes

Enumerator
XTRNGPSV_ERROR_INVALID_PARAM | 0x10
XTRNGPSV_ERROR_INVALID_STATE | 0x11
XTRNGPSV_ERROR_UNNECESSARY_PARAM | 0x12
XTRNGPSV_ERROR_GLITCH | 0x13
XTRNGPSV_ERROR_NOT_UNINSTANTIATED | 0x20
XTRNGPSV_ERROR_INVALID_USRCFG_MODE | 0x21
XTRNGPSV_ERROR_INVALID_USRCFG_SEEDLIFE | 0x22
XTRNGPSV_ERROR_INVALID_USRCFG_PREDRES | 0x23
XTRNGPSV_ERROR_NO_SEED_INSTANTIATE | 0x24
XTRNGPSV_ERROR_INVALID_USRCFG_DFDIS | 0x25
XTRNGPSV_ERROR_INVALID_USRCFG_DFLENMUL | 0x26
XTRNGPSV_ERROR_USRCFG_CPY | 0x27
XTRNGPSV_ERROR_INVALID_USRCFG_PERSPRES | 0x28
XTRNGPSV_ERROR_INVALID_USRCFG_SEEDPRES | 0x29
XTRNGPSV_ERROR_UNNECESSARY_PARAM_INSTANTIATE | 0x2A
XTRNGPSV_ERROR_NO_SEED | 0x30
XTRNGPSV_ERROR_SEED_INVALID_MODE | 0x31
XTRNGPSV_ERROR_SAME_SEED | 0x32
XTRNGPSV_ERROR_INVALID_RESEED_DFLENMUL | 0x33
XTRNGPSV_ERROR_CERTF | 0x34
XTRNGPSV_ERROR_CERTF_SW_A5_PATTERN | 0x35
XTRNGPSV_ERROR_RESEED_TIMEOUT | 0x36
XTRNGPSV_ERROR_CPY_RESEED | 0x37
XTRNGPSV_ERROR_INSUFFICIENT_RANDBUF | 0x40
XTRNGPSV_ERROR_PREDRES_MISMATCH | 0x41
XTRNGPSV_ERROR_RESEEDING_REQUIRED | 0x42
XTRNGPSV_ERROR_RESEED_REQD_PREDRES | 0x43
XTRNGPSV_ERROR_INVALID_GEN_PREDRES | 0x44
XTRNGPSV_ERROR_CATASTROPHIC_DTF | 0x45
XTRNGPSV_ERROR_CATASTROPHIC_DTF_SW | 0x46
XTRNGPSV_ERROR_GENERATE_TIMEOUT | 0x47
XTRNGPSV_ERROR_INVALID_RANDBUF_ADDR | 0x48
XTRNGPSV_ERROR_DF_CPY | 0x50
XTRNGPSV_ERROR_DF_SETUP_KEY_FAILED | 0x51
XTRNGPSV_ERROR_DF_MEMSET | 0x52
XTRNGPSV_ERROR_DF_MEMMOVE | 0x53
XTRNGPSV_ERROR_HEALTHTEST_INVALID_MODE | 0x60
XTRNGPSV_ERROR_KAT_MISMATCH | 0x61
XTRNGPSV_ERROR_USRCFG_CPY_KAT | 0x62

enum XTrngpsv_Mode

Enumerator
XTRNGPSV_HRNG | 0 - Hybrid RNG
XTRNGPSV_DRNG | 1 - Deterministic RNG
XTRNGPSV_PTRNG | 2 - Physical True RNG

enum XTrngpsv_State

Enumerator
XTRNGPSV_UNINITIALIZED | 0 - Driver is not in Initialized state
XTRNGPSV_HEALTHY | 1 - Driver is not in Healthy state
XTRNGPSV_ERROR | 3 - Driver encountered error condition
XTRNGPSV_CATASTROPHIC | 3 - Driver encountered catastrophic error

## Function Documentation

s32 XTrngpsv_DF | ( | XTrngpsv * | InstancePtr,
|  | u8 * | DFOutput,
|  | u32 | DF_Flag,
|  | const u8 * | PersStrPtr
| ) |  |

This function implements the Derivative Function (per NIST SP80090A) by distilling the entropy available in a lot of bits at its input (DFInput) into a smaller number of bits on the output (DFOutput), thus bringing entropy per bit to 1.

Actual length of input to DF need to be provided to the core (block cipher)algorithm for DF, based on if personalization string is present or not and based on actual length of input entropy, the buffer needs to adjusted by pushing all the unused bytes to the end. The Block Cipher algorithm invoked here is as per sections 10.3.2 and 10.3.3 of the NIST.SP.800-90Ar1 document.

Parameters

  InstancePtr | is a pointer to the XTrngpsv instance to be worked on.
  DFOutput | points to the buffer to which output of DF operation is stored.
  DF_Flag | is the flag used to indicate if this function is used to generate seed or random number (used in the PTRNG mode)
  PersStrPtr | is the pointer to Personalization string. If no personalization string is present, it should be NULL.

Returns
  - XTRNGPSV_SUCCESS if successful.
  - XTRNGPSV_ERROR_DF_CPY if MemCpy failure
  - XTRNGPSV_ERROR_GLITCH if error caused due to glitch conditions.

References DF_KEY_LEN, DF_PAD_VAL, DF_SEED, XTRNGPSV_ERROR_DF_CPY, XTRNGPSV_ERROR_DF_MEMMOVE, XTRNGPSV_ERROR_DF_MEMSET, XTRNGPSV_ERROR_DF_SETUP_KEY_FAILED, XTRNGPSV_ERROR_GLITCH, XTRNGPSV_FAILURE, XTRNGPSV_GEN_LEN_BYTES, XTRNGPSV_PERS_STR_LEN_BYTES, XTRNGPSV_SEC_STRENGTH_BYTES, XTRNGPSV_SEED_LEN_BYTES, XTRNGPSV_SUCCESS, and XTRNGPSV_SWAP_ENDIAN.

Referenced by XTrngpsv_Generate().

s32 XTrngpsv_Generate | ( | XTrngpsv * | InstancePtr,
|  | u8 * | RandBufPtr,
|  | u32 | RandBufSize,
|  | u8 | PredResistanceEn
| ) |  |

This the function which actually generates and provides random bits to the caller.

Number of bits generated per call is 256 bits. If user needs more bits of random data, this API can be called multiple times accordingly.

Parameters

  InstancePtr | is a pointer to the XTrngpsv instance to be worked on.
  RandBufPtr | points to memory address where generated random data will be stored and the memory address should be word aligned.
  RandBufSize | is size of the buffer to which RandBufPtr points to and it should be always greater than or equal to XTRNGPSV_SEC_STRENGTH_BYTES.
  PredResistanceEn | is the flag that controls Generate level Prediction Resistance. When enabled, it mandates fresh seed for every Generate operation.

Returns
  - XTRNGPSV_SUCCESS if Random number generation was successful.
  - XTRNGPSV_ERROR_INVALID_PARAM if invalid parameter(s) passed to this function.
  - XTRNGPSV_ERROR_INVALID_STATE if driver is not Healthy state before invoking this.
  - XTRNGPSV_ERROR_INSUFFICIENT_RANDBUF if length of Buffer passed is insufficient.
  - XTRNGPSV_ERROR_INVALID_GEN_PREDRES if Prediction Resistance set for PTRNG mode.
  - XTRNGPSV_ERROR_PREDRES_MISMATCH if Pred Resistance not set during Instantiate but set now.
  - XTRNGPSV_ERROR_RESEEDING_REQUIRED if SeedLife elapsed.
  - XTRNGPSV_ERROR_RESEED_REQD_PREDRES if seed is consumed and has Pred Resistance.
  - XTRNGPSV_ERROR_GLITCH if error caused due to glitch conditions.
  - Other error codes from the called functions as defined in XTrngpsv_ErrorCodes.

If during Instantiation Prediction Resistance is enabled and not during Generate, its an error

References BYTES_PER_BLOCK, DF_RAND, PRNGMODE_GEN, TRNG_CTRL, TRNG_CTRL_EUMODE_MASK, TRNG_CTRL_PRNGXS_MASK, TRNG_CTRL_TRSSEN_MASK, TRNG_OSC_EN, TRNG_OSC_EN_VAL_MASK, XTRNGPSV_CATASTROPHIC, XTrngpsv_DF(), XTRNGPSV_DRNG, XTRNGPSV_ERROR, XTRNGPSV_ERROR_GLITCH, XTRNGPSV_ERROR_INSUFFICIENT_RANDBUF, XTRNGPSV_ERROR_INVALID_GEN_PREDRES, XTRNGPSV_ERROR_INVALID_PARAM, XTRNGPSV_ERROR_INVALID_RANDBUF_ADDR, XTRNGPSV_ERROR_INVALID_STATE, XTRNGPSV_ERROR_PREDRES_MISMATCH, XTRNGPSV_ERROR_RESEED_REQD_PREDRES, XTRNGPSV_ERROR_RESEEDING_REQUIRED, XTRNGPSV_FAILURE, XTRNGPSV_FALSE, XTRNGPSV_HEALTHY, XTRNGPSV_HRNG, XTRNGPSV_PTRNG, XTRNGPSV_SEC_STRENGTH_BYTES, XTRNGPSV_SUCCESS, XTRNGPSV_TRUE, and XTRNGPSV_WORD_ALIGN_MASK.

Referenced by XTrngpsv_RunKAT().

s32 XTrngpsv_Instantiate | ( | XTrngpsv * | InstancePtr,
|  | const XTrngpsv_UsrCfg * | ConfigurValues
| ) |  |

This function further initializes i.e.

instantiates the TRNGPSV instance/driver with user configuration, resets the TRNG core and reseeds with initial seed and personalization string provided during Instantiation. Switching to a new state of attributes or changing any attributes (configured during Instantiation) requires UnInstantiation of the current instance and instantiation of a new instance. After successful Instantiation, State of the driver is changed to Healthy.

Parameters

  InstancePtr | is a pointer to the XTrngpsv instance to be worked on.
  ConfigurValues | points to the user configuration structure associated with the TRNGPSV driver.

Returns
  - XTRNGPSV_SUCCESS if Instantiation was successful.
  - XTRNGPSV_ERROR_INVALID_PARAM if invalid parameter(s) passed to this function.
  - XTRNGPSV_ERROR_NOT_UNINSTANTIATED if the driver is not uninstantiated earlier.
  - XTRNGPSV_ERROR_INVALID_USRCFG_MODE if invalid Mode parameter.
  - XTRNGPSV_ERROR_INVALID_USRCFG_SEEDLIFE if SeedLife parameter is invalid
  - XTRNGPSV_ERROR_INVALID_USRCFG_PREDRES if invalid Prediction Resistance parameter.
  - XTRNGPSV_ERROR_INVALID_USRCFG_PERSPRES if PersStrPresent parameter is invalid.
  - XTRNGPSV_ERROR_INVALID_USRCFG_SEEDPRES if InitSeedPresent parameter is invalid.
  - XTRNGPSV_ERROR_NO_SEED_INSTANTIATE if no seed passed for DRNG mode.
  - XTRNGPSV_ERROR_UNNECESSARY_PARAM_INSTANTIATE if seed passed for HRNG mode or if unnecessary seed related parameter passed for PTRNG mode.
  - XTRNGPSV_ERROR_INVALID_USRCFG_DFDIS if DFDisable parameter is invalid.
  - XTRNGPSV_ERROR_INVALID_USRCFG_DFLENMUL if DFLenMul parameter is invalid.
  - XTRNGPSV_ERROR_USRCFG_CPY if error during copy of ConfigurValues structure.
  - Other error codes from the called functions as defined in XTrngpsv_ErrorCodes.

References XTRNGPSV_DRNG, XTRNGPSV_ERROR, XTRNGPSV_ERROR_INVALID_PARAM, XTRNGPSV_ERROR_INVALID_USRCFG_DFDIS, XTRNGPSV_ERROR_INVALID_USRCFG_DFLENMUL, XTRNGPSV_ERROR_INVALID_USRCFG_MODE, XTRNGPSV_ERROR_INVALID_USRCFG_PERSPRES, XTRNGPSV_ERROR_INVALID_USRCFG_PREDRES, XTRNGPSV_ERROR_INVALID_USRCFG_SEEDLIFE, XTRNGPSV_ERROR_INVALID_USRCFG_SEEDPRES, XTRNGPSV_ERROR_NO_SEED_INSTANTIATE, XTRNGPSV_ERROR_NOT_UNINSTANTIATED, XTRNGPSV_ERROR_UNNECESSARY_PARAM_INSTANTIATE, XTRNGPSV_ERROR_USRCFG_CPY, XTRNGPSV_FAILURE, XTRNGPSV_FALSE, XTRNGPSV_HEALTHY, XTRNGPSV_HRNG, XTRNGPSV_MAX_DFLENMUL, XTRNGPSV_MAX_SEEDLIFE, XTRNGPSV_MIN_DFLENMUL, XTRNGPSV_MIN_SEEDLIFE, XTRNGPSV_PTRNG, XTRNGPSV_SUCCESS, XTRNGPSV_TRUE, and XTRNGPSV_UNINITIALIZED.

Referenced by XTrngpsv_RunHealthTest(), and XTrngpsv_RunKAT().

XTrngpsv_Config * XTrngpsv_LookupConfig | ( | u16 | DeviceId | ) |

This function returns a reference to an XTrng_Config structure based on the DeviceId.

The return value will refer to an entry in the device configuration table defined in the xtrng_g.c file.

Parameters

  DeviceId | is the unique device ID of the device being lookedup.

Returns
  XTrng_LookupConfig returns a reference to a config record in the configuration table (in xtrngpsv.c) corresponding to DeviceId, or NULL if no match is found.

s32 XTrngpsv_Reseed | ( | XTrngpsv * | InstancePtr,
|  | const u8 * | ExtSeedPtr,
|  | u32 | DFLenMul
| ) |  |

This function reseeds the TRNG in DRNG, HRNG modes.

This function will be called by random number consuming application. This is just a wrapper function calling XTrng_ReseedInternal() which passes NULL as personalization string.

Parameters

  InstancePtr | is a pointer to the XTrngpsv instance to be worked on.
  ExtSeedPtr | points to the byte array containing external seed. This shall be NULL for HRNG case.
  DFLenMul | is DF Length multiplier used to determine number of bits on the input of the DF construct which is (DFLenMul + 1)*128 bits. This indicates the size of the seed pointed by ExtSeedPtr. This shall be 0 for Non-DF case.

Returns
  - XTRNGPSV_SUCCESS if Reseed was successful.
  - XTRNGPSV_ERROR_INVALID_PARAM if invalid parameter(s) passed to this function.
  - XTRNGPSV_ERROR_INVALID_STATE if driver is not Healthy state before invoking this.
  - XTRNGPSV_ERROR_SEED_INVALID_MODE if this is called in PTRNG mode.
  - XTRNGPSV_ERROR_NO_SEED if no seed passed for DRNG mode.
  - XTRNGPSV_ERROR_UNNECESSARY_PARAM if seed passed for non-DRNG mode.
  - XTRNGPSV_ERROR_INVALID_RESEED_DFLENMUL if invalid DFLenMul parameter passed.
  - XTRNGPSV_ERROR_SAME_SEED if same seed passed for both Instantiation and Reseed.
  - Other error codes from the called functions as defined in XTrngpsv_ErrorCodes.

References XTRNGPSV_DRNG, XTRNGPSV_ERROR, XTRNGPSV_ERROR_INVALID_PARAM, XTRNGPSV_ERROR_INVALID_RESEED_DFLENMUL, XTRNGPSV_ERROR_INVALID_STATE, XTRNGPSV_ERROR_NO_SEED, XTRNGPSV_ERROR_SAME_SEED, XTRNGPSV_ERROR_SEED_INVALID_MODE, XTRNGPSV_ERROR_UNNECESSARY_PARAM, XTRNGPSV_FAILURE, XTRNGPSV_FALSE, XTRNGPSV_HEALTHY, XTRNGPSV_HRNG, XTRNGPSV_MAX_DFLENMUL, XTRNGPSV_SEED_LEN_BYTES, XTRNGPSV_SUCCESS, and XTRNGPSV_TRUE.

Referenced by XTrngpsv_RunKAT().

s32 XTrngpsv_RunHealthTest | ( | XTrngpsv * | InstancePtr | ) |

Health tests are entropy tests and hence should be run when the configured mode is of PTRNG or HRNG mode.

1024 bits of entropy data to be generated and the CTF flag to be monitored. TRNG configured in HRNG + DF serves this purpose ((7+1)*128 = 1024 bits). Since this flag is monitored for every reseed, no need to monitor CTF explicitly in this test. This API is to be called at startup, after instantiation (and reseeding). Even for PTRNG mode, for this test, mode to be configured as HRNG (as there is no reseed operation involved in PTRNG mode).

Parameters

  InstancePtr | is a pointer to the XTrngpsv instance to be worked on.

Returns
  - XTRNGPSV_SUCCESS if Health tests are successfully run.
  - XTRNGPSV_ERROR_INVALID_PARAM if invalid parameter passed to this function (OR) other error codes from the called functions as defined in XTrngpsv_ErrorCodes.

References HEALTH_TEST_SEEDLIFE, XTRNGPSV_ERROR, XTRNGPSV_ERROR_INVALID_PARAM, XTRNGPSV_FAILURE, XTRNGPSV_FALSE, XTRNGPSV_HRNG, XTrngpsv_Instantiate(), XTRNGPSV_SUCCESS, and XTrngpsv_Uninstantiate().

s32 XTrngpsv_RunKAT | ( | XTrngpsv * | InstancePtr | ) |

KAT can be run at startup and on demand.

256 bits are generated and ignored. This test can be run when the TRNG is configured in DRNG and HRNG modes. For HRNG mode too, tests should be run in DRNG mode. If KAT fails, driver has to be put in Error state.

Parameters

  InstancePtr | is a pointer to the XTrngpsv instance to be worked on.

Returns
  - XTRNGPSV_SUCCESS if KAT is successful.
  - XTRNGPSV_ERROR_INVALID_PARAM if invalid parameter passed to this function.
  - XTRNGPSV_ERROR_USRCFG_CPY_KAT if copy of seed/personalization string failed.
  - XTRNGPSV_ERROR_KAT_MISMATCH if KAT result doesn't match with expected output (OR) other error codes from the called functions as defined in XTrngpsv_ErrorCodes.

References BYTES_PER_BLOCK, XTRNGPSV_DRNG, XTRNGPSV_ERROR, XTRNGPSV_ERROR_INVALID_PARAM, XTRNGPSV_ERROR_KAT_MISMATCH, XTRNGPSV_ERROR_USRCFG_CPY_KAT, XTRNGPSV_FAILURE, XTRNGPSV_FALSE, XTRNGPSV_GEN_LEN_BYTES, XTrngpsv_Generate(), XTrngpsv_Instantiate(), XTRNGPSV_PERS_STR_LEN_BYTES, XTrngpsv_Reseed(), XTRNGPSV_SEED_LEN_BYTES, XTRNGPSV_SUCCESS, XTRNGPSV_TRUE, and XTrngpsv_Uninstantiate().

s32 XTrngpsv_Uninstantiate | ( | XTrngpsv * | InstancePtr | ) |

This function is used to put the TRNG in reset state, and clear the instance data including configuration, status.

Parameters

  InstancePtr | is a pointer to the XTrngpsv instance to be worked on.

Returns
  - XTRNGPSV_SUCCESS if Uninstantiation was successful.
  - XTRNGPSV_ERROR_INVALID_PARAM if invalid parameter(s) passed to this function.
  - XTRNGPSV_ERROR_INVALID_STATE if driver is not Healthy state before invoking this.
  - XTRNGPSV_ERROR_GLITCH if error caused due to glitch conditions.

References TRNG_EXT_SEED_0, TRNG_PER_STRNG_0, XTRNGPSV_ERROR, XTRNGPSV_ERROR_INVALID_PARAM, XTRNGPSV_ERROR_INVALID_STATE, XTRNGPSV_FAILURE, XTRNGPSV_PERS_STR_LEN, XTRNGPSV_SEED_LEN, XTRNGPSV_SUCCESS, and XTRNGPSV_UNINITIALIZED.

Referenced by XTrngpsv_RunHealthTest(), and XTrngpsv_RunKAT().