If you need urgent consulting help click here

Task Watchdog

Overview

Many microcontrollers feature a hardware watchdog timer peripheral. Its purpose is to trigger an action (usually a system reset) in case of severe software malfunctions. Once initialized, the watchdog timer has to be restarted (“fed”) in regular intervals to prevent it from timing out. If the software got stuck and does not manage to feed the watchdog anymore, the corrective action is triggered to bring the system back to normal operation.

In real-time operating systems with multiple tasks running in parallel, a single watchdog instance may not be sufficient anymore, as it can be used for only one task. This software watchdog based on kernel timers provides a method to supervise multiple threads or tasks (called watchdog channels).

An existing hardware watchdog can be used as an optional fallback if the task watchdog itself or the scheduler has a malfunction.

The task watchdog uses a kernel timer as its backend. If configured properly, the timer ISR is never actually called during normal operation, as the timer is continuously updated in the feed calls.

It’s currently not possible to have multiple instances of task watchdogs. Instead, the task watchdog API can be accessed globally to add or delete new channels without passing around a context or device pointer in the firmware.

The maximum number of channels is predefined via Kconfig and should be adjusted to match exactly the number of channels required by the application.

API Reference

group task_wdt_api

Task Watchdog APIs.

Typedefs

typedef void (*task_wdt_callback_t)(int channel_id, void *user_data)

Task watchdog callback.

Functions

int task_wdt_init(const struct device *hw_wdt)

Initialize task watchdog.

This function sets up necessary kernel timers and the hardware watchdog (if desired as fallback). It has to be called before task_wdt_add() and task_wdt_feed().

Parameters

  • hw_wdt – Pointer to the hardware watchdog device used as fallback. Pass NULL if no hardware watchdog fallback is desired.

Return values

  • 0 – If successful.

  • -ENOTSUP – If assigning a hardware watchdog is not supported.

  • -Errno – Negative errno if the fallback hw_wdt is used and the install timeout API fails. See wdt_install_timeout() API for possible return values.

int task_wdt_add(uint32_t reload_period, task_wdt_callback_t callback, void *user_data)

Install new timeout.

Adds a new timeout to the list of task watchdog channels.

Parameters

  • reload_period – Period in milliseconds used to reset the timeout

  • callback – Function to be called when watchdog timer expired. Pass NULL to use system reset handler.

  • user_data – User data to associate with the watchdog channel.

Return values

  • channel_id – If successful, a non-negative value indicating the index of the channel to which the timeout was assigned. This ID is supposed to be used as the parameter in calls to task_wdt_feed().

  • -EINVAL – If the reload_period is invalid.

  • -ENOMEM – If no more timeouts can be installed.

int task_wdt_delete(int channel_id)

Delete task watchdog channel.

Deletes the specified channel from the list of task watchdog channels. The channel is now available again for other tasks via task_wdt_add() function.

Parameters
Return values

  • 0 – If successful.

  • -EINVAL – If there is no installed timeout for supplied channel.

int task_wdt_feed(int channel_id)

Feed specified watchdog channel.

This function loops through all installed task watchdogs and updates the internal kernel timer used as for the software watchdog with the next due timeout.

Parameters

  • channel_id – Index of the fed channel as returned by task_wdt_add().

Return values

  • 0 – If successful.

  • -EINVAL – If there is no installed timeout for supplied channel.