lib/main/STM32F7/Drivers/STM32F7xx_HAL_Driver/Src/stm32f7xx_hal_rng.c

   1 /**
   2   ******************************************************************************
   3   * @file    stm32f7xx_hal_rng.c
   4   * @author  MCD Application Team
   5   * @version V1.2.2
   6   * @date    14-April-2017
   7   * @brief   RNG HAL module driver.
   8   *          This file provides firmware functions to manage the following
   9   *          functionalities of the Random Number Generator (RNG) peripheral:
  10   *           + Initialization/de-initialization functions
  11   *           + Peripheral Control functions
  12   *           + Peripheral State functions
  13   *
  14   @verbatim
  15   ==============================================================================
  16                      ##### How to use this driver #####
  17   ==============================================================================
  18   [..]
  19       The RNG HAL driver can be used as follows:
  20
  21       (#) Enable the RNG controller clock using __HAL_RCC_RNG_CLK_ENABLE() macro
  22           in HAL_RNG_MspInit().
  23       (#) Activate the RNG peripheral using HAL_RNG_Init() function.
  24       (#) Wait until the 32 bit Random Number Generator contains a valid
  25           random data using (polling/interrupt) mode.
  26       (#) Get the 32 bit random number using HAL_RNG_GenerateRandomNumber() function.
  27
  28   @endverbatim
  29   ******************************************************************************
  30   * @attention
  31   *
  32   * <h2><center>&copy; COPYRIGHT(c) 2017 STMicroelectronics</center></h2>
  33   *
  34   * Redistribution and use in source and binary forms, with or without modification,
  35   * are permitted provided that the following conditions are met:
  36   *   1. Redistributions of source code must retain the above copyright notice,
  37   *      this list of conditions and the following disclaimer.
  38   *   2. Redistributions in binary form must reproduce the above copyright notice,
  39   *      this list of conditions and the following disclaimer in the documentation
  40   *      and/or other materials provided with the distribution.
  41   *   3. Neither the name of STMicroelectronics nor the names of its contributors
  42   *      may be used to endorse or promote products derived from this software
  43   *      without specific prior written permission.
  44   *
  45   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  46   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  47   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  48   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  49   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  50   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  51   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  52   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  53   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  54   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  55   *
  56   ******************************************************************************
  57   */
  58
  59 /* Includes ------------------------------------------------------------------*/
  60 #include "stm32f7xx_hal.h"
  61
  62 /** @addtogroup STM32F7xx_HAL_Driver
  63   * @{
  64   */
  65
  66 /** @addtogroup RNG
  67   * @{
  68   */
  69
  70 #ifdef HAL_RNG_MODULE_ENABLED
  71
  72 /* Private types -------------------------------------------------------------*/
  73 /* Private defines -----------------------------------------------------------*/
  74 /* Private variables ---------------------------------------------------------*/
  75 /* Private constants ---------------------------------------------------------*/
  76 /** @addtogroup RNG_Private_Constants
  77   * @{
  78   */
  79 #define RNG_TIMEOUT_VALUE     2
  80 /**
  81   * @}
  82   */
  83 /* Private macros ------------------------------------------------------------*/
  84 /* Private functions prototypes ----------------------------------------------*/
  85 /* Private functions ---------------------------------------------------------*/
  86 /* Exported functions --------------------------------------------------------*/
  87
  88 /** @addtogroup RNG_Exported_Functions
  89   * @{
  90   */
  91
  92 /** @addtogroup RNG_Exported_Functions_Group1
  93  *  @brief   Initialization and de-initialization functions
  94  *
  95 @verbatim
  96  ===============================================================================
  97           ##### Initialization and de-initialization functions #####
  98  ===============================================================================
  99     [..]  This section provides functions allowing to:
 100       (+) Initialize the RNG according to the specified parameters
 101           in the RNG_InitTypeDef and create the associated handle
 102       (+) DeInitialize the RNG peripheral
 103       (+) Initialize the RNG MSP
 104       (+) DeInitialize RNG MSP
 105
 106 @endverbatim
 107   * @{
 108   */
 109
 110 /**
 111   * @brief  Initializes the RNG peripheral and creates the associated handle.
 112   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 113   *                the configuration information for RNG.
 114   * @retval HAL status
 115   */
 116 HAL_StatusTypeDef HAL_RNG_Init(RNG_HandleTypeDef *hrng)
 117 {
 118   /* Check the RNG handle allocation */
 119   if(hrng == NULL)
 120   {
 121     return HAL_ERROR;
 122   }
 123
 124   __HAL_LOCK(hrng);
 125
 126   if(hrng->State == HAL_RNG_STATE_RESET)
 127   {
 128     /* Allocate lock resource and initialize it */
 129     hrng->Lock = HAL_UNLOCKED;
 130
 131     /* Init the low level hardware */
 132     HAL_RNG_MspInit(hrng);
 133   }
 134
 135   /* Change RNG peripheral state */
 136   hrng->State = HAL_RNG_STATE_BUSY;
 137
 138   /* Enable the RNG Peripheral */
 139   __HAL_RNG_ENABLE(hrng);
 140
 141   /* Initialize the RNG state */
 142   hrng->State = HAL_RNG_STATE_READY;
 143
 144   __HAL_UNLOCK(hrng);
 145
 146   /* Return function status */
 147   return HAL_OK;
 148 }
 149
 150 /**
 151   * @brief  DeInitializes the RNG peripheral.
 152   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 153   *                the configuration information for RNG.
 154   * @retval HAL status
 155   */
 156 HAL_StatusTypeDef HAL_RNG_DeInit(RNG_HandleTypeDef *hrng)
 157 {
 158   /* Check the RNG handle allocation */
 159   if(hrng == NULL)
 160   {
 161     return HAL_ERROR;
 162   }
 163   /* Disable the RNG Peripheral */
 164   CLEAR_BIT(hrng->Instance->CR, RNG_CR_IE | RNG_CR_RNGEN);
 165
 166   /* Clear RNG interrupt status flags */
 167   CLEAR_BIT(hrng->Instance->SR, RNG_SR_CEIS | RNG_SR_SEIS);
 168
 169   /* DeInit the low level hardware */
 170   HAL_RNG_MspDeInit(hrng);
 171
 172   /* Update the RNG state */
 173   hrng->State = HAL_RNG_STATE_RESET;
 174
 175   /* Release Lock */
 176   __HAL_UNLOCK(hrng);
 177
 178   /* Return the function status */
 179   return HAL_OK;
 180 }
 181
 182 /**
 183   * @brief  Initializes the RNG MSP.
 184   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 185   *                the configuration information for RNG.
 186   * @retval None
 187   */
 188 __weak void HAL_RNG_MspInit(RNG_HandleTypeDef *hrng)
 189 {
 190   /* Prevent unused argument(s) compilation warning */
 191   UNUSED(hrng);
 192
 193   /* NOTE : This function should not be modified. When the callback is needed,
 194             function HAL_RNG_MspInit must be implemented in the user file.
 195    */
 196 }
 197
 198 /**
 199   * @brief  DeInitializes the RNG MSP.
 200   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 201   *                the configuration information for RNG.
 202   * @retval None
 203   */
 204 __weak void HAL_RNG_MspDeInit(RNG_HandleTypeDef *hrng)
 205 {
 206   /* Prevent unused argument(s) compilation warning */
 207   UNUSED(hrng);
 208
 209   /* NOTE : This function should not be modified. When the callback is needed,
 210             function HAL_RNG_MspDeInit must be implemented in the user file.
 211    */
 212 }
 213
 214 /**
 215   * @}
 216   */
 217
 218 /** @addtogroup RNG_Exported_Functions_Group2
 219  *  @brief   Peripheral Control functions
 220  *
 221 @verbatim
 222  ===============================================================================
 223                       ##### Peripheral Control functions #####
 224  ===============================================================================
 225     [..]  This section provides functions allowing to:
 226       (+) Get the 32 bit Random number
 227       (+) Get the 32 bit Random number with interrupt enabled
 228       (+) Handle RNG interrupt request
 229
 230 @endverbatim
 231   * @{
 232   */
 233
 234 /**
 235   * @brief  Generates a 32-bit random number.
 236   * @note   Each time the random number data is read the RNG_FLAG_DRDY flag
 237   *         is automatically cleared.
 238   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 239   *                the configuration information for RNG.
 240   * @param  random32bit: pointer to generated random number variable if successful.
 241   * @retval HAL status
 242   */
 243
 244 HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber(RNG_HandleTypeDef *hrng, uint32_t *random32bit)
 245 {
 246   uint32_t tickstart = 0;
 247   HAL_StatusTypeDef status = HAL_OK;
 248
 249   /* Process Locked */
 250   __HAL_LOCK(hrng);
 251
 252   /* Check RNG peripheral state */
 253   if(hrng->State == HAL_RNG_STATE_READY)
 254   {
 255     /* Change RNG peripheral state */
 256     hrng->State = HAL_RNG_STATE_BUSY;
 257
 258     /* Get tick */
 259     tickstart = HAL_GetTick();
 260
 261     /* Check if data register contains valid random data */
 262     while(__HAL_RNG_GET_FLAG(hrng, RNG_FLAG_DRDY) == RESET)
 263     {
 264       if((HAL_GetTick() - tickstart ) > RNG_TIMEOUT_VALUE)
 265       {
 266         hrng->State = HAL_RNG_STATE_ERROR;
 267
 268         /* Process Unlocked */
 269         __HAL_UNLOCK(hrng);
 270
 271         return HAL_TIMEOUT;
 272       }
 273     }
 274
 275     /* Get a 32bit Random number */
 276     hrng->RandomNumber = hrng->Instance->DR;
 277     *random32bit = hrng->RandomNumber;
 278
 279     hrng->State = HAL_RNG_STATE_READY;
 280   }
 281   else
 282   {
 283     status = HAL_ERROR;
 284   }
 285
 286   /* Process Unlocked */
 287   __HAL_UNLOCK(hrng);
 288
 289   return status;
 290 }
 291
 292 /**
 293   * @brief  Generates a 32-bit random number in interrupt mode.
 294   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 295   *                the configuration information for RNG.
 296   * @retval HAL status
 297   */
 298 HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber_IT(RNG_HandleTypeDef *hrng)
 299 {
 300   HAL_StatusTypeDef status = HAL_OK;
 301
 302   /* Process Locked */
 303   __HAL_LOCK(hrng);
 304
 305   /* Check RNG peripheral state */
 306   if(hrng->State == HAL_RNG_STATE_READY)
 307   {
 308     /* Change RNG peripheral state */
 309     hrng->State = HAL_RNG_STATE_BUSY;
 310
 311     /* Process Unlocked */
 312     __HAL_UNLOCK(hrng);
 313
 314     /* Enable the RNG Interrupts: Data Ready, Clock error, Seed error */
 315     __HAL_RNG_ENABLE_IT(hrng);
 316   }
 317   else
 318   {
 319     /* Process Unlocked */
 320     __HAL_UNLOCK(hrng);
 321
 322     status = HAL_ERROR;
 323   }
 324
 325   return status;
 326 }
 327
 328 /**
 329   * @brief  Handles RNG interrupt request.
 330   * @note   In the case of a clock error, the RNG is no more able to generate
 331   *         random numbers because the PLL48CLK clock is not correct. User has
 332   *         to check that the clock controller is correctly configured to provide
 333   *         the RNG clock and clear the CEIS bit using __HAL_RNG_CLEAR_IT().
 334   *         The clock error has no impact on the previously generated
 335   *         random numbers, and the RNG_DR register contents can be used.
 336   * @note   In the case of a seed error, the generation of random numbers is
 337   *         interrupted as long as the SECS bit is '1'. If a number is
 338   *         available in the RNG_DR register, it must not be used because it may
 339   *         not have enough entropy. In this case, it is recommended to clear the
 340   *         SEIS bit using __HAL_RNG_CLEAR_IT(), then disable and enable
 341   *         the RNG peripheral to reinitialize and restart the RNG.
 342   * @note   User-written HAL_RNG_ErrorCallback() API is called once whether SEIS
 343   *         or CEIS are set.
 344   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 345   *                the configuration information for RNG.
 346   * @retval None
 347
 348   */
 349 void HAL_RNG_IRQHandler(RNG_HandleTypeDef *hrng)
 350 {
 351   /* RNG clock error interrupt occurred */
 352   if((__HAL_RNG_GET_IT(hrng, RNG_IT_CEI) != RESET) ||  (__HAL_RNG_GET_IT(hrng, RNG_IT_SEI) != RESET))
 353   {
 354     /* Change RNG peripheral state */
 355     hrng->State = HAL_RNG_STATE_ERROR;
 356
 357     HAL_RNG_ErrorCallback(hrng);
 358
 359     /* Clear the clock error flag */
 360     __HAL_RNG_CLEAR_IT(hrng, RNG_IT_CEI|RNG_IT_SEI);
 361
 362   }
 363
 364   /* Check RNG data ready interrupt occurred */
 365   if(__HAL_RNG_GET_IT(hrng, RNG_IT_DRDY) != RESET)
 366   {
 367     /* Generate random number once, so disable the IT */
 368     __HAL_RNG_DISABLE_IT(hrng);
 369
 370     /* Get the 32bit Random number (DRDY flag automatically cleared) */
 371     hrng->RandomNumber = hrng->Instance->DR;
 372
 373     if(hrng->State != HAL_RNG_STATE_ERROR)
 374     {
 375       /* Change RNG peripheral state */
 376       hrng->State = HAL_RNG_STATE_READY;
 377
 378       /* Data Ready callback */
 379       HAL_RNG_ReadyDataCallback(hrng, hrng->RandomNumber);
 380     }
 381   }
 382 }
 383
 384 /**
 385   * @brief  Returns generated random number in polling mode (Obsolete)
 386   *         Use HAL_RNG_GenerateRandomNumber() API instead.
 387   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 388   *                the configuration information for RNG.
 389   * @retval Random value
 390   */
 391 uint32_t HAL_RNG_GetRandomNumber(RNG_HandleTypeDef *hrng)
 392 {
 393   if(HAL_RNG_GenerateRandomNumber(hrng, &(hrng->RandomNumber)) == HAL_OK)
 394   {
 395     return hrng->RandomNumber;
 396   }
 397   else
 398   {
 399     return 0;
 400   }
 401 }
 402
 403 /**
 404   * @brief  Returns a 32-bit random number with interrupt enabled (Obsolete),
 405   *         Use HAL_RNG_GenerateRandomNumber_IT() API instead.
 406   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 407   *                the configuration information for RNG.
 408   * @retval 32-bit random number
 409   */
 410 uint32_t HAL_RNG_GetRandomNumber_IT(RNG_HandleTypeDef *hrng)
 411 {
 412   uint32_t random32bit = 0;
 413
 414   /* Process locked */
 415   __HAL_LOCK(hrng);
 416
 417   /* Change RNG peripheral state */
 418   hrng->State = HAL_RNG_STATE_BUSY;
 419
 420   /* Get a 32bit Random number */
 421   random32bit = hrng->Instance->DR;
 422
 423   /* Enable the RNG Interrupts: Data Ready, Clock error, Seed error */
 424   __HAL_RNG_ENABLE_IT(hrng);
 425
 426   /* Return the 32 bit random number */
 427   return random32bit;
 428 }
 429
 430 /**
 431   * @brief  Read latest generated random number.
 432   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 433   *                the configuration information for RNG.
 434   * @retval random value
 435   */
 436 uint32_t HAL_RNG_ReadLastRandomNumber(RNG_HandleTypeDef *hrng)
 437 {
 438   return(hrng->RandomNumber);
 439 }
 440
 441 /**
 442   * @brief  Data Ready callback in non-blocking mode.
 443   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 444   *                the configuration information for RNG.
 445   * @param  random32bit: generated random number.
 446   * @retval None
 447   */
 448 __weak void HAL_RNG_ReadyDataCallback(RNG_HandleTypeDef *hrng, uint32_t random32bit)
 449 {
 450   /* Prevent unused argument(s) compilation warning */
 451   UNUSED(hrng);
 452
 453   /* NOTE : This function should not be modified. When the callback is needed,
 454             function HAL_RNG_ReadyDataCallback must be implemented in the user file.
 455    */
 456 }
 457
 458 /**
 459   * @brief  RNG error callbacks.
 460   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 461   *                the configuration information for RNG.
 462   * @retval None
 463   */
 464 __weak void HAL_RNG_ErrorCallback(RNG_HandleTypeDef *hrng)
 465 {
 466   /* Prevent unused argument(s) compilation warning */
 467   UNUSED(hrng);
 468
 469   /* NOTE : This function should not be modified. When the callback is needed,
 470             function HAL_RNG_ErrorCallback must be implemented in the user file.
 471    */
 472 }
 473 /**
 474   * @}
 475   */
 476
 477
 478 /** @addtogroup RNG_Exported_Functions_Group3
 479  *  @brief   Peripheral State functions
 480  *
 481 @verbatim
 482  ===============================================================================
 483                       ##### Peripheral State functions #####
 484  ===============================================================================
 485     [..]
 486     This subsection permits to get in run-time the status of the peripheral
 487     and the data flow.
 488
 489 @endverbatim
 490   * @{
 491   */
 492
 493 /**
 494   * @brief  Returns the RNG state.
 495   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 496   *                the configuration information for RNG.
 497   * @retval HAL state
 498   */
 499 HAL_RNG_StateTypeDef HAL_RNG_GetState(RNG_HandleTypeDef *hrng)
 500 {
 501   return hrng->State;
 502 }
 503
 504 /**
 505   * @}
 506   */
 507
 508 /**
 509   * @}
 510   */
 511
 512 #endif /* HAL_RNG_MODULE_ENABLED */
 513
 514 /**
 515   * @}
 516   */
 517
 518 /**
 519   * @}
 520   */
 521
 522 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/