HAL IWDG Functions

Initialization and Start functions

group IWDG_Exported_Functions_Group1

This subsection provides a set of functions allowing to initialize and start the IWDG peripheral:

  • Call the function HAL_IWDG_Init() to initialize the IWDG handle and associate an instance.

  • Call the function HAL_IWDG_Start() to start the IWDG according to the parameters provided by the user.

Functions

hal_status_t HAL_IWDG_Init ( hal_iwdg_handle_t * hiwdg , hal_iwdg_t instance )

Initialize the IWDG according to the associated handle.

Warning

LSI frequency used in the driver is reinitialized to the default value LSI_VALUE or LSI_VALUE/128 (if LSI prescaler is enabled) and then API HAL_IWDG_SetLSIFrequency() can be called to use a more accurate value.

Warning

In case of starting IWDG in Hardware mode, make sure that USE_HAL_IWDG_HARDWARE_START is aligned with the IWDG_SW option byte.

Parameters :

  • hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

  • instance – IWDG instance.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_INVALID_PARAM – Invalid parameter.

hal_status_t HAL_IWDG_Start ( hal_iwdg_handle_t * hiwdg , uint32_t min_time , uint32_t max_time , uint32_t early_wakeup_time )

Start the IWDG. Before exiting the function, the watchdog is refreshed to have a correct time base.

Warning

The min_time and max_time are used to define the window and the reload values, the unit for these parameters depend on the switch USE_HAL_IWDG_TIME_UNIT.

Warning

When the Window is not needed, the value of min_time is set to IWDG_WINDOW_DISABLE.

Warning

The early_wakeup_time is used to set the Early Wakeup Interrupt. When it is not needed, value is set to IWDG_EWI_DISABLE.

Parameters :

  • hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

  • min_time – Minimum time value before refreshing is allowed.

  • max_time – Maximum time value before a WWDG reset.

  • early_wakeup_time – Early Wakeup Interrupt time value.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

IO Operation functions

group IWDG_Exported_Functions_Group2

This subsection provides a set of functions to manage the IWDG driver:

  • Call the function HAL_IWDG_Refresh() to reload IWDG counter with value defined in the reload register.

Functions

hal_status_t HAL_IWDG_Refresh ( hal_iwdg_handle_t * hiwdg )

Refresh the IWDG.

Parameters :

hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

Return values :

HAL_OK – Operation completed successfully.

State functions

group IWDG_Exported_Functions_Group3

This subsection provides a set of functions to manage the IWDG driver:

Functions

hal_iwdg_state_t HAL_IWDG_GetState ( const hal_iwdg_handle_t * hiwdg )

Return the IWDG handle state.

Parameters :

hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

Return values :

  • HAL_IWDG_STATE_RESET – IWDG driver not initialized and not started.

  • HAL_IWDG_STATE_IDLE – IWDG driver initialized and not started.

  • HAL_IWDG_STATE_ACTIVE – IWDG driver initialized and started.

Set and Get item functions

group IWDG_Exported_Functions_Group4

This subsection provides a set of functions to set/retrieve configuration items separately for the IWDG driver:

Note

The prescaler is calculated from max_time once in the HAL_IWDG_Start() function, to avoid a change of prescaler, we did not proceed by a setMaxTime() function because it can modify the prescaler and thus require to recalculate the Window and the Early Wakeup Interrupt. To modify the max_time, the user must proceed by the HAL_IWDG_Start() function.

Functions

uint32_t HAL_IWDG_GetMaxTime ( const hal_iwdg_handle_t * hiwdg )

Get the reset time value according to the handler instance registers.

Parameters :

hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

Return values :

uint32_t – Current reset time in the selected USE_HAL_IWDG_TIME_UNIT unit.

uint32_t HAL_IWDG_GetStep_us ( const hal_iwdg_handle_t * hiwdg )

Get the step of the IWDG in microseconds.

Note

HAL_IWDG_GetStep_us is given as informational to allow the user to calculate max_time, min_time and early_wakeup_time to avoid rounded values.

Parameters :

hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

Return values :

uint32_t – Current step value in us.

hal_status_t HAL_IWDG_SetMinTime ( hal_iwdg_handle_t * hiwdg , uint32_t time )

Set the Window time value.

Note

Modifying the IWDG Window register will automatically reload the watchdog counter.

Parameters :

  • hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

  • time – Window time value to be set.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

uint32_t HAL_IWDG_GetMinTime ( const hal_iwdg_handle_t * hiwdg )

Get the Window time value according to the handler instance registers.

Parameters :

hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

Return values :

uint32_t – Current Window time value.

hal_status_t HAL_IWDG_SetEarlyWakeupInterruptTime ( hal_iwdg_handle_t * hiwdg , uint32_t time )

Set the Early Wakeup time value.

Note

Modifying the IWDG early wakeup interrupt register will automatically reload the watchdog counter.

Parameters :

  • hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

  • time – Early Wakeup time value to be set.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

uint32_t HAL_IWDG_GetEarlyWakeupInterruptTime ( const hal_iwdg_handle_t * hiwdg )

Get the Window time value according to the handler instance registers.

Parameters :

hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

Return values :

uint32_t – Current Early Wakeup time value.

IRQ Handler/Callbacks/Register Callbacks functions

group IWDG_Exported_Functions_Group5

This subsection provides a set of functions allowing to register the IWDG process and callbacks:

There are two ways to use callbacks:

Override weak callback function: Call the function

HAL_IWDG_EarlyWakeupCallback()

to indicate that an early interrupt is pending.

Or register callbacks user: Call the function

HAL_IWDG_RegisterEarlyWakeupCallback() to register the Early Wakeup Callback.

Functions

void HAL_IWDG_IRQHandler ( hal_iwdg_handle_t * hiwdg )

Handle IWDG interrupt request.

Note

The Early Wakeup Interrupt (EWI) can be used if specific safety operations or data logging must be performed before the actual reset is generated. The EWI interrupt is enabled by calling HAL_IWDG_Start() function with an early_wakeup_time. When the downcounter reaches the value EWIT - 1 , an EWI interrupt is generated and the corresponding Interrupt Service Routine (ISR) can be used to trigger specific actions through the callback, before the device resets.

Parameters :

hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

void HAL_IWDG_EarlyWakeupCallback ( hal_iwdg_handle_t * hiwdg )

IWDG Early Wakeup callback.

Warning

This function must not be modified, when the callback is needed, the HAL_IWDG_EarlyWakeupCallback() can be implemented in the user file

Parameters :

hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

hal_status_t HAL_IWDG_RegisterEarlyWakeupCallback ( hal_iwdg_handle_t * hiwdg , hal_iwdg_cb_t p_callback )

Register the user IWDG Early Wakeup Callback.

Parameters :

  • hiwdg – Pointer to a hal_iwdg_handle_t structure that contains the configuration information for the specified IWDG module.

  • p_callback – pointer to the hal_iwdg_cb_t Callback function

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_INVALID_PARAM – Invalid parameter.

Set and Get User Data functions

group IWDG_Exported_Functions_Group6

This section provides functions allowing to Set and Get user data:

Functions

void HAL_IWDG_SetUserData ( hal_iwdg_handle_t * hiwdg , const void * p_user_data )

Store the user data into the IWDG handle.

Parameters :

  • hiwdg – Pointer to IWDG handle.

  • p_user_data – Pointer to the user data.

const void * HAL_IWDG_GetUserData ( const hal_iwdg_handle_t * hiwdg )

Retrieve the user data from the IWDG handle.

Parameters :

hiwdg – Pointer to IWDG handle.

Return values :

Pointer – to the user data.