ADuCM4x50 Device Drivers API Reference Manual  Release 4.0.0.0
RNG Driver

Modules

 RNG Driver Configuration
 

Macros

#define ADI_RNG_MEMORY_SIZE   (12u)
 

Typedefs

typedef void * ADI_RNG_HANDLE
 

Enumerations

enum  ADI_RNG_RESULT {
  ADI_RNG_SUCCESS = 0,
  ADI_RNG_UNKNOWN_ERROR,
  ADI_RNG_ALREADY_INITIALIZED,
  ADI_RNG_INVALID_PARAM,
  ADI_RNG_BAD_DEV_HANDLE,
  ADI_RNG_BAD_DEVICE_NUM,
  ADI_RNG_NOT_INITIALIZED,
  ADI_RNG_INVALID_STATE
}
 
enum  ADI_RNG_EVENT {
  ADI_RNG_EVENT_READY,
  ADI_RNG_EVENT_STUCK
}
 

Functions

ADI_RNG_RESULT adi_rng_Open (uint32_t const nDeviceNum, void *const pMemory, uint32_t const MemorySize, ADI_RNG_HANDLE *const phDevice)
 Opena a Random Number Generator Device. More...
 
ADI_RNG_RESULT adi_rng_Close (ADI_RNG_HANDLE hDevice)
 Uninitializes and deallocates the RNG device. More...
 
ADI_RNG_RESULT adi_rng_Enable (ADI_RNG_HANDLE const hDevice, bool const bFlag)
 Enables/Disables the RNG device. More...
 
ADI_RNG_RESULT adi_rng_EnableBuffering (ADI_RNG_HANDLE const hDevice, bool const bFlag)
 Enables/Disables Buffering for RNG. More...
 
ADI_RNG_RESULT adi_rng_SetSampleLen (ADI_RNG_HANDLE const hDevice, uint16_t const nLenPrescaler, uint16_t const nLenReload)
 Sets the reload and prescale value for the sample counter. The Sample Length will be nLenReload*2^nLenPrescaler. More...
 
ADI_RNG_RESULT adi_rng_GetRdyStatus (ADI_RNG_HANDLE const hDevice, bool *const pbFlag)
 Retrieves the current state of RNG data/CRC accumulator register. More...
 
ADI_RNG_RESULT adi_rng_GetStuckStatus (ADI_RNG_HANDLE const hDevice, bool *const pbFlag)
 Retrieve whether the RNG oscillator output is stuck at a constant value. More...
 
ADI_RNG_RESULT adi_rng_GetRngData (ADI_RNG_HANDLE const hDevice, uint32_t *const pRegData)
 Retrieve the current value of the RNG data register. More...
 
ADI_RNG_RESULT adi_rng_GetOscCount (ADI_RNG_HANDLE const hDevice, uint32_t *const pOscCount)
 Retrieve the current RNG Oscillator count. More...
 
ADI_RNG_RESULT adi_rng_GetOscDiff (ADI_RNG_HANDLE const hDevice, uint32_t const nIndex, uint8_t *const pOscDiff)
 Retrieve the current RNG Oscillator difference value for the given index. More...
 
ADI_RNG_RESULT adi_rng_RegisterCallback (ADI_RNG_HANDLE hDevice, ADI_CALLBACK cbFunc, void *pCBParam)
 RNG Application callback registration API. More...
 
ADI_RNG_RESULT adi_rng_GetSampleLen (ADI_RNG_HANDLE const hDevice, uint16_t *const pLenPrescaler, uint16_t *const pLenReload)
 Retrieve the current RNG sample length prescale and reload value configured in the device. More...
 

Detailed Description

Random Number Generator Driver

Macro Definition Documentation

◆ ADI_RNG_MEMORY_SIZE

#define ADI_RNG_MEMORY_SIZE   (12u)

The amount of application supplied memory required by the RNG driver

Definition at line 72 of file adi_rng.h.

Typedef Documentation

◆ ADI_RNG_HANDLE

typedef void* ADI_RNG_HANDLE

RNG Device handle typedef

Definition at line 76 of file adi_rng.h.

Enumeration Type Documentation

◆ ADI_RNG_RESULT

Random Number Generator API return codes

Enumerator
ADI_RNG_SUCCESS 

No Error, API suceeded

ADI_RNG_UNKNOWN_ERROR 

Unknown error detected

ADI_RNG_ALREADY_INITIALIZED 

RNG is already initialized

ADI_RNG_INVALID_PARAM 

Invalid function parameter

ADI_RNG_BAD_DEV_HANDLE 

Invalid device handle passed

ADI_RNG_BAD_DEVICE_NUM 

Invalid device instance

ADI_RNG_NOT_INITIALIZED 

RNG not yet initialized

ADI_RNG_INVALID_STATE 

Device is in an invalid state

Definition at line 48 of file adi_rng.h.

◆ ADI_RNG_EVENT

Random Number Generator callback events

Enumerator
ADI_RNG_EVENT_READY 

Random number ready event

ADI_RNG_EVENT_STUCK 

The ring oscillator got stuck event

Definition at line 64 of file adi_rng.h.

Function Documentation

◆ adi_rng_Open()

ADI_RNG_RESULT adi_rng_Open ( uint32_t const  nDeviceNum,
void *const  pMemory,
uint32_t const  MemorySize,
ADI_RNG_HANDLE *const  phDevice 
)

Opena a Random Number Generator Device.

Parameters
[in]nDeviceNumDevice number to be opened.
[in]pMemoryPointer to the memory to be used by the driver. Size of the memory should be at least ADI_RNG_MEMORY_SIZE bytes.
[in]MemorySizeSize of the memory passed in pMemory parameter.
[out]phDevicePointer to a location in the calling function memory space to which the device handle will be written upon successful driver initialization.
Returns
Status

Initialize and allocate a RNG device for other use. The core NVIC RNG interrupt is enabled. This API must preceed all other RNG API calls and the handle returned must be passed to all other RNG API calls.

Note
The contents of ppDevice will be set to NULL upon failure.

The RNG device driver will clear all pending interrupts and disable all RNG interrupts during RNG device initialization.
See also
adi_rng_Close().

Definition at line 107 of file adi_rng.c.

◆ adi_rng_Close()

ADI_RNG_RESULT adi_rng_Close ( ADI_RNG_HANDLE  hDevice)

Uninitializes and deallocates the RNG device.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
Returns
Status

Uninitialize and release an allocated RNG device for other use. The core NVIC RNG interrupt is disabled.

See also
adi_rng_Open().

Definition at line 183 of file adi_rng.c.

◆ adi_rng_Enable()

ADI_RNG_RESULT adi_rng_Enable ( ADI_RNG_HANDLE const  hDevice,
bool const  bFlag 
)

Enables/Disables the RNG device.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[in]bFlagFlag to specify whether to enable or disable RNG device.
Returns
Status
See also
adi_rng_Open().
adi_rng_RegisterCallback().

Definition at line 218 of file adi_rng.c.

◆ adi_rng_EnableBuffering()

ADI_RNG_RESULT adi_rng_EnableBuffering ( ADI_RNG_HANDLE const  hDevice,
bool const  bFlag 
)

Enables/Disables Buffering for RNG.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[in]bFlagFlag to specify whether to enable or disable buffering for RNG device. When buffering is enabled, adi_rng_GetRngData returns 32-bit values. When buffering is disabled the API returns 8-bit values.
Returns
Status
See also
adi_rng_Open().
adi_rng_RegisterCallback().
adi_rng_GetRngData().

Definition at line 261 of file adi_rng.c.

◆ adi_rng_SetSampleLen()

ADI_RNG_RESULT adi_rng_SetSampleLen ( ADI_RNG_HANDLE const  hDevice,
uint16_t const  nLenPrescaler,
uint16_t const  nLenReload 
)

Sets the reload and prescale value for the sample counter. The Sample Length will be nLenReload*2^nLenPrescaler.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[in]nLenPrescalerPrescaler value for the sample counter (0-10).
[in]nLenReloadReload value for the sample counter (0-4095)
Returns
Status
See also
adi_rng_Open().
adi_rng_RegisterCallback().

Definition at line 303 of file adi_rng.c.

◆ adi_rng_GetRdyStatus()

ADI_RNG_RESULT adi_rng_GetRdyStatus ( ADI_RNG_HANDLE const  hDevice,
bool *const  pbFlag 
)

Retrieves the current state of RNG data/CRC accumulator register.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[out]pbFlagPointer to an application-defined boolean variable into which to write the result:
  • true = RNG data is ready to be read.
  • false = RNG data is not ready.
Returns
Status

Retrieve the current state of RNG data/CRC accumulator register. The register holds the final entropy value accumulated by RNG and it should to read only when the data is ready.

See also
adi_rng_Open().
adi_rng_GetRngData().
adi_rng_RegisterCallback().

Definition at line 359 of file adi_rng.c.

◆ adi_rng_GetStuckStatus()

ADI_RNG_RESULT adi_rng_GetStuckStatus ( ADI_RNG_HANDLE const  hDevice,
bool *const  pbFlag 
)

Retrieve whether the RNG oscillator output is stuck at a constant value.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[out]pbFlagPointer to an application-defined boolean variable into which to write the result:
  • true = RNG oscillator is stuck at a constant value.
  • false = RNG oscillator is not stuck at a constant value.
Returns
Status
See also
adi_rng_Open().
adi_rng_GetRngData().
adi_rng_RegisterCallback().

Definition at line 408 of file adi_rng.c.

◆ adi_rng_GetRngData()

ADI_RNG_RESULT adi_rng_GetRngData ( ADI_RNG_HANDLE const  hDevice,
uint32_t *const  pRegData 
)

Retrieve the current value of the RNG data register.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[in]pRegDataPointer to an application-defined variable into which to write the result. Only lower 8-bit is valid if buffering is not enabled
Returns
Status

Retrieve the current value of RNG data register. If the buffering is enabled all 32-bit of value written to pRegData is valid else only the lower 8-bit is valid.

See also
adi_rng_Open().
adi_rng_GetRdyStatus().
adi_rng_RegisterCallback().

Definition at line 464 of file adi_rng.c.

◆ adi_rng_GetOscCount()

ADI_RNG_RESULT adi_rng_GetOscCount ( ADI_RNG_HANDLE const  hDevice,
uint32_t *const  pOscCount 
)

Retrieve the current RNG Oscillator count.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[in]pOscCountPointer to an application-defined variable into which to write the result.
Returns
Status
See also
adi_rng_Open().
adi_rng_RegisterCallback().

Definition at line 509 of file adi_rng.c.

◆ adi_rng_GetOscDiff()

ADI_RNG_RESULT adi_rng_GetOscDiff ( ADI_RNG_HANDLE const  hDevice,
uint32_t const  nIndex,
uint8_t *const  pOscDiff 
)

Retrieve the current RNG Oscillator difference value for the given index.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[in]nIndexIndex of the difference register.
[out]pOscDiffPointer to an application-defined variable into which to write the oscillator difference value for the given index.
Returns
Status
See also
adi_rng_Open().
adi_Rng_RegisterCallback().

Definition at line 555 of file adi_rng.c.

◆ adi_rng_RegisterCallback()

ADI_RNG_RESULT adi_rng_RegisterCallback ( ADI_RNG_HANDLE  hDevice,
ADI_CALLBACK  cbFunc,
void *  pCBParam 
)

RNG Application callback registration API.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[in]cbFuncApplication callback address; the function to call on the interrupt.
[in]pCBParamApplication handle to be passed in the call back.
Returns
Status

Registers an application-defined callback cbFunc function address of type ADI_CALLBACK with the RNG device driver. Callbacks are made in response to received RNG interrupts.

The callback to the application is made in context of the originating interrupt (i.e., the RNG driver's RNG interrupt handler that is registered in the system's interrupt vector table). Extended processing during the callback (an extension of the RNG's interrupt handler) is discouraged so as to avoid lower-priority interrupt blocking. Also, any register read-modify-write operations should be protected using the ADI_ENTER_CRITICAL_REGION()/ADI_EXIT_CRITICAL_REGION() pair to prevent higher-priority interrupts from modifying said register during the read-modify-write operation.

Note
CALLBACKS: RNG interrupt callbacks are disabled by default during RNG device driver initialization (adi_rng_Open()). The application uses the adi_rng_RegisterCallback() API to request an application-defined callback from the RNG device driver. The RNG device driver clears the interrupt when the callback exits. The application callback should avoid extended processing during callbacks as the callback is executing context of the initiating interrupt and will block lower-priority interrupts. If extended application-level interrupt processing is required, the application should schedule it for the main application loop and exit the callback as soon as possible.
See also
adi_rng_Open().

Definition at line 677 of file adi_rng.c.

◆ adi_rng_GetSampleLen()

ADI_RNG_RESULT adi_rng_GetSampleLen ( ADI_RNG_HANDLE const  hDevice,
uint16_t *const  pLenPrescaler,
uint16_t *const  pLenReload 
)

Retrieve the current RNG sample length prescale and reload value configured in the device.

Parameters
[in]hDeviceDevice handle obtained from adi_rng_Open().
[out]pLenPrescalerPointer to an application-defined variable into which the prescaler value is written.
[out]pLenReloadPointer to an application-defined variable into which the reload value for the sample counter is written.
Returns
Status
See also
adi_rng_Open().
adi_rng_RegisterCallback().

Definition at line 604 of file adi_rng.c.