lib/main/STM32H7/Drivers/STM32H7xx_HAL_Driver/Src/stm32h7xx_hal_wwdg.c

   1 /**
   2   ******************************************************************************
   3   * @file    stm32h7xx_hal_wwdg.c
   4   * @author  MCD Application Team
   5   * @brief   WWDG HAL module driver.
   6   *          This file provides firmware functions to manage the following
   7   *          functionalities of the Window Watchdog (WWDG) peripheral:
   8   *           + Initialization and Configuration functions
   9   *           + IO operation functions
  10   @verbatim
  11   ==============================================================================
  12                       ##### WWDG Specific features #####
  13   ==============================================================================
  14   [..]
  15     Once enabled the WWDG generates a system reset on expiry of a programmed
  16     time period, unless the program refreshes the counter (T[6;0] downcounter)
  17     before reaching 0x3F value (i.e. a reset is generated when the counter
  18     value rolls down from 0x40 to 0x3F).
  19
  20     (+) An MCU reset is also generated if the counter value is refreshed
  21         before the counter has reached the refresh window value. This
  22         implies that the counter must be refreshed in a limited window.
  23     (+) Once enabled the WWDG cannot be disabled except by a system reset.
  24     (+) WWDGRST flag in RCC CSR register can be used to inform when a WWDG
  25         reset occurs.
  26     (+) The WWDG counter input clock is derived from the APB clock divided
  27         by a programmable prescaler.
  28     (+) WWDG clock (Hz) = PCLK1 / (4096 * Prescaler)
  29     (+) WWDG timeout (mS) = 1000 * (T[5;0] + 1) / WWDG clock (Hz)
  30         where T[5;0] are the lowest 6 bits of Counter.
  31     (+) WWDG Counter refresh is allowed between the following limits :
  32         (++) min time (mS) = 1000 * (Counter - Window) / WWDG clock
  33         (++) max time (mS) = 1000 * (Counter - 0x40) / WWDG clock
  34     (+) Typical values:
  35         (++) Counter min (T[5;0] = 0x00) @56MHz (PCLK1) with zero prescaler:
  36              max timeout before reset: approximately 73.14µs
  37         (++) Counter max (T[5;0] = 0x3F) @56MHz (PCLK1) with prescaler dividing by 128:
  38              max timeout before reset: approximately 599.18ms
  39
  40   ==============================================================================
  41                      ##### How to use this driver #####
  42   ==============================================================================
  43
  44     *** Common driver usage ***
  45     ===========================
  46
  47   [..]
  48     (+) Enable WWDG APB1 clock using __HAL_RCC_WWDG_CLK_ENABLE().
  49     (+) Set the WWDG prescaler, refresh window and counter value
  50         using HAL_WWDG_Init() function.
  51     (+) Start the WWDG using HAL_WWDG_Start() function.
  52         When the WWDG is enabled the counter value should be configured to
  53         a value greater than 0x40 to prevent generating an immediate reset.
  54     (+) Optionally you can enable the Early Wakeup Interrupt (EWI) which is
  55         generated when the counter reaches 0x40, and then start the WWDG using
  56         HAL_WWDG_Start_IT(). At EWI HAL_WWDG_WakeupCallback is executed and user can
  57         add his own code by customization of callback HAL_WWDG_WakeupCallback.
  58         Once enabled, EWI interrupt cannot be disabled except by a system reset.
  59     (+) Then the application program must refresh the WWDG counter at regular
  60         intervals during normal operation to prevent an MCU reset, using
  61         HAL_WWDG_Refresh() function. This operation must occur only when
  62         the counter is lower than the refresh window value already programmed.
  63
  64     *** Callback registration ***
  65     =============================
  66
  67   [..]
  68     The compilation define  USE_HAL_WWDG_REGISTER_CALLBACKS when set to 1 allows
  69     the user to configure dynamically the driver callbacks. Use Functions
  70     @ref HAL_WWDG_RegisterCallback() to register a user callback.
  71
  72     (+) Function @ref HAL_WWDG_RegisterCallback() allows to register following
  73         callbacks:
  74         (++) EwiCallback : callback for Early WakeUp Interrupt.
  75         (++) MspInitCallback : WWDG MspInit.
  76     This function takes as parameters the HAL peripheral handle, the Callback ID
  77     and a pointer to the user callback function.
  78
  79     (+) Use function @ref HAL_WWDG_UnRegisterCallback() to reset a callback to
  80     the default weak (surcharged) function. @ref HAL_WWDG_UnRegisterCallback()
  81     takes as parameters the HAL peripheral handle and the Callback ID.
  82     This function allows to reset following callbacks:
  83         (++) EwiCallback : callback for  Early WakeUp Interrupt.
  84         (++) MspInitCallback : WWDG MspInit.
  85
  86     [..]
  87     When calling @ref HAL_WWDG_Init function, callbacks are reset to the
  88     corresponding legacy weak (surcharged) functions:
  89     @ref HAL_WWDG_EarlyWakeupCallback() and HAL_WWDG_MspInit() only if they have
  90     not been registered before.
  91
  92     [..]
  93     When compilation define USE_HAL_WWDG_REGISTER_CALLBACKS is set to 0 or
  94     not defined, the callback registering feature is not available
  95     and weak (surcharged) callbacks are used.
  96
  97     *** WWDG HAL driver macros list ***
  98     ===================================
  99     [..]
 100       Below the list of most used macros in WWDG HAL driver.
 101       (+) __HAL_WWDG_ENABLE: Enable the WWDG peripheral
 102       (+) __HAL_WWDG_GET_FLAG: Get the selected WWDG's flag status
 103       (+) __HAL_WWDG_CLEAR_FLAG: Clear the WWDG's pending flags
 104       (+) __HAL_WWDG_ENABLE_IT: Enable the WWDG early wakeup interrupt
 105
 106   @endverbatim
 107   ******************************************************************************
 108   * @attention
 109   *
 110   * <h2><center>&copy; Copyright (c) 2017 STMicroelectronics.
 111   * All rights reserved.</center></h2>
 112   *
 113   * This software component is licensed by ST under BSD 3-Clause license,
 114   * the "License"; You may not use this file except in compliance with the
 115   * License. You may obtain a copy of the License at:
 116   *                        opensource.org/licenses/BSD-3-Clause
 117   *
 118   ******************************************************************************
 119   */
 120
 121 /* Includes ------------------------------------------------------------------*/
 122 #include "stm32h7xx_hal.h"
 123
 124 /** @addtogroup STM32H7xx_HAL_Driver
 125   * @{
 126   */
 127
 128 #ifdef HAL_WWDG_MODULE_ENABLED
 129 /** @defgroup WWDG WWDG
 130   * @brief WWDG HAL module driver.
 131   * @{
 132   */
 133
 134 /* Private typedef -----------------------------------------------------------*/
 135 /* Private define ------------------------------------------------------------*/
 136 /* Private macro -------------------------------------------------------------*/
 137 /* Private variables ---------------------------------------------------------*/
 138 /* Private function prototypes -----------------------------------------------*/
 139 /* Exported functions --------------------------------------------------------*/
 140
 141 /** @defgroup WWDG_Exported_Functions WWDG Exported Functions
 142   * @{
 143   */
 144
 145 /** @defgroup WWDG_Exported_Functions_Group1 Initialization and Configuration functions
 146   *  @brief    Initialization and Configuration functions.
 147   *
 148 @verbatim
 149   ==============================================================================
 150           ##### Initialization and Configuration functions #####
 151   ==============================================================================
 152   [..]
 153     This section provides functions allowing to:
 154       (+) Initialize and start the WWDG according to the specified parameters
 155           in the WWDG_InitTypeDef of associated handle.
 156       (+) Initialize the WWDG MSP.
 157
 158 @endverbatim
 159   * @{
 160   */
 161
 162 /**
 163   * @brief  Initialize the WWDG according to the specified.
 164   *         parameters in the WWDG_InitTypeDef of  associated handle.
 165   * @param  hwwdg  pointer to a WWDG_HandleTypeDef structure that contains
 166   *                the configuration information for the specified WWDG module.
 167   * @retval HAL status
 168   */
 169 HAL_StatusTypeDef HAL_WWDG_Init(WWDG_HandleTypeDef *hwwdg)
 170 {
 171   /* Check the WWDG handle allocation */
 172   if (hwwdg == NULL)
 173   {
 174     return HAL_ERROR;
 175   }
 176
 177   /* Check the parameters */
 178   assert_param(IS_WWDG_ALL_INSTANCE(hwwdg->Instance));
 179   assert_param(IS_WWDG_PRESCALER(hwwdg->Init.Prescaler));
 180   assert_param(IS_WWDG_WINDOW(hwwdg->Init.Window));
 181   assert_param(IS_WWDG_COUNTER(hwwdg->Init.Counter));
 182   assert_param(IS_WWDG_EWI_MODE(hwwdg->Init.EWIMode));
 183
 184 #if (USE_HAL_WWDG_REGISTER_CALLBACKS == 1)
 185   /* Reset Callback pointers */
 186   if (hwwdg->EwiCallback == NULL)
 187   {
 188     hwwdg->EwiCallback = HAL_WWDG_EarlyWakeupCallback;
 189   }
 190
 191   if (hwwdg->MspInitCallback == NULL)
 192   {
 193     hwwdg->MspInitCallback = HAL_WWDG_MspInit;
 194   }
 195
 196   /* Init the low level hardware */
 197   hwwdg->MspInitCallback(hwwdg);
 198 #else
 199   /* Init the low level hardware */
 200   HAL_WWDG_MspInit(hwwdg);
 201 #endif
 202
 203   /* Set WWDG Counter */
 204   WRITE_REG(hwwdg->Instance->CR, (WWDG_CR_WDGA | hwwdg->Init.Counter));
 205
 206   /* Set WWDG Prescaler and Window */
 207   WRITE_REG(hwwdg->Instance->CFR, (hwwdg->Init.EWIMode | hwwdg->Init.Prescaler | hwwdg->Init.Window));
 208
 209   /* Return function status */
 210   return HAL_OK;
 211 }
 212
 213
 214 /**
 215   * @brief  Initialize the WWDG MSP.
 216   * @param  hwwdg  pointer to a WWDG_HandleTypeDef structure that contains
 217   *                the configuration information for the specified WWDG module.
 218   * @note   When rewriting this function in user file, mechanism may be added
 219   *         to avoid multiple initialize when HAL_WWDG_Init function is called
 220   *         again to change parameters.
 221   * @retval None
 222   */
 223 __weak void HAL_WWDG_MspInit(WWDG_HandleTypeDef *hwwdg)
 224 {
 225   /* Prevent unused argument(s) compilation warning */
 226   UNUSED(hwwdg);
 227
 228   /* NOTE: This function should not be modified, when the callback is needed,
 229            the HAL_WWDG_MspInit could be implemented in the user file
 230    */
 231 }
 232
 233
 234 #if (USE_HAL_WWDG_REGISTER_CALLBACKS == 1)
 235 /**
 236   * @brief  Register a User WWDG Callback
 237   *         To be used instead of the weak (surcharged) predefined callback
 238   * @param  hwwdg WWDG handle
 239   * @param  CallbackID ID of the callback to be registered
 240   *         This parameter can be one of the following values:
 241   *           @arg @ref HAL_WWDG_EWI_CB_ID Early WakeUp Interrupt Callback ID
 242   *           @arg @ref HAL_WWDG_MSPINIT_CB_ID MspInit callback ID
 243   * @param  pCallback pointer to the Callback function
 244   * @retval status
 245   */
 246 HAL_StatusTypeDef HAL_WWDG_RegisterCallback(WWDG_HandleTypeDef *hwwdg, HAL_WWDG_CallbackIDTypeDef CallbackID, pWWDG_CallbackTypeDef pCallback)
 247 {
 248   HAL_StatusTypeDef status = HAL_OK;
 249
 250   if (pCallback == NULL)
 251   {
 252     status = HAL_ERROR;
 253   }
 254   else
 255   {
 256     switch (CallbackID)
 257     {
 258       case HAL_WWDG_EWI_CB_ID:
 259         hwwdg->EwiCallback = pCallback;
 260         break;
 261
 262       case HAL_WWDG_MSPINIT_CB_ID:
 263         hwwdg->MspInitCallback = pCallback;
 264         break;
 265
 266       default:
 267         status = HAL_ERROR;
 268         break;
 269     }
 270   }
 271
 272   return status;
 273 }
 274
 275
 276 /**
 277   * @brief  Unregister a WWDG Callback
 278   *         WWDG Callback is redirected to the weak (surcharged) predefined callback
 279   * @param  hwwdg WWDG handle
 280   * @param  CallbackID ID of the callback to be registered
 281   *         This parameter can be one of the following values:
 282   *           @arg @ref HAL_WWDG_EWI_CB_ID Early WakeUp Interrupt Callback ID
 283   *           @arg @ref HAL_WWDG_MSPINIT_CB_ID MspInit callback ID
 284   * @retval status
 285   */
 286 HAL_StatusTypeDef HAL_WWDG_UnRegisterCallback(WWDG_HandleTypeDef *hwwdg, HAL_WWDG_CallbackIDTypeDef CallbackID)
 287 {
 288   HAL_StatusTypeDef status = HAL_OK;
 289
 290   switch (CallbackID)
 291   {
 292     case HAL_WWDG_EWI_CB_ID:
 293       hwwdg->EwiCallback = HAL_WWDG_EarlyWakeupCallback;
 294       break;
 295
 296     case HAL_WWDG_MSPINIT_CB_ID:
 297       hwwdg->MspInitCallback = HAL_WWDG_MspInit;
 298       break;
 299
 300     default:
 301       status = HAL_ERROR;
 302       break;
 303   }
 304
 305   return status;
 306 }
 307 #endif
 308
 309 /**
 310   * @}
 311   */
 312
 313 /** @defgroup WWDG_Exported_Functions_Group2 IO operation functions
 314   *  @brief    IO operation functions
 315   *
 316 @verbatim
 317   ==============================================================================
 318                       ##### IO operation functions #####
 319   ==============================================================================
 320   [..]
 321     This section provides functions allowing to:
 322     (+) Refresh the WWDG.
 323     (+) Handle WWDG interrupt request and associated function callback.
 324
 325 @endverbatim
 326   * @{
 327   */
 328
 329 /**
 330   * @brief  Refresh the WWDG.
 331   * @param  hwwdg  pointer to a WWDG_HandleTypeDef structure that contains
 332   *                the configuration information for the specified WWDG module.
 333   * @retval HAL status
 334   */
 335 HAL_StatusTypeDef HAL_WWDG_Refresh(WWDG_HandleTypeDef *hwwdg)
 336 {
 337   /* Write to WWDG CR the WWDG Counter value to refresh with */
 338   WRITE_REG(hwwdg->Instance->CR, (hwwdg->Init.Counter));
 339
 340   /* Return function status */
 341   return HAL_OK;
 342 }
 343
 344 /**
 345   * @brief  Handle WWDG interrupt request.
 346   * @note   The Early Wakeup Interrupt (EWI) can be used if specific safety operations
 347   *         or data logging must be performed before the actual reset is generated.
 348   *         The EWI interrupt is enabled by calling HAL_WWDG_Init function with
 349   *         EWIMode set to WWDG_EWI_ENABLE.
 350   *         When the downcounter reaches the value 0x40, and EWI interrupt is
 351   *         generated and the corresponding Interrupt Service Routine (ISR) can
 352   *         be used to trigger specific actions (such as communications or data
 353   *         logging), before resetting the device.
 354   * @param  hwwdg  pointer to a WWDG_HandleTypeDef structure that contains
 355   *                the configuration information for the specified WWDG module.
 356   * @retval None
 357   */
 358 void HAL_WWDG_IRQHandler(WWDG_HandleTypeDef *hwwdg)
 359 {
 360   /* Check if Early Wakeup Interrupt is enable */
 361   if (__HAL_WWDG_GET_IT_SOURCE(hwwdg, WWDG_IT_EWI) != RESET)
 362   {
 363     /* Check if WWDG Early Wakeup Interrupt occurred */
 364     if (__HAL_WWDG_GET_FLAG(hwwdg, WWDG_FLAG_EWIF) != RESET)
 365     {
 366       /* Clear the WWDG Early Wakeup flag */
 367       __HAL_WWDG_CLEAR_FLAG(hwwdg, WWDG_FLAG_EWIF);
 368
 369 #if (USE_HAL_WWDG_REGISTER_CALLBACKS == 1)
 370       /* Early Wakeup registered callback */
 371       hwwdg->EwiCallback(hwwdg);
 372 #else
 373       /* Early Wakeup callback */
 374       HAL_WWDG_EarlyWakeupCallback(hwwdg);
 375 #endif
 376     }
 377   }
 378 }
 379
 380
 381 /**
 382   * @brief  WWDG Early Wakeup callback.
 383   * @param  hwwdg  pointer to a WWDG_HandleTypeDef structure that contains
 384   *                the configuration information for the specified WWDG module.
 385   * @retval None
 386   */
 387 __weak void HAL_WWDG_EarlyWakeupCallback(WWDG_HandleTypeDef *hwwdg)
 388 {
 389   /* Prevent unused argument(s) compilation warning */
 390   UNUSED(hwwdg);
 391
 392   /* NOTE: This function should not be modified, when the callback is needed,
 393            the HAL_WWDG_EarlyWakeupCallback could be implemented in the user file
 394    */
 395 }
 396
 397 /**
 398   * @}
 399   */
 400
 401 /**
 402   * @}
 403   */
 404
 405 #endif /* HAL_WWDG_MODULE_ENABLED */
 406 /**
 407   * @}
 408   */
 409
 410 /**
 411   * @}
 412   */
 413
 414 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/