MT2523 API Reference  LinkIt SDK v4
WDT

Overview

Terms and acronyms

Terms Details
NVIC Nested Vectored Interrupt Controller. NVIC is the interrupt controller of ARM Cortex-M4. For more details, please refer to NVIC introduction in ARM Cortex-M4 Processor Technical Reference Manual.
WDT Watchdog Timer. A watchdog timer is an electronic timer that is used to detect and recover from computer malfunctions. For an introduction to Watchdog timer, please refer to Watchdog timer in Wikipedia.

Supported features

Software architecture of WDT

The software architecture of WDT driver is shown in the below diagrams.

  1. WDT reset mode architecture : Set WDT to reset mode by calling hal_wdt_init() function, then call hal_wdt_enable() function to enable the timer. After the timer is enabled, call hal_wdt_feed() function to feed the watchdog continuously to avoid the timer expiration. If the software fails to feed the watchdog on time or hal_wdt_software_reset() function is called to manually trigger a reset, the WDT hardware will reset the MCU subsystem, MCU peripheral and DSP subsystem and reboot the system.
    hal_wdt_reset_mode.png
  2. WDT interrupt mode architecture: Unlike WDT reset mode, in WDT interrupt mode, an interrupt will be triggered, the MCU subsystem, MCU peripheral and DSP subsystem will not be reset and the system will not reboot.
    hal_wdt_interrupt_mode.png

How to use this driver

Functions

hal_wdt_status_t hal_wdt_init (hal_wdt_config_t *wdt_config)
 This function is mainly used to initialize the watchdog hardware. More...
 
hal_wdt_status_t hal_wdt_deinit (void)
 De-initialize the watchdog. More...
 
hal_wdt_status_t hal_wdt_enable (uint32_t magic)
 Enable the watchdog timer. More...
 
hal_wdt_status_t hal_wdt_disable (uint32_t magic)
 Disable the watchdog timer. More...
 
hal_wdt_status_t hal_wdt_software_reset (void)
 This function is used to trigger a watchdog reset manually. More...
 
hal_wdt_status_t hal_wdt_feed (uint32_t magic)
 This function is used to feed the watchdog(restart the watchdog timer). More...
 
hal_wdt_callback_t hal_wdt_register_callback (hal_wdt_callback_t wdt_callback)
 Register a callback function while using interrupt mode. More...
 
hal_wdt_reset_status_t hal_wdt_get_reset_status (void)
 Get the status of last watchdog reset/interrupt. More...
 
bool hal_wdt_get_enable_status (void)
 Get the enable status of the WDT. More...
 
hal_wdt_mode_t hal_wdt_get_mode (void)
 Get the current mode of the WDT. More...
 

Modules

 Define
 
 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_wdt_status_t hal_wdt_deinit ( void  )

De-initialize the watchdog.

After this function is called, the callback will be cleared and the WDT will be disabled.

Returns
This function will return HAL_WDT_STATUS_OK.
See also
hal_wdt_init()
Example
Sample code please refer to How to use this driver
hal_wdt_status_t hal_wdt_disable ( uint32_t  magic)

Disable the watchdog timer.

After this function, the watchdog timer will stop counting.

Parameters
[in]magicis the magic number of this function. Please always use HAL_WDT_DISABLE_MAGIC.
Returns
HAL_WDT_STATUS_OK means enable success.
HAL_WDT_STATUS_INVALID_MAGIC means an invalid magic number is given.
Note
The reset status (hardware status register) will be cleared by this function.
See also
hal_wdt_disable(), hal_wdt_get_reset_status(), hal_wdt_get_enable_status().
Example
Sample code please refer to How to use this driver
hal_wdt_status_t hal_wdt_enable ( uint32_t  magic)

Enable the watchdog timer.

After this function call, the watchdog timer will start counting down.

Parameters
[in]magicis the magic number of this function. Please always use HAL_WDT_ENABLE_MAGIC.
Returns
HAL_WDT_STATUS_OK means enable success.
HAL_WDT_STATUS_INVALID_MAGIC means an invalid magic number is given.
Note
The reset status (hardware status register) will be cleared by this function.
See also
hal_wdt_disable(), hal_wdt_get_reset_status(), hal_wdt_get_enable_status().
Example
Sample code please refer to How to use this driver
hal_wdt_status_t hal_wdt_feed ( uint32_t  magic)

This function is used to feed the watchdog(restart the watchdog timer).

To avoid the WDT from expiring, this function should be called regularly.

Parameters
[in]magicis the magic number of this function. Please always use HAL_WDT_FEED_MAGIC.
Returns
HAL_WDT_STATUS_OK means enable success.
HAL_WDT_STATUS_INVALID_MAGIC means an invalid magic number is given.
Example
Sample code please refer to How to use this driver
bool hal_wdt_get_enable_status ( void  )

Get the enable status of the WDT.

Returns
true means the watchdog is enabled and the timer is counting.
false means the watchdog is disabled and the timer is stopped.
See also
hal_wdt_enable(), hal_wdt_disable().
Example
1 ret = hal_wdt_get_enable_status();
2 if (true == ret) {
3  // WDT enable
4 } else {
5  // WDT disable
6 }
hal_wdt_mode_t hal_wdt_get_mode ( void  )

Get the current mode of the WDT.

For more information on reset and interrupt modes, please refer to Supported features in overview.

Returns
HAL_WDT_MODE_RESET means the watchdog is in reset mode.
HAL_WDT_MODE_INTERRUPT means the watchdog is in interrupt mode.
See also
hal_wdt_init().
Example
1 ret = hal_wdt_get_mode();
2 if (HAL_WDT_MODE_RESET == ret) {
3  // WDT reset mode
4 } else if (HAL_WDT_MODE_INTERRUPT == ret) {
5  // WDT interrupt mode
6 }
hal_wdt_reset_status_t hal_wdt_get_reset_status ( void  )

Get the status of last watchdog reset/interrupt.

If the WDT failed to be fed in time and has expired, the status will be HAL_WDT_TIMEOUT_RESET. If the software register is set by hal_wdt_software_reset() function, the status will be HAL_WDT_SOFTWARE_RESET. Note that the reset status can be cleared by hal_wdt_init(), hal_wdt_enable() and hal_wdt_disable() functions. It is advised to call this function to get the reset status before hal_wdt_init(), hal_wdt_enable() and hal_wdt_disable() function calls. If you want to preserve the reset status of the last reset, you should call this function to get the reset status before calling hal_wdt_init() and hal_wdt_enable() and hal_wdt_disable().

Returns
HAL_WDT_TIMEOUT_RESET means the WDT reset is due to the timer timing out;
HAL_WDT_SOFTWARE_RESET means the WDT reset is due to software trigger;
HAL_WDT_NONE_RESET means no WDT reset occurred.
See also
hal_wdt_init(), hal_wdt_enable(), hal_wdt_disable(), hal_wdt_software_reset().
Example
1 ret = hal_wdt_get_reset_status();
2 if (HAL_WDT_TIMEOUT_RESET == ret) {
3  // handle timeout reset;
4 } else if (HAL_WDT_SOFTWARE_RESET == ret) {
5  // handle software reset;
6 } else (HAL_WDT_NONE_RESET == ret) {
7  // handle none reset case;
8 }
hal_wdt_status_t hal_wdt_init ( hal_wdt_config_t wdt_config)

This function is mainly used to initialize the watchdog hardware.

It is used to set the WDT to either reset or interrupt modes. For more details on reset and interrupt modes, please refer to overview in Supported features. It’s also used to set the timeout value of the watchdog timer. This function will not enable the WDT. To enable WDT, the hal_wdt_enable() must be called.

Parameters
[in]wdt_configis the init configuration parameter. For more details about this parameter, please refer to hal_wdt_config_t.
Returns
HAL_WDT_STATUS_OK means success;
HAL_WDT_STATUS_INVALID_PARAMETER means a wrong parameter is given, the parameter must be verified.
See also
hal_wdt_deinit()
Example
Sample code please refer to How to use this driver
hal_wdt_callback_t hal_wdt_register_callback ( hal_wdt_callback_t  wdt_callback)

Register a callback function while using interrupt mode.

Parameters
[in]wdt_callbackis the function pointer to the callback. This callback is called once the WDT triggers an interrupt in the ISR routine. WDT driver will only keep the last registered wdt_callback. It means if user1 registers callback func1, later, user2 registers callback func2, the driver will only keep callback func2 and return func1 to user2.
Returns
This function will return the current callback function. This means that if user1 is the first one to call this function to register a callback func1, it will receive NULL as a return value. Then, user2 calls this function to register its own callback func2; it will receive a function pointer func1. User can make use of this character to implement a callback chain.

For example, user1 registers func1 and gets return value NULL, user2 registers func2 and gets return value func1, and user3 register func3 and get func2. In this case, the WDT driver will keep the last callback func3. Once the WDT times out and triggers an interrupt, the WDT ISR routine will call func3. As func3 have recorded func2, it can call func2 in func3. Using similar analogy, func2 can call func1. But as func1 is the first one registered and the return value must be NULL, func1 should be the last one to be called.
See also
hal_wdt_init()
Example
1 // in user code
2 ret_callback = hal_wdt_register_callback(wdt_callback);
1 void wdt_callback(hal_wdt_reset_status_t wdt_reset_status)
2 {
3  // other code.
4  ret_callback(wdt_reset_status);
5 }
hal_wdt_status_t hal_wdt_software_reset ( void  )

This function is used to trigger a watchdog reset manually.

After this function is called, the software reset bit of the hardware status register will be set, you can get this status by using hal_wdt_get_reset_status().

Returns
This function will return HAL_WDT_STATUS_OK.
Note
Please be noted that the WDT will immediately trigger hardware reset or interrupt even if the timeout has not been reached.
Example
Sample code please refer to How to use this driver