tool/mbed/mbed-sdk/libraries/mbed/targets/cmsis/TARGET_STM/TARGET_STM32L0/stm32l0xx_hal_rng.c

   1 /**
   2   ******************************************************************************
   3   * @file    stm32l0xx_hal_rng.c
   4   * @author  MCD Application Team
   5   * @version V1.2.0
   6   * @date    06-February-2015
   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) 2015 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 "stm32l0xx_hal.h"
  61
  62 /** @addtogroup STM32L0xx_HAL_Driver
  63   * @{
  64   */
  65
  66 /** @addtogroup RNG
  67   * @{
  68   */
  69
  70 #ifdef HAL_RNG_MODULE_ENABLED
  71
  72
  73 #if defined (STM32L052xx) || defined (STM32L053xx) || defined (STM32L062xx) ||  defined (STM32L063xx) || \
  74     defined (STM32L072xx) || defined (STM32L073xx) || defined (STM32L082xx) ||  defined (STM32L083xx)
  75 /* Private types -------------------------------------------------------------*/
  76 /* Private Defines -----------------------------------------------------------*/
  77 /** @addtogroup RNG_Private_Defines
  78   * @{
  79   */
  80 #define RNG_TIMEOUT_VALUE     1000
  81 /**
  82   * @}
  83   */
  84
  85 /* Private variables ---------------------------------------------------------*/
  86 /* Private constants ---------------------------------------------------------*/
  87 /* Private macros ------------------------------------------------------------*/
  88 /* Private functions prototypes ----------------------------------------------*/
  89 /* Private functions ---------------------------------------------------------*/
  90 /* Exported functions --------------------------------------------------------*/
  91
  92 /** @addtogroup RNG_Exported_Functions
  93   * @{
  94   */
  95
  96 /** @addtogroup RNG_Exported_Functions_Group1
  97  *  @brief   Initialization and de-initialization functions
  98  *
  99 @verbatim
 100  ===============================================================================
 101           ##### Initialization and de-initialization functions #####
 102  ===============================================================================
 103     [..]  This section provides functions allowing to:
 104       (+) Initialize the RNG according to the specified parameters
 105           in the RNG_InitTypeDef and create the associated handle
 106       (+) DeInitialize the RNG peripheral
 107       (+) Initialize the RNG MSP
 108       (+) DeInitialize RNG MSP
 109
 110 @endverbatim
 111   * @{
 112   */
 113
 114 /**
 115   * @brief  Initializes the RNG peripheral and creates the associated handle.
 116   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 117   * @retval HAL status
 118   */
 119 HAL_StatusTypeDef HAL_RNG_Init(RNG_HandleTypeDef *hrng)
 120 {
 121   /* Check the RNG handle allocation */
 122   if(hrng == NULL)
 123   {
 124     return HAL_ERROR;
 125   }
 126   assert_param(IS_RNG_ALL_INSTANCE(hrng->Instance));
 127
 128   __HAL_LOCK(hrng);
 129
 130   if(hrng->State == HAL_RNG_STATE_RESET)
 131   {
 132     /* Init the low level hardware */
 133     HAL_RNG_MspInit(hrng);
 134   }
 135
 136   /* Change RNG peripheral state */
 137   hrng->State = HAL_RNG_STATE_BUSY;
 138
 139   /* Enable the RNG Peripheral */
 140   __HAL_RNG_ENABLE(hrng);
 141
 142   /* Initialize the RNG state */
 143   hrng->State = HAL_RNG_STATE_READY;
 144
 145   __HAL_UNLOCK(hrng);
 146
 147   /* Return function status */
 148   return HAL_OK;
 149 }
 150
 151 /**
 152   * @brief  DeInitializes the RNG peripheral.
 153   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 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.
 185   * @retval None
 186   */
 187 __weak void HAL_RNG_MspInit(RNG_HandleTypeDef *hrng)
 188 {
 189   /* NOTE : This function should not be modified. When the callback is needed,
 190             function HAL_RNG_MspInit must be implemented in the user file.
 191    */
 192 }
 193
 194 /**
 195   * @brief  DeInitializes the RNG MSP.
 196   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 197   * @retval None
 198   */
 199 __weak void HAL_RNG_MspDeInit(RNG_HandleTypeDef *hrng)
 200 {
 201   /* NOTE : This function should not be modified. When the callback is needed,
 202             function HAL_RNG_MspDeInit must be implemented in the user file.
 203    */
 204 }
 205
 206 /**
 207   * @}
 208   */
 209
 210 /** @addtogroup RNG_Exported_Functions_Group2
 211  *  @brief   Peripheral Control functions
 212  *
 213 @verbatim
 214  ===============================================================================
 215                       ##### Peripheral Control functions #####
 216  ===============================================================================
 217     [..]  This section provides functions allowing to:
 218       (+) Get the 32 bit Random number
 219       (+) Get the 32 bit Random number with interrupt enabled
 220       (+) Handle RNG interrupt request
 221
 222
 223 @endverbatim
 224   * @{
 225   */
 226
 227 /**
 228   * @brief  Generates a 32-bit random number.
 229   * @note   Each time the random number data is read the RNG_FLAG_DRDY flag
 230   *         is automatically cleared.
 231   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 232   * @param  random32bit: pointer to generated random number variable if successful.
 233   * @retval HAL status
 234   */
 235
 236 HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber(RNG_HandleTypeDef *hrng, uint32_t *random32bit)
 237 {
 238   uint32_t tickstart = 0;
 239   HAL_StatusTypeDef status = HAL_OK;
 240
 241   /* Process Locked */
 242   __HAL_LOCK(hrng);
 243
 244   /* Check RNG peripheral state */
 245   if(hrng->State == HAL_RNG_STATE_READY)
 246   {
 247     /* Change RNG peripheral state */
 248     hrng->State = HAL_RNG_STATE_BUSY;
 249
 250     /* Get tick */
 251     tickstart = HAL_GetTick();
 252
 253     /* Check if data register contains valid random data */
 254     while(__HAL_RNG_GET_FLAG(hrng, RNG_FLAG_DRDY) == RESET)
 255     {
 256       if((HAL_GetTick() - tickstart ) > RNG_TIMEOUT_VALUE)
 257       {
 258         hrng->State = HAL_RNG_STATE_ERROR;
 259
 260         /* Process Unlocked */
 261         __HAL_UNLOCK(hrng);
 262
 263         return HAL_TIMEOUT;
 264       }
 265     }
 266
 267     /* Get a 32bit Random number */
 268     hrng->RandomNumber = hrng->Instance->DR;
 269     *random32bit = hrng->RandomNumber;
 270
 271     hrng->State = HAL_RNG_STATE_READY;
 272   }
 273   else
 274   {
 275     status = HAL_ERROR;
 276   }
 277
 278   /* Process Unlocked */
 279   __HAL_UNLOCK(hrng);
 280
 281   return status;
 282 }
 283
 284 /**
 285   * @brief  Generates a 32-bit random number in interrupt mode.
 286   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 287   * @retval HAL status
 288   */
 289 HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber_IT(RNG_HandleTypeDef *hrng)
 290 {
 291   HAL_StatusTypeDef status = HAL_OK;
 292
 293   /* Process Locked */
 294   __HAL_LOCK(hrng);
 295
 296   /* Check RNG peripheral state */
 297   if(hrng->State == HAL_RNG_STATE_READY)
 298   {
 299     /* Change RNG peripheral state */
 300     hrng->State = HAL_RNG_STATE_BUSY;
 301
 302     /* Process Unlocked */
 303     __HAL_UNLOCK(hrng);
 304
 305     /* Enable the RNG Interrupts: Data Ready, Clock error, Seed error */
 306     __HAL_RNG_ENABLE_IT(hrng);
 307   }
 308   else
 309   {
 310     /* Process Unlocked */
 311     __HAL_UNLOCK(hrng);
 312
 313     status = HAL_ERROR;
 314   }
 315
 316   return status;
 317 }
 318
 319 /**
 320   * @brief  Handles RNG interrupt request.
 321   * @note   In the case of a clock error, the RNG is no more able to generate
 322   *         random numbers because the PLL48CLK clock is not correct. User has
 323   *         to check that the clock controller is correctly configured to provide
 324   *         the RNG clock and clear the CEIS bit using __HAL_RNG_CLEAR_IT().
 325   *         The clock error has no impact on the previously generated
 326   *         random numbers, and the RNG_DR register contents can be used.
 327   * @note   In the case of a seed error, the generation of random numbers is
 328   *         interrupted as long as the SECS bit is '1'. If a number is
 329   *         available in the RNG_DR register, it must not be used because it may
 330   *         not have enough entropy. In this case, it is recommended to clear the
 331   *         SEIS bit using __HAL_RNG_CLEAR_IT(), then disable and enable
 332   *         the RNG peripheral to reinitialize and restart the RNG.
 333   * @note   User-written HAL_RNG_ErrorCallback() API is called once whether SEIS
 334   *         or CEIS are set.
 335   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 336   * @retval None
 337
 338   */
 339 void HAL_RNG_IRQHandler(RNG_HandleTypeDef *hrng)
 340 {
 341   /* RNG clock error interrupt occurred */
 342   if((__HAL_RNG_GET_IT(hrng, RNG_IT_CEI) != RESET) ||  (__HAL_RNG_GET_IT(hrng, RNG_IT_SEI) != RESET))
 343   {
 344     /* Change RNG peripheral state */
 345     hrng->State = HAL_RNG_STATE_ERROR;
 346
 347     HAL_RNG_ErrorCallback(hrng);
 348
 349     /* Clear the clock error flag */
 350     __HAL_RNG_CLEAR_IT(hrng, RNG_IT_CEI|RNG_IT_SEI);
 351
 352   }
 353
 354   /* Check RNG data ready interrupt occurred */
 355   if(__HAL_RNG_GET_IT(hrng, RNG_IT_DRDY) != RESET)
 356   {
 357     /* Generate random number once, so disable the IT */
 358     __HAL_RNG_DISABLE_IT(hrng);
 359
 360     /* Get the 32bit Random number (DRDY flag automatically cleared) */
 361     hrng->RandomNumber = hrng->Instance->DR;
 362
 363     if(hrng->State != HAL_RNG_STATE_ERROR)
 364     {
 365       /* Change RNG peripheral state */
 366       hrng->State = HAL_RNG_STATE_READY;
 367
 368       /* Data Ready callback */
 369       HAL_RNG_ReadyDataCallback(hrng, hrng->RandomNumber);
 370     }
 371   }
 372 }
 373
 374 /**
 375   * @brief  return generated random number in polling mode (Obsolete).
 376   *         Use HAL_RNG_GenerateRandomNumber() API instead.
 377   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
 378   *                the configuration information for RNG.
 379   * @retval random value
 380   */
 381 uint32_t HAL_RNG_GetRandomNumber(RNG_HandleTypeDef *hrng)
 382 {
 383   if(HAL_RNG_GenerateRandomNumber(hrng, &(hrng->RandomNumber)) == HAL_OK)
 384   {
 385     return hrng->RandomNumber;
 386   }
 387   else
 388   {
 389     return 0;
 390   }
 391 }
 392
 393
 394 /**
 395   * @brief  Returns a 32-bit random number with interrupt enabled (Obsolete),
 396   *         Use HAL_RNG_GenerateRandomNumber_IT() API instead.
 397   * @param  hrng: RNG handle
 398   * @retval 32-bit random number
 399   */
 400 uint32_t HAL_RNG_GetRandomNumber_IT(RNG_HandleTypeDef *hrng)
 401 {
 402   uint32_t random32bit = 0;
 403
 404   /* Process locked */
 405   __HAL_LOCK(hrng);
 406
 407   /* Change RNG peripheral state */
 408   hrng->State = HAL_RNG_STATE_BUSY;
 409
 410   /* Get a 32bit Random number */
 411   random32bit = hrng->Instance->DR;
 412
 413   /* Enable the RNG Interrupts: Data Ready, Clock error, Seed error */
 414   __HAL_RNG_ENABLE_IT(hrng);
 415
 416   /* Return the 32 bit random number */
 417   return random32bit;
 418 }
 419
 420
 421
 422 /**
 423   * @brief  Read latest generated random number.
 424   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 425   * @retval random value
 426   */
 427 uint32_t HAL_RNG_ReadLastRandomNumber(RNG_HandleTypeDef *hrng)
 428 {
 429   return(hrng->RandomNumber);
 430 }
 431
 432 /**
 433   * @brief  Data Ready callback in non-blocking mode.
 434   * @param  hrng: pointer to a RNG_HandleTypeDef structure..
 435   * @param  random32bit: generated random value
 436   * @retval None
 437   */
 438 __weak void HAL_RNG_ReadyDataCallback(RNG_HandleTypeDef *hrng, uint32_t random32bit)
 439 {
 440   /* NOTE : This function should not be modified. When the callback is needed,
 441             function HAL_RNG_ReadyDataCallback must be implemented in the user file.
 442    */
 443 }
 444
 445 /**
 446   * @brief  RNG error callbacks.
 447   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 448   * @retval None
 449   */
 450 __weak void HAL_RNG_ErrorCallback(RNG_HandleTypeDef *hrng)
 451 {
 452   /* NOTE : This function should not be modified. When the callback is needed,
 453             function HAL_RNG_ErrorCallback must be implemented in the user file.
 454    */
 455 }
 456
 457 /**
 458   * @}
 459   */
 460
 461 /** @addtogroup RNG_Exported_Functions_Group3
 462  *  @brief    Peripheral State functions.
 463  *
 464 @verbatim
 465  ===============================================================================
 466                       ##### Peripheral State functions #####
 467  ===============================================================================
 468     [..]
 469     This subsection permits to get in run-time the status of the peripheral.
 470
 471 @endverbatim
 472   * @{
 473   */
 474
 475 /**
 476   * @brief  Returns the RNG state.
 477   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
 478   * @retval HAL state
 479   */
 480 HAL_RNG_StateTypeDef HAL_RNG_GetState(RNG_HandleTypeDef *hrng)
 481 {
 482   return hrng->State;
 483 }
 484
 485 /**
 486   * @}
 487   */
 488
 489 /**
 490   * @}
 491   */
 492
 493 #endif /*  if defined (STM32L052xx) || defined (STM32L053xx) || defined (STM32L062xx) ||  defined (STM32L063xx) || \
 494            defined (STM32L072xx) || defined (STM32L073xx) || defined (STM32L082xx) ||  defined (STM32L083xx)         */
 495
 496 #endif /* HAL_RNG_MODULE_ENABLED */
 497
 498 /**
 499   * @}
 500   */
 501
 502 /**
 503   * @}
 504   */
 505
 506 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/
 507