WDT

This section introduces the Watchdog Timer (WDT) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions. More...

Overview

This section introduces the Watchdog Timer (WDT) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.

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

• Support reset and interrupt modes.
  There are two hardware behaviors based on the supported mode configuration after the timer times out or soft reset register is set:
  • Reset mode: In this mode, a hardware reset signal will be triggered by WDT hardware, and the MCU subsystem, MCU peripheral and DSP subsystem will be reset. The system will reboot.
  • Interrupt mode: In this mode, an interrupt will be triggered by WDT hardware. This mode is usually used for debugging. The MCU subsystem, MCU peripheral and DSP subsystem will not be reset and system will not reboot. You can register a callback to record important information for debugging while the interrupt is triggered.
  You can use hal_wdt_init() to set the mode and use hal_wdt_get_mode() to get current mode.
  
  
• Support software reset.
  For special purposes, you can manually trigger a watchdog reset or watchdog interrupt by calling hal_wdt_software_reset().
  It will trigger WDT reset/interrupt immediately without waiting the timer to timeout.
  
  
• Support callback function registration. When the WDT is configured as interrupt mode, you can register a callback function
  via hal_wdt_register_callback(). Your callback function will be called after the WDT triggers an interrupt in the WDT ISR routine.

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.
   
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.
   

How to use this driver

• Use WDT in a reset mode.
  
  • step1: call hal_wdt_init() to configure the WDT as reset mode.
  • step2: call hal_wdt_enable() to start the watchdog timer.
  • step3: call hal_wdt_feed() to feed the watchdog continuously to avoid the timer expiration.
  • step4: call hal_wdt_disable() if user wants to disable the WDT.
  • step5: call hal_wdt_deinit() if user wants to deinit the WDT.
  • sample code:

    uint32_t ret_reset_status;
    hal_wdt_config_t wdt_config;
    wdt_config.mode = HAL_WDT_MODE_RESET;
    wdt_config.seconds = 4;
    
    ret_reset_status = hal_wdt_get_reset_status(); //get reset status first, because hal_wdt_init, hal_wdt_enable,
    //hal_wdt_disable will clear the reset status. User can get the reason of last reset by this status. ret_reset_status may be used at any time after #hal_wdt_init() is called.
    //set WDT as t0 mode.
    if(HAL_WDT_STATUS_OK != hal_wdt_init(&wdt_config)) {
          //error handle
    }
    hal_wdt_enable(HAL_WDT_ENABLE_MAGIC); //enable WDT to start the timer.
    hal_wdt_feed(HAL_WDT_FEED_MAGIC);  //feed the WDT regularly.
    // ...
    //hal_wdt_disable(HAL_WDT_DISABLE_MAGIC); //if you want to disable the WDT
    //hal_wdt_deinit();// if you want to deinit the WDT.

• Use WDT in an interrupt mode.
  
  • step1: call hal_wdt_init() to configure the WDT as reset mode.
  • step2: call hal_wdt_register_callback() to register a callback function.
  • step3: call hal_wdt_enable() to start the watchdog timer.
  • step4: call hal_wdt_feed() to feed the watchdog regularly to avoid the timer expiration.
  • step5: call hal_wdt_disable() if user wants to disable the WDT.
  • step6: call hal_wdt_deinit() if user wants to deinit the WDT.
  • sample code:

    uint32_t ret_reset_status;
    hal_wdt_config_t wdt_config;
    wdt_config.mode = HAL_WDT_MODE_INTERRUPT;
    wdt_config.seconds = 4;
    
    ret_reset_status = hal_wdt_get_reset_status(); //get reset status first, because hal_wdt_init, hal_wdt_enable,
    //hal_wdt_disable will clear the reset status. User can get the reason of last reset by this status. ret_reset_status may be used at any time after #hal_wdt_init() is called.
    //set WDT as interrupt mode.
    if(HAL_WDT_STATUS_OK != hal_wdt_init(&wdt_config)) {
          //error handle
    }
    hal_wdt_register_callback(user_callback); // register a user callback.
    hal_wdt_enable(HAL_WDT_ENABLE_MAGIC); //enable WDT to start the timer.
    hal_wdt_feed(HAL_WDT_FEED_MAGIC);  //feed the WDT regularly.
    //...
    //hal_wdt_disable(HAL_WDT_DISABLE_MAGIC); //if you want to disable the WDT
    //hal_wdt_deinit();// if you want to deinit the WDT.

    // Callback function. This function should be registered with #hal_wdt_register_callback().
    void wdt_callback(hal_wdt_reset_status_t wdt_reset_status)
    {
        //Just normal irq, what we do in this function is depends on user's usage, such as for debug.
        //ret_callback(wdt_reset_status);
    }

• To trigger a WDT reset or interrupt manually, it only needs to call the hal_wdt_software_reset(). The reset or interrupt will be triggered immediately after the call.

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]

magic

is 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]

magic

is 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]

magic

is 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

ret = hal_wdt_get_enable_status();
if (true == ret) {
   // WDT enable
} else {
   // WDT disable
}

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

ret = hal_wdt_get_mode();
if (HAL_WDT_MODE_RESET == ret) {
   // WDT reset mode
} else if (HAL_WDT_MODE_INTERRUPT == ret) {
   // WDT interrupt mode
}

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

ret = hal_wdt_get_reset_status();
if (HAL_WDT_TIMEOUT_RESET == ret) {
    // handle timeout reset;
} else if (HAL_WDT_SOFTWARE_RESET == ret) {
    // handle software reset;
} else (HAL_WDT_NONE_RESET == ret) {
    // handle none reset case;
}

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_config

is 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_callback

is 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

// in user code
ret_callback = hal_wdt_register_callback(wdt_callback);

void wdt_callback(hal_wdt_reset_status_t wdt_reset_status)
{
    // other code.
    ret_callback(wdt_reset_status);
}

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