HAL RNG Functions

Initialization and de-initialization functions

STM32C562xx STM32C5A3xx STM32C542xx

group RNG_Exported_Functions_Group1

This subsection provides a set of functions that allow you to initialize and de-initialize the RNG peripheral:

• HAL_RNG_Init() to initialize the selected HAL RNG handle and associate an RNG peripheral instance.

• HAL_RNG_DeInit() to de-initialize the given HAL RNG instance and reset the state machine.

Functions

hal_status_t HAL_RNG_Init ( hal_rng_handle_t * hrng , hal_rng_t instance )

Initialize the RNG handle and associate an instance.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• instance – one of the values of the enumeration hal_rng_t.

Return values :

• HAL_OK – RNG handle has been correctly initialized.

• HAL_INVALID_PARAM – invalid parameter.

void HAL_RNG_DeInit ( hal_rng_handle_t * hrng )

DeInitialize the RNG peripheral.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Configuration functions

STM32C562xx STM32C5A3xx STM32C542xx

group RNG_Exported_Functions_Group2

This subsection provides a set of APIs to configure the RNG peripheral:

• HAL_RNG_SetConfig() sets the configuration of the RNG peripheral.

• HAL_RNG_SetCandidateNISTConfig() sets the RNG peripheral within a candidate NIST compliant configuration.

• HAL_RNG_SetCandidateGermanBSIConfig() sets the RNG peripheral within a candidate German BSI compliant configuration.

• HAL_RNG_GetConfig() retrieves the RNG peripheral configuration.

• HAL_RNG_EnableClockErrorDetection() enables the clock error detection feature.

• HAL_RNG_DisableClockErrorDetection() disables the clock error detection feature.

• HAL_RNG_IsEnabledClockErrorDetection() checks whether the clock error detection feature is enabled.

• HAL_RNG_EnableAutoReset() enables the auto reset feature.

• HAL_RNG_DisableAutoReset() disables the auto reset feature.

• HAL_RNG_IsEnabledAutoReset() checks whether the auto reset feature is enabled.

• HAL_RNG_SetClockDivider() sets the clock divider.

• HAL_RNG_GetClockDivider() retrieves the clock divider value.

Functions

hal_status_t HAL_RNG_SetConfig ( hal_rng_handle_t * hrng , const hal_rng_config_t * p_config )

Configure the RNG with the specified parameters in the hal_rng_config_t.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• p_config – pointer to hal_rng_config_t structure.

Return values :

• HAL_OK – configuration succeeded.

• HAL_ERROR – configuration fail.

• HAL_INVALID_PARAM – invalid parameter.

hal_status_t HAL_RNG_SetCandidateNISTConfig ( hal_rng_handle_t * hrng )

Configure the RNG with the candidate NIST compliant configuration.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

• HAL_OK – configuration succeeded.

• HAL_ERROR – configuration fail.

• HAL_INVALID_PARAM – invalid parameter.

hal_status_t HAL_RNG_SetCandidateGermanBSIConfig ( hal_rng_handle_t * hrng )

Configure the RNG with the candidate German BSI compliant configuration.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

• HAL_OK – configuration succeeded.

• HAL_ERROR – configuration fail.

• HAL_INVALID_PARAM – invalid parameter.

hal_status_t HAL_RNG_SetHealthFactorConfig ( hal_rng_handle_t * hrng , hal_rng_htcr_idx_t htcr_idx , uint32_t htcr_value )

Configure the RNG additional health tests.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• htcr_idx – is a value of the hal_rng_htcr_idx_t enumeration.

• htcr_value – Health test value.

Return values :

• HAL_OK – configuration succeeded.

• HAL_ERROR – configuration fail.

• HAL_INVALID_PARAM – invalid parameter.

uint32_t HAL_RNG_GetHealthFactorConfig ( const hal_rng_handle_t * hrng , hal_rng_htcr_idx_t htcr_idx )

Get RNG additional health tests config.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• htcr_idx – is a value of the hal_rng_htcr_idx_t enumeration.

Return values :

factor_config – uint32_t additional health test value between 0x0 and 0xFFFF.

void HAL_RNG_GetConfig ( const hal_rng_handle_t * hrng , hal_rng_config_t * p_config )

Get the RNG configuration and fill parameters in the hal_rng_config_t.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• p_config – pointer to hal_rng_config_t structure. module

hal_status_t HAL_RNG_EnableClockErrorDetection ( hal_rng_handle_t * hrng )

Enable the clock error detection feature.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

• HAL_OK – configuration succeeded.

• HAL_ERROR – configuration fail.

• HAL_INVALID_PARAM – invalid parameter.

hal_status_t HAL_RNG_DisableClockErrorDetection ( hal_rng_handle_t * hrng )

Disable the clock error detection feature.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

• HAL_OK – configuration succeeded.

• HAL_ERROR – configuration fail.

• HAL_INVALID_PARAM – invalid parameter.

hal_rng_clock_error_detection_status_t HAL_RNG_IsEnabledClockErrorDetection ( const hal_rng_handle_t * hrng )

Check the clock error detection status.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

hal_rng_clock_error_detection_status_t – error detection state.

hal_status_t HAL_RNG_EnableAutoReset ( hal_rng_handle_t * hrng )

Enable the automatic reset.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

• HAL_OK – auto-reset enabled successfully.

• HAL_ERROR – fail to enable the auto-reset.

• HAL_INVALID_PARAM – invalid parameter.

hal_status_t HAL_RNG_DisableAutoReset ( hal_rng_handle_t * hrng )

Disable the auto reset.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

• HAL_OK – auto-reset disabled successfully.

• HAL_ERROR – fail to disable the auto-reset.

• HAL_INVALID_PARAM – invalid parameter.

hal_rng_auto_reset_status_t HAL_RNG_IsEnabledAutoReset ( const hal_rng_handle_t * hrng )

Check the status of the auto reset.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

hal_rng_auto_reset_status_t – auto-reset state

hal_status_t HAL_RNG_SetClockDivider ( hal_rng_handle_t * hrng , hal_rng_clock_divider_t clk_divider )

Set RNG Clock divider factor.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• clk_divider – is a value of the hal_rng_clock_divider_t enumeration.

Return values :

• HAL_OK – clock divider set successfully.

• HAL_ERROR – fail to set the clock divider.

• HAL_INVALID_PARAM – invalid parameter.

hal_rng_clock_divider_t HAL_RNG_GetClockDivider ( const hal_rng_handle_t * hrng )

Get RNG Clock divider factor.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

hal_rng_clock_divider_t – Clock divider.

Peripheral control functions

STM32C562xx STM32C5A3xx STM32C542xx

group RNG_Exported_Functions_Group3

This subsection provides a set of APIs to generate random numbers in polling and interrupt modes:

• HAL_RNG_GenerateRandomNumber() generates N random number words in polling mode.

• HAL_RNG_GenerateRandomNumber_IT() generates N random number words in interrupt mode.

• HAL_RNG_IRQHandler() handles RNG interrupt requests.

Functions

hal_status_t HAL_RNG_GenerateRandomNumber ( hal_rng_handle_t * hrng , uint32_t * p_data , uint32_t size_word , uint32_t timeout_ms )

Generate N 32-bit random numbers in polling mode.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• p_data – pointer to be filled with random number.

• size_word – total number of random numbers to be generated.

• timeout_ms – timeout in milliseconds.

Return values :

• HAL_OK – random numbers are generated successfully.

• HAL_ERROR – seed error occurred when generating random numbers.

• HAL_TIMEOUT – timeout occurred when generating random numbers.

• HAL_BUSY – process is already ongoing.

• HAL_INVALID_PARAM – invalid parameter.

hal_status_t HAL_RNG_GenerateRandomNumber_IT ( hal_rng_handle_t * hrng , uint32_t * p_data , uint32_t size_word )

Generate a N x 32-bit random number in interrupt mode.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• p_data – pointer to be filled with random number.

• size_word – total number of random number to be generated.

Return values :

• HAL_OK – 32-bit random number generated successfully.

• HAL_BUSY – process is already ongoing.

• HAL_INVALID_PARAM – invalid parameter.

void HAL_RNG_IRQHandler ( hal_rng_handle_t * hrng )

Handle the RNG interrupt request.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Seed error recovery function

STM32C562xx STM32C5A3xx STM32C542xx

group RNG_Exported_Functions_Group4

This subsection provides the RNG recover from seed error function :

• HAL_RNG_RecoverSeedError() recover seed error when occurs.

Functions

hal_status_t HAL_RNG_RecoverSeedError ( hal_rng_handle_t * hrng )

Recover the RNG sequence when a seed error occurs.

Warning

Recover from seed error will adapt the parameters config1,2,3 to overcome seed error.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

• HAL_OK – operation succeeded

• HAL_ERROR – operation failed

• HAL_INVALID_PARAM – invalid parameter.

Callbacks functions

STM32C562xx STM32C5A3xx STM32C542xx

group RNG_Exported_Functions_Group5

This subsection provides a set of RNG callback registration APIs:

• HAL_RNG_RegisterGenerationCpltCallback() register a callback function for interrupts when generation completes.

• HAL_RNG_RegisterErrorCallback() register a callback function for interrupts when an error occurs.

Functions

void HAL_RNG_ErrorCallback ( hal_rng_handle_t * hrng )

Handle the RNG error callback.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

void HAL_RNG_GenerationCpltCallback ( hal_rng_handle_t * hrng )

Handle the Random number generation complete callback in non-blocking mode.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

hal_status_t HAL_RNG_RegisterGenerationCpltCallback ( hal_rng_handle_t * hrng , hal_rng_cb_t callback )

Register random number RNG generation complete callback.

To be used instead of the weak

HAL_RNG_GenerationCpltCallback().

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• callback – pointer to the random number Ready callback function.

Return values :

• HAL_OK – succeeded.

• HAL_INVALID_PARAM – invalid callback.

hal_status_t HAL_RNG_RegisterErrorCallback ( hal_rng_handle_t * hrng , hal_rng_cb_t callback )

Register a User RNG callback.

To be used instead of the weak HAL_RNG_RegisterErrorCallback.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• callback – pointer to the callback function

Return values :

• HAL_OK – succeeded.

• HAL_INVALID_PARAM – invalid callback.

User Data functions

STM32C562xx STM32C5A3xx STM32C542xx

group RNG_Exported_Functions_Group6

This subsection provides a set of functions to set and get user data:

• HAL_RNG_SetUserData() store the user data pointer in the handle.

• HAL_RNG_GetUserData() retrieve the user data pointer from the handle.

Functions

void HAL_RNG_SetUserData ( hal_rng_handle_t * hrng , const void * p_user_data )

Store the user data into the RNG handle.

Parameters :

• hrng – pointer to hal_rng_handle_t structure.

• p_user_data – pointer to the user data.

const void * HAL_RNG_GetUserData ( const hal_rng_handle_t * hrng )

Retrieve the user data from the RNG handle.

Parameters :

hrng – Pointer to RNG handle.

Return values :

Pointer – to the user data.

Status functions

STM32C562xx STM32C5A3xx STM32C542xx

group RNG_Exported_Functions_Group7

This subsection provides a set of functions to retrieve the state and the error codes

• HAL_RNG_GetState() retrieve the global state of the current RNG peripheral.

• HAL_RNG_GetLastErrorCodes() retrieve the last error code of the RNG peripheral.

Functions

hal_rng_state_t HAL_RNG_GetState ( const hal_rng_handle_t * hrng )

Return the RNG state.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

hal_rng_state_t – RNG global state.

uint32_t HAL_RNG_GetLastErrorCodes ( const hal_rng_handle_t * hrng )

Return the RNG handle error code.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

uint32_t – RNG last error codes.

Lock configuration functions

STM32C562xx STM32C5A3xx STM32C542xx

group RNG_Exported_Functions_Group8

This subsection provides a set of functions to lock RNG configuration.

• HAL_RNG_LockConfig() locks the RNG configuration.

• HAL_RNG_IsConfigLocked() checks whether the RNG peripheral configuration is locked.

Functions

hal_status_t HAL_RNG_LockConfig ( hal_rng_handle_t * hrng )

Lock the current RNG configuration.

Warning

This function locks the RNG peripheral configuration. Once locked, perform a system reset or RNG peripheral reset through RCC before any further configuration update.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

• HAL_OK – configuration locked successfully.

• HAL_INVALID_PARAM – invalid parameter.

• HAL_TIMEOUT – operation exceeds the config lock timeout.

hal_rng_lock_config_status_t HAL_RNG_IsConfigLocked ( const hal_rng_handle_t * hrng )

Check if RNG Config Lock is enabled.

Parameters :

hrng – pointer to hal_rng_handle_t structure.

Return values :

hal_rng_lock_config_status_t – RNG lock config state.