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().