drivers: watchdog: Watchdog API redesign

New API enables setting watchdog timeout in the unit of microseconds.
It is possible to configure watchdog timer behavior in CPU sleep state
as well as when it is halted by the debugger.
It supports watchdogs with multiple reload channels.

Jira: ZEP-2564

Signed-off-by: Michał Kruszewski <michal.kruszewski@nordicsemi.no>
Signed-off-by: Karol Lasończyk <karol.lasonczyk@nordicsemi.no>

doc/api/api.rst

@@ -21,6 +21,7 @@ The Zephyr APIs are used the same way on all SoCs and boards.
    bluetooth.rst
    networking.rst
    io_interfaces.rst
+   timer_counter_interfaces.rst
    power_management_api
    file_system
    display_api

doc/api/timer_counter_interfaces.rst

@@ -0,0 +1,15 @@
+.. _timer_counter_interfaces:
+
+Timer / Counter Driver APIs
+###########################
+
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: top
+
+Watchdog Interface
+******************
+
+.. doxygengroup:: watchdog_interface
+   :project: Zephyr

drivers/watchdog/Kconfig

@@ -1,23 +1,50 @@
 # Kconfig - Watchdog configuration options
 #
-#
 # Copyright (c) 2015 Intel Corporation
+# Copyright (c) 2017 Nordic Semiconductor ASA
 #
 # SPDX-License-Identifier: Apache-2.0
 #
 
-#
-# Watchdog options
-#
 menuconfig WATCHDOG
 	bool
 	prompt "Watchdog Support"
-	default n
 	help
 	  Include support for watchdogs.
 
 if WATCHDOG
 
+config WDT_DISABLE_AT_BOOT
+	bool
+	prompt "Disable at boot"
+	help
+	  Disable watchdog at Zephyr system startup.
+
+config SYS_LOG_WDT_LEVEL
+	int
+	prompt "Watchdog Driver Log level"
+	depends on SYS_LOG
+	default 0
+	range 0 4
+	help
+	  Sets log level for Watchdog drivers.
+	  Levels are:
+	  0 OFF, do not write
+	  1 ERROR, only write SYS_LOG_ERR
+	  2 WARNING, write SYS_LOG_WRN in addition to previous level
+	  3 INFO, write SYS_LOG_INF in addition to previous levels
+	  4 DEBUG, write SYS_LOG_DBG in addition to previous levels
+
+config HAS_WDT_MULTISTAGE
+	bool
+
+config WDT_MULTISTAGE
+	bool
+	prompt "Enable multistage timeouts"
+	depends on HAS_WDT_MULTISTAGE
+	help
+	  Enable multistage operation of watchdog timeouts.
+
 source "drivers/watchdog/Kconfig.qmsi"
 
 source "drivers/watchdog/Kconfig.stm32"

drivers/watchdog/iwdg_stm32.c

@@ -68,10 +68,12 @@ static void iwdg_stm32_enable(struct device *dev)
 	LL_IWDG_Enable(iwdg);
 }
 
-static void iwdg_stm32_disable(struct device *dev)
+static int iwdg_stm32_disable(struct device *dev)
 {
 	/* watchdog cannot be stopped once started */
 	ARG_UNUSED(dev);
+
+	return 0;
 }
 
 static int iwdg_stm32_set_config(struct device *dev,

drivers/watchdog/wdog_cmsdk_apb.c

@@ -87,7 +87,7 @@ static void wdog_cmsdk_apb_enable(struct device *dev)
 	wdog->ctrl = (CMSDK_APB_WDOG_CTRL_RESEN | CMSDK_APB_WDOG_CTRL_INTEN);
 }
 
-static void wdog_cmsdk_apb_disable(struct device *dev)
+static int wdog_cmsdk_apb_disable(struct device *dev)
 {
 	volatile struct wdog_cmsdk_apb *wdog = WDOG_STRUCT;
 
@@ -95,6 +95,8 @@ static void wdog_cmsdk_apb_disable(struct device *dev)
 
 	/* Stop the watchdog counter with INTEN bit */
 	wdog->ctrl = ~(CMSDK_APB_WDOG_CTRL_RESEN | CMSDK_APB_WDOG_CTRL_INTEN);
+
+	return 0;
 }
 
 static int wdog_cmsdk_apb_set_config(struct device *dev,

drivers/watchdog/wdt_esp32.c

@@ -48,7 +48,7 @@ static void wdt_esp32_enable(struct device *dev)
 	wdt_esp32_seal();
 }
 
-static void wdt_esp32_disable(struct device *dev)
+static int wdt_esp32_disable(struct device *dev)
 {
 	volatile u32_t *reg = (u32_t *)TIMG_WDTCONFIG0_REG(1);
 
@@ -57,6 +57,8 @@ static void wdt_esp32_disable(struct device *dev)
 	wdt_esp32_unseal();
 	*reg &= ~BIT(TIMG_WDT_EN_S);
 	wdt_esp32_seal();
+
+	return 0;
 }
 
 static void adjust_timeout(u32_t timeout)

drivers/watchdog/wdt_qmsi.c

@@ -94,9 +94,11 @@ static void enable(struct device *dev)
 	clk_periph_enable(CLK_PERIPH_WDT_REGISTER | CLK_PERIPH_CLK);
 }
 
-static void disable(struct device *dev)
+static int disable(struct device *dev)
 {
 	clk_periph_disable(CLK_PERIPH_WDT_REGISTER);
+
+	return 0;
 }
 
 static const struct wdt_driver_api api = {

drivers/watchdog/wdt_sam.c

@@ -36,11 +36,13 @@ static void wdt_sam_enable(struct device *dev)
 	SYS_LOG_ERR("Function not implemented!");
 }
 
-static void wdt_sam_disable(struct device *dev)
+static int wdt_sam_disable(struct device *dev)
 {
 	Wdt *const wdt = DEV_CFG(dev)->regs;
 
 	wdt->WDT_MR |= WDT_MR_WDDIS;
+
+	return 0;
 }
 
 static int wdt_sam_set_config(struct device *dev, struct wdt_config *config)

drivers/watchdog/wdt_sam0.c

@@ -37,10 +37,12 @@ static void wdt_sam0_enable(struct device *dev)
 	wdt_sam0_wait_synchronization();
 }
 
-static void wdt_sam0_disable(struct device *dev)
+static int wdt_sam0_disable(struct device *dev)
 {
 	WDT_REGS->CTRL.reg = 0;
 	wdt_sam0_wait_synchronization();
+
+	return 0;
 }
 
 static int wdt_sam0_set_config(struct device *dev, struct wdt_config *config)

include/watchdog.h

@@ -1,23 +1,40 @@
 /*
- * Copyright (c) 2015 Intel Corporation.
+ * Copyright (c) 2017 Nordic Semiconductor ASA
+ * Copyright (c) 2015 Intel Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @brief Public API for watchdog drivers.
+ */
+
 #ifndef _WDT_H_
 #define _WDT_H_
 
+/**
+ * @brief Watchdog Interface
+ * @defgroup watchdog_interface Watchdog Interface
+ * @ingroup timer_counter_interfaces
+ * @{
+ */
+
 #include <zephyr/types.h>
-#include <device.h>
 #include <misc/util.h>
+#include <device.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @name Deprecated Watchdog API types.
+ * @{
+ */
 #define WDT_MODE		(BIT(1))
-#define WDT_MODE_OFFSET         (1)
+#define WDT_MODE_OFFSET		(1)
-#define WDT_TIMEOUT_MASK        (0xF)
+#define WDT_TIMEOUT_MASK	(0xF)
 
 enum wdt_mode {
 	WDT_MODE_RESET = 0,
@@ -46,7 +63,6 @@ enum wdt_clock_timeout_cycles {
 	WDT_2_31_CYCLES
 };
 
-
 /**
  * WDT configuration struct.
  */
@@ -55,24 +71,257 @@ struct wdt_config {
 	enum wdt_mode mode;
 	void (*interrupt_fn)(struct device *dev);
 };
+/**
+ * @}
+ */
 
+
+/**
+ * @brief Pause watchdog timer when CPU is in sleep state.
+ */
+#define WDT_OPT_PAUSE_IN_SLEEP	BIT(0)
+
+/**
+ * @brief Pause watchdog timer when CPU is halted by the debugger.
+ */
+#define WDT_OPT_PAUSE_HALTED_BY_DBG	BIT(1)
+
+/**
+ * @brief Watchdog reset flag bit field mask shift.
+ */
+#define WDT_FLAG_RESET_SHIFT		(0)
+/**
+ * @brief Watchdog reset flag bit field mask.
+ */
+#define WDT_FLAG_RESET_MASK		(0x3 << WDT_FLAG_RESET_SHIFT)
+
+/**
+ * @name Watchdog Reset Behavior.
+ * Reset behavior after timeout.
+ * @{
+ */
+/** No reset */
+#define WDT_FLAG_RESET_NONE		(0 << WDT_FLAG_RESET_SHIFT)
+/** CPU core reset */
+#define WDT_FLAG_RESET_CPU_CORE		(1 << WDT_FLAG_RESET_SHIFT)
+/** Global SoC reset */
+#define WDT_FLAG_RESET_SOC		(2 << WDT_FLAG_RESET_SHIFT)
+/**
+ * @}
+ */
+
+/**
+ * @brief Watchdog timeout window.
+ *
+ * Each installed timeout needs feeding within the specified time window,
+ * otherwise the watchdog will trigger. If the watchdog instance does not
+ * support window timeouts then min value must be equal to 0.
+ *
+ * @param min Lower limit of watchdog feed timeout in milliseconds.
+ * @param max Upper limit of watchdog feed timeout in milliseconds.
+ *
+ * @note If specified values can not be precisely set they are always
+ *	 rounded up.
+ */
+struct wdt_window {
+	u32_t min;
+	u32_t max;
+};
+
+/** Watchdog callback. */
+typedef void (*wdt_callback_t)(struct device *dev, int channel_id);
+
+/**
+ * @brief Watchdog timeout configuration struct.
+ *
+ * @param window Timing parameters of watchdog timeout.
+ * @param callback Timeout callback. Passing NULL means that no callback
+ *		   will be run.
+ * @param next Pointer to the next timeout configuration. This pointer is used
+ *	       for watchdogs with staged timeouts functionality. Value must be
+ *	       NULL for single stage timeout.
+ * @param flags Bit field with following parts:
+ *
+ *     reset        [ 0 : 1 ]   - perform specified reset after timeout/callback
+ */
+struct wdt_timeout_cfg {
+	struct wdt_window window;
+	wdt_callback_t callback;
+#ifdef CONFIG_WDT_MULTISTAGE
+	struct wdt_timeout_cfg *next;
+#endif
+	u8_t flags;
+};
+
+/**
+ * @typedef wdt_api_setup
+ * @brief Callback API for setting up watchdog instance.
+ * See wdt_setup() for argument descriptions
+ */
+typedef int (*wdt_api_setup)(struct device *dev, u8_t options);
+
+/**
+ * @typedef wdt_api_disable
+ * @brief Callback API for disabling watchdog instance.
+ * See wdt_disable() for argument descriptions
+ */
+typedef int (*wdt_api_disable)(struct device *dev);
+
+/**
+ * @typedef wdt_api_install_timeout
+ * @brief Callback API for installing new timeout.
+ * See wdt_install_timeout() for argument descriptions
+ */
+typedef int (*wdt_api_install_timeout)(struct device *dev,
+				       const struct wdt_timeout_cfg *cfg);
+
+/**
+ * @typedef wdt_api_feed
+ * @brief Callback API for feeding specified watchdog timeout.
+ * See (wdt_feed) for argument descriptions
+ */
+typedef int (*wdt_api_feed)(struct device *dev, int channel_id);
+
+/**
+ * @typedef wdt_api_enable
+ * @brief Callback API for enabling watchdog.
+ * See wdt_enable() for argument descriptions. Please note that this function
+ * is deprecated.
+ */
 typedef void (*wdt_api_enable)(struct device *dev);
-typedef void (*wdt_api_disable)(struct device *dev);
+
-typedef int (*wdt_api_set_config)(struct device *dev,
+/**
-				  struct wdt_config *config);
+ * @typedef wdt_api_get_config
+ * @brief Callback API for getting current watchdog configuration.
+ * See wdt_get_config() for argument descriptions. Please note that this
+ * function is deprecated.
+ */
 typedef void (*wdt_api_get_config)(struct device *dev,
 				   struct wdt_config *config);
+
+/**
+ * @typedef wdt_api_set_config
+ * @brief Callback API for setting current watchdog configuration.
+ * See wdt_set_config() for argument descriptions. Please note that this
+ * function is deprecated.
+ */
+typedef int (*wdt_api_set_config)(struct device *dev,
+				  struct wdt_config *config);
+
+/**
+ * @typedef wdt_api_reload
+ * @brief Callback API for reloading watchdog.
+ * See wdt_reload() for argument descriptions. Please note that this function
+ * is deprecated.
+ */
 typedef void (*wdt_api_reload)(struct device *dev);
 
+/** @cond INTERNAL_HIDDEN */
 struct wdt_driver_api {
-	wdt_api_enable enable;
+	wdt_api_setup setup;
 	wdt_api_disable disable;
+	wdt_api_install_timeout install_timeout;
+	wdt_api_feed feed;
+	/** Deprecated functions */
+	wdt_api_enable enable;
 	wdt_api_get_config get_config;
 	wdt_api_set_config set_config;
 	wdt_api_reload reload;
 };
+/**
+ * @endcond
+ */
 
-static inline void wdt_enable(struct device *dev)
+/**
+ * @brief Set up watchdog instance.
+ *
+ * This function is used for configuring global watchdog settings that
+ * affect all timeouts. It should be called after installing timeouts.
+ * After successful return, all installed timeouts are valid and must be
+ * serviced periodically by callig wdt_feed().
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param options Configuration options as defined by the WDT_OPT_* constants
+ *
+ * @retval 0 If successful.
+ * @retval -ENOTSUP If any of the set options is not supported.
+ * @retval -EBUSY If watchdog instance has been already setup.
+ */
+static inline int wdt_setup(struct device *dev, u8_t options)
+{
+	const struct wdt_driver_api *api =
+		(const struct wdt_driver_api *)dev->driver_api;
+
+	return api->setup(dev, options);
+}
+
+/**
+ * @brief Disable watchdog instance.
+ *
+ * This function disables the watchdog instance and automatically uninstalls all
+ * timeouts. To set up a new watchdog, install timeouts and call wdt_setup()
+ * again. Not all watchdogs can be restarted after they are disabled.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ *
+ * @retval 0 If successful.
+ * @retval -EFAULT If watchdog instance is not enabled.
+ * @retval -EPERM If watchdog can not be disabled directly by application code.
+ */
+static inline int wdt_disable(struct device *dev)
+{
+	const struct wdt_driver_api *api =
+		(const struct wdt_driver_api *)dev->driver_api;
+
+	return api->disable(dev);
+}
+
+/**
+ * @brief Install new timeout.
+ *
+ * This function must be used before wdt_setup(). Changes applied here
+ * have no effects until wdt_setup() is called.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param cfg Pointer to timeout configuration structure.
+ *
+ * @retval 0 If successful.
+ * @retval -EBUSY If timeout can not be installed while watchdog has already
+ *		  been setup.
+ * @retval -ENOMEM If no more timeouts can be installed.
+ * @retval -ENOTSUP If any of the set flags is not supported.
+ * @retval -EINVAL If any of the window timeout value is out of possible range.
+ *		   This value is also returned if watchdog supports only one
+ *		   timeout value for all timeouts and the supplied timeout
+ *		   window differs from windows for alarms installed so far.
+ */
+static inline int wdt_install_timeout(struct device *dev,
+				      const struct wdt_timeout_cfg *cfg)
+{
+	const struct wdt_driver_api *api =
+		(const struct wdt_driver_api *) dev->driver_api;
+
+	return api->install_timeout(dev, cfg);
+}
+
+/**
+ * @brief Feed specified watchdog timeout.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param channel_id Index of the feeded channel.
+ *
+ * @retval 0 If successful.
+ * @retval -EINVAL If there is no installed timeout for supplied channel.
+ */
+static inline int wdt_feed(struct device *dev, int channel_id)
+{
+	const struct wdt_driver_api *api =
+		(const struct wdt_driver_api *)dev->driver_api;
+
+	return api->feed(dev, channel_id);
+}
+
+static inline void __deprecated wdt_enable(struct device *dev)
 {
 	const struct wdt_driver_api *api =
 		(const struct wdt_driver_api *)dev->driver_api;
@@ -80,15 +329,7 @@ static inline void wdt_enable(struct device *dev)
 	api->enable(dev);
 }
 
-static inline void wdt_disable(struct device *dev)
+static inline void __deprecated wdt_get_config(struct device *dev,
-{
-	const struct wdt_driver_api *api =
-		(const struct wdt_driver_api *)dev->driver_api;
-
-	api->disable(dev);
-}
-
-static inline void wdt_get_config(struct device *dev,
 				  struct wdt_config *config)
 {
 	const struct wdt_driver_api *api =
@@ -97,7 +338,7 @@ static inline void wdt_get_config(struct device *dev,
 	api->get_config(dev, config);
 }
 
-static inline int wdt_set_config(struct device *dev,
+static inline int __deprecated wdt_set_config(struct device *dev,
 				 struct wdt_config *config)
 {
 	const struct wdt_driver_api *api =
@@ -106,16 +347,19 @@ static inline int wdt_set_config(struct device *dev,
 	return api->set_config(dev, config);
 }
 
-static inline void wdt_reload(struct device *dev)
+static inline void __deprecated wdt_reload(struct device *dev)
 {
 	const struct wdt_driver_api *api =
 		(const struct wdt_driver_api *)dev->driver_api;
 
 	api->reload(dev);
 }
-
 #ifdef __cplusplus
 }
 #endif
 
-#endif
+/**
+ * @}
+ */
+
+#endif /* __WDT_H__ */