Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2020 Libre Solar Technologies GmbH
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /**
       8             :  * @file
       9             :  * @brief Task watchdog header file
      10             :  *
      11             :  * This header file declares prototypes for the task watchdog APIs.
      12             :  *
      13             :  * The task watchdog can be used to monitor correct operation of individual
      14             :  * threads. It can be used together with a hardware watchdog as a fallback.
      15             :  */
      16             : 
      17             : #ifndef ZEPHYR_INCLUDE_TASK_WDT_H_
      18             : #define ZEPHYR_INCLUDE_TASK_WDT_H_
      19             : 
      20             : #include <zephyr/types.h>
      21             : #include <zephyr/kernel.h>
      22             : #include <zephyr/device.h>
      23             : 
      24             : /**
      25             :  * @brief Task Watchdog APIs
      26             :  * @defgroup task_wdt_api Task Watchdog APIs
      27             :  * @since 2.5
      28             :  * @version 0.8.0
      29             :  * @ingroup os_services
      30             :  * @{
      31             :  */
      32             : 
      33             : #ifdef __cplusplus
      34             : extern "C" {
      35             : #endif
      36             : 
      37             : /** Task watchdog callback. */
      38           1 : typedef void (*task_wdt_callback_t)(int channel_id, void *user_data);
      39             : 
      40             : /**
      41             :  * @brief Initialize task watchdog.
      42             :  *
      43             :  * This function sets up necessary kernel timers and the hardware watchdog (if
      44             :  * desired as fallback). It has to be called before task_wdt_add() and
      45             :  * task_wdt_feed().
      46             :  *
      47             :  * @param hw_wdt Pointer to the hardware watchdog device used as fallback.
      48             :  *               Pass NULL if no hardware watchdog fallback is desired.
      49             :  *
      50             :  * @retval 0 If successful.
      51             :  * @retval -ENOTSUP If assigning a hardware watchdog is not supported.
      52             :  * @retval -Errno Negative errno if the fallback hw_wdt is used and the
      53             :  *                install timeout API fails.  See wdt_install_timeout()
      54             :  *                API for possible return values.
      55             :  */
      56           1 : int task_wdt_init(const struct device *hw_wdt);
      57             : 
      58             : /**
      59             :  * @brief Install new timeout.
      60             :  *
      61             :  * Adds a new timeout to the list of task watchdog channels.
      62             :  *
      63             :  * @param reload_period Period in milliseconds used to reset the timeout
      64             :  * @param callback Function to be called when watchdog timer expired. Pass
      65             :  *                 NULL to use system reset handler.
      66             :  * @param user_data User data to associate with the watchdog channel.
      67             :  *
      68             :  * @retval channel_id If successful, a non-negative value indicating the index
      69             :  *                    of the channel to which the timeout was assigned. This
      70             :  *                    ID is supposed to be used as the parameter in calls to
      71             :  *                    task_wdt_feed().
      72             :  * @retval -EINVAL If the reload_period is invalid.
      73             :  * @retval -ENOMEM If no more timeouts can be installed.
      74             :  */
      75           1 : int task_wdt_add(uint32_t reload_period, task_wdt_callback_t callback,
      76             :                  void *user_data);
      77             : 
      78             : /**
      79             :  * @brief Delete task watchdog channel.
      80             :  *
      81             :  * Deletes the specified channel from the list of task watchdog channels. The
      82             :  * channel is now available again for other tasks via task_wdt_add() function.
      83             :  *
      84             :  * @param channel_id Index of the channel as returned by task_wdt_add().
      85             :  *
      86             :  * @retval 0 If successful.
      87             :  * @retval -EINVAL If there is no installed timeout for supplied channel.
      88             :  */
      89           1 : int task_wdt_delete(int channel_id);
      90             : 
      91             : /**
      92             :  * @brief Feed specified watchdog channel.
      93             :  *
      94             :  * This function loops through all installed task watchdogs and updates the
      95             :  * internal kernel timer used as for the software watchdog with the next due
      96             :  * timeout.
      97             :  *
      98             :  * @param channel_id Index of the fed channel as returned by task_wdt_add().
      99             :  *
     100             :  * @retval 0 If successful.
     101             :  * @retval -EINVAL If there is no installed timeout for supplied channel.
     102             :  */
     103           1 : int task_wdt_feed(int channel_id);
     104             : 
     105             : #ifdef __cplusplus
     106             : }
     107             : #endif
     108             : 
     109             : /**
     110             :  * @}
     111             :  */
     112             : 
     113             : #endif /* ZEPHYR_INCLUDE_TASK_WDT_H_ */