HAL RNG How to Use ¶

group RNG_How_To_Use

¶

The RNG main features: ¶

The true random number generator (RNG) is a NIST SP 800-90B compliant entropy source delivers a 32-bit random numbers, It has an AMBA AHB slave peripheral, accessible through 32-bit word single accesses only. It can be disabled to reduce power consumption, or enabled with an automatic low power mode (default configuration).The RNG has been pre-certified NIST SP800-90B and it has been also tested with the German BSI statistical tests of AIS-31 (T0 to T8).

How to use the HAL RNG driver ¶

The HAL RNG driver can be used as follows: ¶

• Initialize the RNG handle by calling the HAL_RNG_Init() API that performs these operations:

  • Associate instance to the handle

  • Enable the RNG clock interface (When USE_HAL_RNG_CLK_ENABLE_MODEL compilation flag is set to HAL_CLK_ENABLE_PERIPH_ONLY or HAL_CLK_ENABLE_PERIPH_PWR_SYSTEM in the stm32u5xx_hal_conf.h module)

  • The initialization of the handle state to the HAL_RNG_STATE_IDLE.

• Configure the RNG peripheral with one of the following configuration :

  1. Custom Configuration:

     • Declare a hal_rng_config_t structure

     • Fill all parameters of the declared configuration structure

     • Call HAL_RNG_SetConfig() function with the filled configuration structure

  2. NIST compliant configuration:

     • Call HAL_RNG_SetCertifiedNISTConfig() function.

  3. Candidate NIST compliant configuration:

     • Call HAL_RNG_SetCandidateNISTConfig() function.

  4. Candidate German BSI compliant configuration:

     • Call HAL_RNG_SetCandidateGermanBSIConfig() function.

• To protect the peripheral from any configuration, call the HAL_RNG_LockConfig() . When locked, it’s not allowed to apply any new configuration. The configuration is then possible only after a system reset or RNG peripheral reset through RCC.

• When needed, unitary reconfiguration can be done through:

  • HAL_RNG_EnableClockErrorDetection() and HAL_RNG_DisableClockErrorDetection() to enable (resp. disable) the clock error detection feature.

  • HAL_RNG_EnableAutoReset() and HAL_RNG_DisableAutoReset() to enable (resp. disable) the automatic reset after seed error feature.

  • HAL_RNG_SetClockDivider() to set a new kernel clock divider.

• The RNG can generates random numbers in two different modes:

  • Polling mode:

    1. Call HAL_RNG_GenerateRandomNumber() with specifying :

       • The number of words to be generated.

       • The application buffer where the data will be stored.

         • The maximum timeout for random number words to be generated.

    2. When a seed error occurs, call the HAL_RNG_RecoverSeedError() . (The recovery is not granted through this function due to hardware constraint)

  • Interrupt mode operation:

    1. Call HAL_RNG_GenerateRandomNumber_IT() with specifying :

       • The number of words to be generated.

       • The application buffer where the data will be stored.

    2. Call HAL_RNG_IRQHandler() to handle RNG interrupts and to store the generated number words within the specified user buffer.

    3. When all random numbers specified by the user are generated, HAL_RNG_GenerationCpltCallback() is executed.

    4. When a seed error occurs during the generation process, HAL_RNG_ErrorCallback() is executed where it is recommended to call HAL_RNG_RecoverSeedError() .

• Deinitialize the RNG peripheral user can call the HAL_RNG_DeInit() .

• Retrieve the HAL RNG information:

  • Use HAL_RNG_GetState() function to return the RNG state.

  • Use HAL_RNG_GetConfig() to get RNG configurations.

  • Use HAL_RNG_IsEnabledClockErrorDetection() to check whether the clock error detection feature is enabled or not.

  • Use HAL_RNG_IsEnabledAutoReset() to check whether the auto reset feature is enabled or not.

  • Use HAL_RNG_GetClockDivider() to get the clock divider configuration.

  • Set the compilation flag USE_HAL_RNG_GET_LAST_ERRORS to 1U in the stm32u5xx_hal_conf.h module to retrieve the last error code detected by the HAL RNG driver through the HAL_RNG_GetLastErrorCodes API.

• Register callback:

  • When the compilation flag USE_HAL_RNG_REGISTER_CALLBACKS is set to 1 in the stm32u5xx_hal_conf.h, it allows to configure dynamically the driver callbacks instead of using default ones.

  • Call HAL_RNG_RegisterGenerationCpltCallback() for end of generation random number event.

  • Call HAL_RNG_RegisterErrorCallback() for generation random number error events.