stm32l4xx_hal_rng.c

00001 /**
00002   ******************************************************************************
00003   * @file    stm32l4xx_hal_rng.c
00004   * @author  MCD Application Team
00005   * @version V1.5.1
00006   * @date    31-May-2016
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) 2016 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   /* Prevent unused argument(s) compilation warning */
00193   UNUSED(hrng);
00194 
00195   /* NOTE : This function should not be modified. When the callback is needed,
00196             function HAL_RNG_MspInit must be implemented in the user file.
00197    */
00198 }
00199 
00200 /**
00201   * @brief  DeInitialize the RNG MSP.
00202   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00203   * @retval None
00204   */
00205 __weak void HAL_RNG_MspDeInit(RNG_HandleTypeDef *hrng)
00206 {
00207   /* Prevent unused argument(s) compilation warning */
00208   UNUSED(hrng);
00209 
00210   /* NOTE : This function should not be modified. When the callback is needed,
00211             function HAL_RNG_MspDeInit must be implemented in the user file.
00212    */
00213 }
00214 
00215 /**
00216   * @}
00217   */
00218 
00219 /** @addtogroup RNG_Exported_Functions_Group2
00220  *  @brief    Management functions. 
00221  *
00222 @verbatim   
00223  ===============================================================================
00224                       ##### Peripheral Control functions #####
00225  ===============================================================================  
00226     [..]  This section provides functions allowing to:
00227       (+) Get the 32 bit Random number
00228       (+) Get the 32 bit Random number with interrupt enabled
00229       (+) Handle RNG interrupt request 
00230 
00231 @endverbatim
00232   * @{
00233   */
00234 
00235 /**
00236   * @brief  Generate a 32-bit random number.
00237   * @note   Each time the random number data is read the RNG_FLAG_DRDY flag 
00238   *         is automatically cleared.
00239   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00240   * @param  random32bit: pointer to generated random number variable if successful.
00241   * @retval HAL status
00242   */
00243 
00244 HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber(RNG_HandleTypeDef *hrng, uint32_t *random32bit)
00245 {
00246   uint32_t tickstart = 0;    
00247   HAL_StatusTypeDef status = HAL_OK;
00248 
00249   /* Process Locked */
00250   __HAL_LOCK(hrng); 
00251   
00252   /* Check RNS peripheral state */
00253   if(hrng->State == HAL_RNG_STATE_READY)
00254   {
00255     /* Change RNG peripheral state */  
00256     hrng->State = HAL_RNG_STATE_BUSY;  
00257 
00258     /* Get tick */
00259     tickstart = HAL_GetTick();
00260   
00261     /* Check if data register contains valid random data */
00262     while(__HAL_RNG_GET_FLAG(hrng, RNG_FLAG_DRDY) == RESET)
00263     {
00264       if((HAL_GetTick() - tickstart ) > RNG_TIMEOUT_VALUE)
00265       {    
00266         hrng->State = HAL_RNG_STATE_ERROR;
00267 
00268         /* Process Unlocked */
00269         __HAL_UNLOCK(hrng);
00270       
00271         return HAL_TIMEOUT;
00272       } 
00273     }
00274   
00275     /* Get a 32bit Random number */
00276     hrng->RandomNumber = hrng->Instance->DR;
00277     *random32bit = hrng->RandomNumber;
00278   
00279     hrng->State = HAL_RNG_STATE_READY;
00280   }
00281   else
00282   {
00283     status = HAL_ERROR;
00284   }
00285   
00286   /* Process Unlocked */
00287   __HAL_UNLOCK(hrng);
00288 
00289   return status;
00290 }
00291 
00292 /**
00293   * @brief  Generate a 32-bit random number in interrupt mode.
00294   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00295   * @retval HAL status
00296   */
00297 HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber_IT(RNG_HandleTypeDef *hrng)
00298 {
00299   HAL_StatusTypeDef status = HAL_OK;
00300   
00301   /* Process Locked */
00302   __HAL_LOCK(hrng);
00303   
00304   /* Check RNG peripheral state */
00305   if(hrng->State == HAL_RNG_STATE_READY)
00306   {
00307     /* Change RNG peripheral state */  
00308     hrng->State = HAL_RNG_STATE_BUSY;  
00309   
00310     /* Process Unlocked */
00311     __HAL_UNLOCK(hrng);
00312     
00313     /* Enable the RNG Interrupts: Data Ready, Clock error, Seed error */ 
00314     __HAL_RNG_ENABLE_IT(hrng);
00315   }
00316   else
00317   {
00318     /* Process Unlocked */
00319     __HAL_UNLOCK(hrng);
00320     
00321     status = HAL_ERROR;
00322   }
00323   
00324   return status;
00325 }
00326 
00327 /**
00328   * @brief  Handle RNG interrupt request.
00329   * @note   In the case of a clock error, the RNG is no more able to generate 
00330   *         random numbers because the PLL48CLK clock is not correct. User has 
00331   *         to check that the clock controller is correctly configured to provide
00332   *         the RNG clock and clear the CEIS bit using __HAL_RNG_CLEAR_IT(). 
00333   *         The clock error has no impact on the previously generated 
00334   *         random numbers, and the RNG_DR register contents can be used.
00335   * @note   In the case of a seed error, the generation of random numbers is 
00336   *         interrupted as long as the SECS bit is '1'. If a number is 
00337   *         available in the RNG_DR register, it must not be used because it may 
00338   *         not have enough entropy. In this case, it is recommended to clear the 
00339   *         SEIS bit using __HAL_RNG_CLEAR_IT(), then disable and enable 
00340   *         the RNG peripheral to reinitialize and restart the RNG.
00341   * @note   User-written HAL_RNG_ErrorCallback() API is called once whether SEIS
00342   *         or CEIS are set.  
00343   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00344   * @retval None
00345 
00346   */
00347 void HAL_RNG_IRQHandler(RNG_HandleTypeDef *hrng)
00348 {
00349   /* RNG clock error interrupt occurred */
00350   if((__HAL_RNG_GET_IT(hrng, RNG_IT_CEI) != RESET) ||  (__HAL_RNG_GET_IT(hrng, RNG_IT_SEI) != RESET))
00351   { 
00352     /* Change RNG peripheral state */
00353     hrng->State = HAL_RNG_STATE_ERROR;
00354   
00355     HAL_RNG_ErrorCallback(hrng);
00356     
00357     /* Clear the clock error flag */
00358     __HAL_RNG_CLEAR_IT(hrng, RNG_IT_CEI|RNG_IT_SEI);
00359     
00360   }
00361   
00362   /* Check RNG data ready interrupt occurred */    
00363   if(__HAL_RNG_GET_IT(hrng, RNG_IT_DRDY) != RESET)
00364   {
00365     /* Generate random number once, so disable the IT */
00366     __HAL_RNG_DISABLE_IT(hrng);
00367     
00368     /* Get the 32bit Random number (DRDY flag automatically cleared) */ 
00369     hrng->RandomNumber = hrng->Instance->DR;
00370     
00371     if(hrng->State != HAL_RNG_STATE_ERROR)
00372     {
00373       /* Change RNG peripheral state */
00374       hrng->State = HAL_RNG_STATE_READY; 
00375       
00376       /* Data Ready callback */ 
00377       HAL_RNG_ReadyDataCallback(hrng, hrng->RandomNumber);
00378     } 
00379   }
00380 } 
00381 
00382 /**
00383   * @brief  Return generated random number in polling mode (Obsolete).
00384   * @note   Use HAL_RNG_GenerateRandomNumber() API instead.
00385   * @param  hrng: pointer to a RNG_HandleTypeDef structure that contains
00386   *                the configuration information for RNG.
00387   * @retval random value
00388   */
00389 uint32_t HAL_RNG_GetRandomNumber(RNG_HandleTypeDef *hrng)
00390 {
00391   if(HAL_RNG_GenerateRandomNumber(hrng, &(hrng->RandomNumber)) == HAL_OK)
00392   {
00393     return hrng->RandomNumber; 
00394   }
00395   else
00396   {
00397     return 0;
00398   }
00399 }
00400 
00401 
00402 /**
00403   * @brief  Return a 32-bit random number with interrupt enabled (Obsolete).
00404   * @note   Use HAL_RNG_GenerateRandomNumber_IT() API instead.
00405   * @param  hrng: RNG handle
00406   * @retval 32-bit random number
00407   */
00408 uint32_t HAL_RNG_GetRandomNumber_IT(RNG_HandleTypeDef *hrng)
00409 {
00410   uint32_t random32bit = 0;
00411   
00412   /* Process locked */
00413   __HAL_LOCK(hrng);
00414   
00415   /* Change RNG peripheral state */  
00416   hrng->State = HAL_RNG_STATE_BUSY;  
00417   
00418   /* Get a 32bit Random number */ 
00419   random32bit = hrng->Instance->DR;
00420   
00421   /* Enable the RNG Interrupts: Data Ready, Clock error, Seed error */ 
00422   __HAL_RNG_ENABLE_IT(hrng); 
00423   
00424   /* Return the 32 bit random number */   
00425   return random32bit;
00426 }
00427 
00428 
00429 
00430 /**
00431   * @brief  Read latest generated random number. 
00432   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00433   * @retval random value
00434   */
00435 uint32_t HAL_RNG_ReadLastRandomNumber(RNG_HandleTypeDef *hrng)
00436 {
00437   return(hrng->RandomNumber);
00438 }
00439 
00440 /**
00441   * @brief  Data Ready callback in non-blocking mode. 
00442   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00443   * @param  random32bit: generated random value
00444   * @retval None
00445   */
00446 __weak void HAL_RNG_ReadyDataCallback(RNG_HandleTypeDef *hrng, uint32_t random32bit)
00447 {
00448   /* Prevent unused argument(s) compilation warning */
00449   UNUSED(hrng);
00450   UNUSED(random32bit);
00451 
00452   /* NOTE : This function should not be modified. When the callback is needed,
00453             function HAL_RNG_ReadyDataCallback must be implemented in the user file.
00454    */
00455 }
00456 
00457 /**
00458   * @brief  RNG error callback.
00459   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00460   * @retval None
00461   */
00462 __weak void HAL_RNG_ErrorCallback(RNG_HandleTypeDef *hrng)
00463 {
00464   /* Prevent unused argument(s) compilation warning */
00465   UNUSED(hrng);
00466 
00467   /* NOTE : This function should not be modified. When the callback is needed,
00468             function HAL_RNG_ErrorCallback must be implemented in the user file.
00469    */
00470 }
00471  
00472 /**
00473   * @}
00474   */
00475 
00476 /** @addtogroup RNG_Exported_Functions_Group3
00477  *  @brief    Peripheral State functions. 
00478  *
00479 @verbatim   
00480  ===============================================================================
00481                       ##### Peripheral State functions #####
00482  ===============================================================================  
00483     [..]
00484     This subsection permits to get in run-time the status of the peripheral.
00485 
00486 @endverbatim
00487   * @{
00488   */
00489 
00490 /**
00491   * @brief  Return the RNG handle state.
00492   * @param  hrng: pointer to a RNG_HandleTypeDef structure.
00493   * @retval HAL state
00494   */
00495 HAL_RNG_StateTypeDef HAL_RNG_GetState(RNG_HandleTypeDef *hrng)
00496 {
00497   /* Return RNG handle state */
00498   return hrng->State;
00499 }
00500 
00501 /**
00502   * @}
00503   */
00504 
00505 /**
00506   * @}
00507   */
00508 
00509 
00510 #endif /* HAL_RNG_MODULE_ENABLED */
00511 /**
00512   * @}
00513   */
00514 
00515 /**
00516   * @}
00517   */
00518 
00519 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/