Line data    Source code

       1           0 : /*
       2             :  * Copyright (c) 2017 Nordic Semiconductor ASA
       3             :  * Copyright (c) 2015 Intel Corporation
       4             :  *
       5             :  * SPDX-License-Identifier: Apache-2.0
       6             :  */
       7             : 
       8             : #ifndef ZEPHYR_INCLUDE_DRIVERS_WATCHDOG_H_
       9             : #define ZEPHYR_INCLUDE_DRIVERS_WATCHDOG_H_
      10             : 
      11             : /**
      12             :  * @brief Watchdog Interface
      13             :  * @defgroup watchdog_interface Watchdog Interface
      14             :  * @since 1.0
      15             :  * @version 1.0.0
      16             :  * @ingroup io_interfaces
      17             :  * @{
      18             :  */
      19             : 
      20             : #include <zephyr/types.h>
      21             : #include <zephyr/sys/util.h>
      22             : #include <zephyr/device.h>
      23             : 
      24             : #ifdef __cplusplus
      25             : extern "C" {
      26             : #endif
      27             : 
      28             : /**
      29             :  * @name Watchdog options
      30             :  * @anchor WDT_OPT
      31             :  * @{
      32             :  */
      33             : 
      34             : /** @brief Pause watchdog timer when CPU is in sleep state. */
      35           1 : #define WDT_OPT_PAUSE_IN_SLEEP          BIT(0)
      36             : 
      37             : /** @brief Pause watchdog timer when CPU is halted by the debugger. */
      38           1 : #define WDT_OPT_PAUSE_HALTED_BY_DBG     BIT(1)
      39             : 
      40             : /** @} */
      41             : 
      42             : /**
      43             :  * @name Watchdog behavior flags
      44             :  * @anchor WDT_FLAGS
      45             :  * @{
      46             :  */
      47             : 
      48             : /** @cond INTERNAL_HIDDEN */
      49             : /** @brief Watchdog reset flag bit field mask shift. */
      50             : #define WDT_FLAG_RESET_SHIFT            (0)
      51             : /** @brief Watchdog reset flag bit field mask. */
      52             : #define WDT_FLAG_RESET_MASK             (0x3 << WDT_FLAG_RESET_SHIFT)
      53             : /** @endcond */
      54             : 
      55             : /** Reset: none */
      56           1 : #define WDT_FLAG_RESET_NONE             (0 << WDT_FLAG_RESET_SHIFT)
      57             : /** Reset: CPU core */
      58           1 : #define WDT_FLAG_RESET_CPU_CORE         (1 << WDT_FLAG_RESET_SHIFT)
      59             : /** Reset: SoC */
      60           1 : #define WDT_FLAG_RESET_SOC              (2 << WDT_FLAG_RESET_SHIFT)
      61             : 
      62             : /** @} */
      63             : 
      64             : /**
      65             :  * @brief Watchdog timeout window.
      66             :  *
      67             :  * Each installed timeout needs feeding within the specified time window,
      68             :  * otherwise the watchdog will trigger. If the watchdog instance does not
      69             :  * support window timeouts then min value must be equal to 0.
      70             :  *
      71             :  * @note If specified values can not be precisely set they are always rounded
      72             :  * up.
      73             :  */
      74           1 : struct wdt_window {
      75             :         /** Lower limit of watchdog feed timeout in milliseconds. */
      76           1 :         uint32_t min;
      77             :         /** Upper limit of watchdog feed timeout in milliseconds. */
      78           1 :         uint32_t max;
      79             : };
      80             : 
      81             : /**
      82             :  * @brief Watchdog callback.
      83             :  *
      84             :  * @param dev Watchdog device instance.
      85             :  * @param channel_id Channel identifier.
      86             :  */
      87           1 : typedef void (*wdt_callback_t)(const struct device *dev, int channel_id);
      88             : 
      89             : /** @brief Watchdog timeout configuration. */
      90           1 : struct wdt_timeout_cfg {
      91             :         /** Timing parameters of watchdog timeout. */
      92           1 :         struct wdt_window window;
      93             :         /** Timeout callback (can be `NULL`). */
      94           1 :         wdt_callback_t callback;
      95             : #if defined(CONFIG_WDT_MULTISTAGE) || defined(__DOXYGEN__)
      96             :         /**
      97             :          * Pointer to the next timeout configuration.
      98             :          *
      99             :          * This field is only available if @kconfig{CONFIG_WDT_MULTISTAGE} is
     100             :          * enabled (watchdogs with staged timeouts functionality). Value must be
     101             :          * `NULL` for single stage timeout.
     102             :          */
     103           1 :         struct wdt_timeout_cfg *next;
     104             : #endif
     105             :         /** Flags (see @ref WDT_FLAGS). */
     106           1 :         uint8_t flags;
     107             : };
     108             : 
     109             : /** @cond INTERNAL_HIDDEN */
     110             : 
     111             : /**
     112             :  * @brief Callback API for setting up watchdog instance.
     113             :  * @see wdt_setup().
     114             :  */
     115             : typedef int (*wdt_api_setup)(const struct device *dev, uint8_t options);
     116             : 
     117             : /**
     118             :  * @brief Callback API for disabling watchdog instance.
     119             :  * @see wdt_disable().
     120             :  */
     121             : typedef int (*wdt_api_disable)(const struct device *dev);
     122             : 
     123             : /**
     124             :  * @brief Callback API for installing new timeout.
     125             :  * @see wdt_install_timeout().
     126             :  */
     127             : typedef int (*wdt_api_install_timeout)(const struct device *dev,
     128             :                                        const struct wdt_timeout_cfg *cfg);
     129             : 
     130             : /**
     131             :  * @brief Callback API for feeding specified watchdog timeout.
     132             :  * @see wdt_feed().
     133             :  */
     134             : typedef int (*wdt_api_feed)(const struct device *dev, int channel_id);
     135             : 
     136             : __subsystem struct wdt_driver_api {
     137             :         wdt_api_setup setup;
     138             :         wdt_api_disable disable;
     139             :         wdt_api_install_timeout install_timeout;
     140             :         wdt_api_feed feed;
     141             : };
     142             : /**
     143             :  * @endcond
     144             :  */
     145             : 
     146             : /**
     147             :  * @brief Set up watchdog instance.
     148             :  *
     149             :  * This function is used for configuring global watchdog settings that
     150             :  * affect all timeouts. It should be called after installing timeouts.
     151             :  * After successful return, all installed timeouts are valid and must be
     152             :  * serviced periodically by calling wdt_feed().
     153             :  *
     154             :  * @param dev Watchdog device instance.
     155             :  * @param options Configuration options (see @ref WDT_OPT).
     156             :  *
     157             :  * @retval 0 If successful.
     158             :  * @retval -ENOTSUP If any of the set options is not supported.
     159             :  * @retval -EBUSY If watchdog instance has been already setup.
     160             :  * @retval -errno In case of any other failure.
     161             :  */
     162           1 : __syscall int wdt_setup(const struct device *dev, uint8_t options);
     163             : 
     164             : static inline int z_impl_wdt_setup(const struct device *dev, uint8_t options)
     165             : {
     166             :         const struct wdt_driver_api *api =
     167             :                 (const struct wdt_driver_api *)dev->api;
     168             : 
     169             :         return api->setup(dev, options);
     170             : }
     171             : 
     172             : /**
     173             :  * @brief Disable watchdog instance.
     174             :  *
     175             :  * This function disables the watchdog instance and automatically uninstalls all
     176             :  * timeouts. To set up a new watchdog, install timeouts and call wdt_setup()
     177             :  * again. Not all watchdogs can be restarted after they are disabled.
     178             :  *
     179             :  * @param dev Watchdog device instance.
     180             :  *
     181             :  * @retval 0 If successful.
     182             :  * @retval -EFAULT If watchdog instance is not enabled.
     183             :  * @retval -EPERM If watchdog can not be disabled directly by application code.
     184             :  * @retval -errno In case of any other failure.
     185             :  */
     186           1 : __syscall int wdt_disable(const struct device *dev);
     187             : 
     188             : static inline int z_impl_wdt_disable(const struct device *dev)
     189             : {
     190             :         const struct wdt_driver_api *api =
     191             :                 (const struct wdt_driver_api *)dev->api;
     192             : 
     193             :         return api->disable(dev);
     194             : }
     195             : 
     196             : /**
     197             :  * @brief Install a new timeout.
     198             :  *
     199             :  * @note This function must be used before wdt_setup(). Changes applied here
     200             :  * have no effects until wdt_setup() is called.
     201             :  *
     202             :  * @param dev Watchdog device instance.
     203             :  * @param[in] cfg Timeout configuration.
     204             :  *
     205             :  * @retval channel_id If successful, a non-negative value indicating the index
     206             :  * of the channel to which the timeout was assigned. This value is supposed to
     207             :  * be used as the parameter in calls to wdt_feed().
     208             :  * @retval -EBUSY If timeout can not be installed while watchdog has already
     209             :  * been setup.
     210             :  * @retval -ENOMEM If no more timeouts can be installed.
     211             :  * @retval -ENOTSUP If any of the set flags is not supported.
     212             :  * @retval -EINVAL If any of the window timeout value is out of possible range.
     213             :  * This value is also returned if watchdog supports only one timeout value for
     214             :  * all timeouts and the supplied timeout window differs from windows for alarms
     215             :  * installed so far.
     216             :  * @retval -errno In case of any other failure.
     217             :  */
     218           1 : static inline int wdt_install_timeout(const struct device *dev,
     219             :                                       const struct wdt_timeout_cfg *cfg)
     220             : {
     221             :         const struct wdt_driver_api *api =
     222             :                 (const struct wdt_driver_api *) dev->api;
     223             : 
     224             :         return api->install_timeout(dev, cfg);
     225             : }
     226             : 
     227             : /**
     228             :  * @brief Feed specified watchdog timeout.
     229             :  *
     230             :  * @param dev Watchdog device instance.
     231             :  * @param channel_id Channel index.
     232             :  *
     233             :  * @retval 0 If successful.
     234             :  * @retval -EAGAIN If completing the feed operation would stall the caller, for
     235             :  * example due to an in-progress watchdog operation such as a previous
     236             :  * wdt_feed() call.
     237             :  * @retval -EINVAL If there is no installed timeout for supplied channel.
     238             :  * @retval -errno In case of any other failure.
     239             :  */
     240           1 : __syscall int wdt_feed(const struct device *dev, int channel_id);
     241             : 
     242             : static inline int z_impl_wdt_feed(const struct device *dev, int channel_id)
     243             : {
     244             :         const struct wdt_driver_api *api =
     245             :                 (const struct wdt_driver_api *)dev->api;
     246             : 
     247             :         return api->feed(dev, channel_id);
     248             : }
     249             : 
     250             : #ifdef __cplusplus
     251             : }
     252             : #endif
     253             : 
     254             : /** @} */
     255             : 
     256             : #include <zephyr/syscalls/watchdog.h>
     257             : 
     258             : #endif /* ZEPHYR_INCLUDE_DRIVERS_WATCHDOG_H_ */