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.

Returns 0

If successful.

Returns -ENOTSUP

If assigning a hardware watchdog is not supported.

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.

Returns 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().

Returns -EINVAL

If the reload_period is invalid.

Returns -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
Returns 0

If successful.

Returns -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().

Returns 0

If successful.

Returns -EINVAL

If there is no installed timeout for supplied channel.