stm32l4xx_hal_rng.c

00001 /**
00002   ******************************************************************************
00003   * @file    stm32l4xx_hal_rng.c
00004   * @author  MCD Application Team
00005   * @version V1.1.0
00006   * @date    16-September-2015
00007   * @brief   RNG HAL module driver.
00008   *          This file provides firmware functions to manage the following 
00009   *          functionalities of the Random Number Generator (RNG) peripheral:
00010   *           + Initialization/de-initialization functions
00011   *           + Peripheral Control functions 
00012   *           + Peripheral State functions
00013   *         
00014   @verbatim
00015   ==============================================================================
00016                      ##### How to use this driver #####
00017   ==============================================================================
00018   [..]
00019       The RNG HAL driver can be used as follows:
00020 
00021       (#) Enable the RNG controller clock using __HAL_RCC_RNG_CLK_ENABLE() macro 
00022           in HAL_RNG_MspInit().
00023       (#) Activate the RNG peripheral using HAL_RNG_Init() function.
00024       (#) Wait until the 32-bit Random Number Generator contains a valid 
00025           random data using (polling/interrupt) mode.   
00026       (#) Get the 32 bit random number using HAL_RNG_GenerateRandomNumber() function.
00027   
00028   @endverbatim
00029   ******************************************************************************
00030   * @attention
00031   *
00032   * <h2><center>&copy; COPYRIGHT(c) 2015 STMicroelectronics</center></h2>
00033   *
00034   * Redistribution and use in source and binary forms, with or without modification,
00035   * are permitted provided that the following conditions are met:
00036   *   1. Redistributions of source code must retain the above copyright notice,
00037   *      this list of conditions and the following disclaimer.
00038   *   2. Redistributions in binary form must reproduce the above copyright notice,
00039   *      this list of conditions and the following disclaimer in the documentation
00040   *      and/or other materials provided with the distribution.
00041   *   3. Neither the name of STMicroelectronics nor the names of its contributors
00042   *      may be used to endorse or promote products derived from this software
00043   *      without specific prior written permission.
00044   *
00045   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00046   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00047   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00048   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
00049   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00050   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00051   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00052   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00053   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00054   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00055   *
00056   ******************************************************************************
00057   */ 
00058 
00059 /* Includes ------------------------------------------------------------------*/
00060 #include "stm32l4xx_hal.h"
00061 
00062 /** @addtogroup STM32L4xx_HAL_Driver
00063   * @{
00064   */
00065 
00066 /** @defgroup RNG RNG
00067   * @brief RNG HAL module driver.
00068   * @{
00069   */
00070 
00071 #ifdef HAL_RNG_MODULE_ENABLED
00072 
00073 
00074 
00075 /* Private types -------------------------------------------------------------*/
00076 /* Private defines -----------------------------------------------------------*/
00077 /** @defgroup RNG_Private_Constants RNG_Private_Constants
00078   * @{
00079   */
00080 #define RNG_TIMEOUT_VALUE     2
00081 /**
00082   * @}
00083   */ 
00084 
00085 /* Private macros ------------------------------------------------------------*/
00086 /* Private variables ---------------------------------------------------------*/
00087 /* Private function prototypes -----------------------------------------------*/
00088 /* Private functions ---------------------------------------------------------*/
00089 /* Exported functions --------------------------------------------------------*/
00090 
00091 /** @addtogroup RNG_Exported_Functions
00092   * @{
00093   */
00094 
00095 /** @addtogroup RNG_Exported_Functions_Group1
00096  *  @brief   Initialization and de-initialization functions
00097  *
00098 @verbatim
00099  ===============================================================================
00100           ##### Initialization and de-initialization functions #####
00101  ===============================================================================
00102     [..]  This section provides functions allowing to:
00103       (+) Initialize the RNG according to the specified parameters 
00104           in the RNG_InitTypeDef and create the associated handle
00105       (+) DeInitialize the RNG peripheral
00106       (+) Initialize the RNG MSP (MCU Specific Package)
00107       (+) DeInitialize the RNG MSP 
00108  
00109 @endverbatim
00110   * @{
00111   */
00112 
00113 /**
00114   * @brief  Initialize the RNG peripheral and initialize the associated handle.
00115   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00116   * @retval HAL status
00117   */
00118 HAL_StatusTypeDef HAL_RNG_Init(RNG_HandleTypeDef *hrng)
00119 { 
00120   /* Check the RNG handle allocation */
00121   if(hrng == NULL)
00122   {
00123     return HAL_ERROR;
00124   }
00125   
00126   assert_param(IS_RNG_ALL_INSTANCE(hrng->Instance)); 
00127   
00128   __HAL_LOCK(hrng);
00129   
00130   if(hrng->State == HAL_RNG_STATE_RESET)
00131   {  
00132     /* Allocate lock resource and initialize it */
00133     hrng->Lock = HAL_UNLOCKED;
00134 
00135     /* Init the low level hardware */
00136     HAL_RNG_MspInit(hrng);
00137   }
00138   
00139   /* Change RNG peripheral state */
00140   hrng->State = HAL_RNG_STATE_BUSY;
00141 
00142   /* Enable the RNG Peripheral */
00143   __HAL_RNG_ENABLE(hrng);
00144 
00145   /* Initialize the RNG state */
00146   hrng->State = HAL_RNG_STATE_READY;
00147   
00148   __HAL_UNLOCK(hrng);
00149   
00150   /* Return function status */
00151   return HAL_OK;
00152 }
00153 
00154 /**
00155   * @brief  DeInitialize the RNG peripheral. 
00156   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00157   * @retval HAL status
00158   */
00159 HAL_StatusTypeDef HAL_RNG_DeInit(RNG_HandleTypeDef *hrng)
00160 { 
00161   /* Check the RNG handle allocation */
00162   if(hrng == NULL)
00163   {
00164     return HAL_ERROR;
00165   }
00166   /* Disable the RNG Peripheral */
00167   CLEAR_BIT(hrng->Instance->CR, RNG_CR_IE | RNG_CR_RNGEN);
00168   
00169   /* Clear RNG interrupt status flags */
00170   CLEAR_BIT(hrng->Instance->SR, RNG_SR_CEIS | RNG_SR_SEIS);
00171   
00172   /* DeInit the low level hardware */
00173   HAL_RNG_MspDeInit(hrng);
00174   
00175   /* Update the RNG state */
00176   hrng->State = HAL_RNG_STATE_RESET; 
00177 
00178   /* Release Lock */
00179   __HAL_UNLOCK(hrng);
00180   
00181   /* Return the function status */
00182   return HAL_OK;
00183 }
00184 
00185 /**
00186   * @brief  Initialize the RNG MSP.
00187   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00188   * @retval None
00189   */
00190 __weak void HAL_RNG_MspInit(RNG_HandleTypeDef *hrng)
00191 {
00192   /* NOTE : This function should not be modified. When the callback is needed,
00193             function HAL_RNG_MspInit must be implemented in the user file.
00194    */
00195 }
00196 
00197 /**
00198   * @brief  DeInitialize the RNG MSP.
00199   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00200   * @retval None
00201   */
00202 __weak void HAL_RNG_MspDeInit(RNG_HandleTypeDef *hrng)
00203 {
00204   /* NOTE : This function should not be modified. When the callback is needed,
00205             function HAL_RNG_MspDeInit must be implemented in the user file.
00206    */
00207 }
00208 
00209 /**
00210   * @}
00211   */
00212 
00213 /** @addtogroup RNG_Exported_Functions_Group2
00214  *  @brief    Management functions. 
00215  *
00216 @verbatim   
00217  ===============================================================================
00218                       ##### Peripheral Control functions #####
00219  ===============================================================================  
00220     [..]  This section provides functions allowing to:
00221       (+) Get the 32 bit Random number
00222       (+) Get the 32 bit Random number with interrupt enabled
00223       (+) Handle RNG interrupt request 
00224 
00225 @endverbatim
00226   * @{
00227   */
00228 
00229 /**
00230   * @brief  Generate a 32-bit random number.
00231   * @note   Each time the random number data is read the RNG_FLAG_DRDY flag 
00232   *         is automatically cleared.
00233   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00234   * @param  random32bit: pointer to generated random number variable if successful.
00235   * @retval HAL status
00236   */
00237 
00238 HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber(RNG_HandleTypeDef *hrng, uint32_t *random32bit)
00239 {
00240   uint32_t tickstart = 0;    
00241   HAL_StatusTypeDef status = HAL_OK;
00242 
00243   /* Process Locked */
00244   __HAL_LOCK(hrng); 
00245   
00246   /* Check RNS peripheral state */
00247   if(hrng->State == HAL_RNG_STATE_READY)
00248   {
00249     /* Change RNG peripheral state */  
00250     hrng->State = HAL_RNG_STATE_BUSY;  
00251 
00252     /* Get tick */
00253     tickstart = HAL_GetTick();
00254   
00255     /* Check if data register contains valid random data */
00256     while(__HAL_RNG_GET_FLAG(hrng, RNG_FLAG_DRDY) == RESET)
00257     {
00258       if((HAL_GetTick() - tickstart ) > RNG_TIMEOUT_VALUE)
00259       {    
00260         hrng->State = HAL_RNG_STATE_ERROR;
00261 
00262         /* Process Unlocked */
00263         __HAL_UNLOCK(hrng);
00264       
00265         return HAL_TIMEOUT;
00266       } 
00267     }
00268   
00269     /* Get a 32bit Random number */
00270     hrng->RandomNumber = hrng->Instance->DR;
00271     *random32bit = hrng->RandomNumber;
00272   
00273     hrng->State = HAL_RNG_STATE_READY;
00274   }
00275   else
00276   {
00277     status = HAL_ERROR;
00278   }
00279   
00280   /* Process Unlocked */
00281   __HAL_UNLOCK(hrng);
00282 
00283   return status;
00284 }
00285 
00286 /**
00287   * @brief  Generate a 32-bit random number in interrupt mode.
00288   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00289   * @retval HAL status
00290   */
00291 HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber_IT(RNG_HandleTypeDef *hrng)
00292 {
00293   HAL_StatusTypeDef status = HAL_OK;
00294   
00295   /* Process Locked */
00296   __HAL_LOCK(hrng);
00297   
00298   /* Check RNG peripheral state */
00299   if(hrng->State == HAL_RNG_STATE_READY)
00300   {
00301     /* Change RNG peripheral state */  
00302     hrng->State = HAL_RNG_STATE_BUSY;  
00303   
00304     /* Process Unlocked */
00305     __HAL_UNLOCK(hrng);
00306     
00307     /* Enable the RNG Interrupts: Data Ready, Clock error, Seed error */ 
00308     __HAL_RNG_ENABLE_IT(hrng);
00309   }
00310   else
00311   {
00312     /* Process Unlocked */
00313     __HAL_UNLOCK(hrng);
00314     
00315     status = HAL_ERROR;
00316   }
00317   
00318   return status;
00319 }
00320 
00321 /**
00322   * @brief  Handle RNG interrupt request.
00323   * @note   In the case of a clock error, the RNG is no more able to generate 
00324   *         random numbers because the PLL48CLK clock is not correct. User has 
00325   *         to check that the clock controller is correctly configured to provide
00326   *         the RNG clock and clear the CEIS bit using __HAL_RNG_CLEAR_IT(). 
00327   *         The clock error has no impact on the previously generated 
00328   *         random numbers, and the RNG_DR register contents can be used.
00329   * @note   In the case of a seed error, the generation of random numbers is 
00330   *         interrupted as long as the SECS bit is '1'. If a number is 
00331   *         available in the RNG_DR register, it must not be used because it may 
00332   *         not have enough entropy. In this case, it is recommended to clear the 
00333   *         SEIS bit using __HAL_RNG_CLEAR_IT(), then disable and enable 
00334   *         the RNG peripheral to reinitialize and restart the RNG.
00335   * @note   User-written HAL_RNG_ErrorCallback() API is called once whether SEIS
00336   *         or CEIS are set.  
00337   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00338   * @retval None
00339 
00340   */
00341 void HAL_RNG_IRQHandler(RNG_HandleTypeDef *hrng)
00342 {
00343   /* RNG clock error interrupt occurred */
00344   if((__HAL_RNG_GET_IT(hrng, RNG_IT_CEI) != RESET) ||  (__HAL_RNG_GET_IT(hrng, RNG_IT_SEI) != RESET))
00345   { 
00346     /* Change RNG peripheral state */
00347     hrng->State = HAL_RNG_STATE_ERROR;
00348   
00349     HAL_RNG_ErrorCallback(hrng);
00350     
00351     /* Clear the clock error flag */
00352     __HAL_RNG_CLEAR_IT(hrng, RNG_IT_CEI|RNG_IT_SEI);
00353     
00354   }
00355   
00356   /* Check RNG data ready interrupt occurred */    
00357   if(__HAL_RNG_GET_IT(hrng, RNG_IT_DRDY) != RESET)
00358   {
00359     /* Generate random number once, so disable the IT */
00360     __HAL_RNG_DISABLE_IT(hrng);
00361     
00362     /* Get the 32bit Random number (DRDY flag automatically cleared) */ 
00363     hrng->RandomNumber = hrng->Instance->DR;
00364     
00365     if(hrng->State != HAL_RNG_STATE_ERROR)
00366     {
00367       /* Change RNG peripheral state */
00368       hrng->State = HAL_RNG_STATE_READY; 
00369       
00370       /* Data Ready callback */ 
00371       HAL_RNG_ReadyDataCallback(hrng, hrng->RandomNumber);
00372     } 
00373   }
00374 } 
00375 
00376 /**
00377   * @brief  Return generated random number in polling mode (Obsolete).
00378   * @note   Use HAL_RNG_GenerateRandomNumber() API instead.
00379   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
00380   *                the configuration information for RNG.
00381   * @retval random value
00382   */
00383 uint32_t HAL_RNG_GetRandomNumber(RNG_HandleTypeDef *hrng)
00384 {
00385   if(HAL_RNG_GenerateRandomNumber(hrng, &(hrng->RandomNumber)) == HAL_OK)
00386   {
00387     return hrng->RandomNumber; 
00388   }
00389   else
00390   {
00391     return 0;
00392   }
00393 }
00394 
00395 
00396 /**
00397   * @brief  Return a 32-bit random number with interrupt enabled (Obsolete).
00398   * @note   Use HAL_RNG_GenerateRandomNumber_IT() API instead.
00399   * @param  hrng: RNG handle
00400   * @retval 32-bit random number
00401   */
00402 uint32_t HAL_RNG_GetRandomNumber_IT(RNG_HandleTypeDef *hrng)
00403 {
00404   uint32_t random32bit = 0;
00405   
00406   /* Process locked */
00407   __HAL_LOCK(hrng);
00408   
00409   /* Change RNG peripheral state */  
00410   hrng->State = HAL_RNG_STATE_BUSY;  
00411   
00412   /* Get a 32bit Random number */ 
00413   random32bit = hrng->Instance->DR;
00414   
00415   /* Enable the RNG Interrupts: Data Ready, Clock error, Seed error */ 
00416   __HAL_RNG_ENABLE_IT(hrng); 
00417   
00418   /* Return the 32 bit random number */   
00419   return random32bit;
00420 }
00421 
00422 
00423 
00424 /**
00425   * @brief  Read latest generated random number. 
00426   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00427   * @retval random value
00428   */
00429 uint32_t HAL_RNG_ReadLastRandomNumber(RNG_HandleTypeDef *hrng)
00430 {
00431   return(hrng->RandomNumber);
00432 }
00433 
00434 /**
00435   * @brief  Data Ready callback in non-blocking mode. 
00436   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00437   * @param  random32bit: generated random value
00438   * @retval None
00439   */
00440 __weak void HAL_RNG_ReadyDataCallback(RNG_HandleTypeDef *hrng, uint32_t random32bit)
00441 {
00442   /* NOTE : This function should not be modified. When the callback is needed,
00443             function HAL_RNG_ReadyDataCallback must be implemented in the user file.
00444    */
00445 }
00446 
00447 /**
00448   * @brief  RNG error callback.
00449   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00450   * @retval None
00451   */
00452 __weak void HAL_RNG_ErrorCallback(RNG_HandleTypeDef *hrng)
00453 {
00454   /* NOTE : This function should not be modified. When the callback is needed,
00455             function HAL_RNG_ErrorCallback must be implemented in the user file.
00456    */
00457 }
00458  
00459 /**
00460   * @}
00461   */
00462 
00463 /** @addtogroup RNG_Exported_Functions_Group3
00464  *  @brief    Peripheral State functions. 
00465  *
00466 @verbatim   
00467  ===============================================================================
00468                       ##### Peripheral State functions #####
00469  ===============================================================================  
00470     [..]
00471     This subsection permits to get in run-time the status of the peripheral.
00472 
00473 @endverbatim
00474   * @{
00475   */
00476 
00477 /**
00478   * @brief  Return the RNG handle state.
00479   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00480   * @retval HAL state
00481   */
00482 HAL_RNG_StateTypeDef HAL_RNG_GetState(RNG_HandleTypeDef *hrng)
00483 {
00484   /* Return RNG handle state */
00485   return hrng->State;
00486 }
00487 
00488 /**
00489   * @}
00490   */
00491 
00492 /**
00493   * @}
00494   */
00495 
00496 
00497 #endif /* HAL_RNG_MODULE_ENABLED */
00498 /**
00499   * @}
00500   */
00501 
00502 /**
00503   * @}
00504   */
00505 
00506 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/
00507