include/linux/watchdog.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  *      Generic watchdog defines. Derived from..
   4  *
   5  * Berkshire PC Watchdog Defines
   6  * by Ken Hollis <khollis@bitgate.com>
   7  *
   8  */
   9 #ifndef _LINUX_WATCHDOG_H
  10 #define _LINUX_WATCHDOG_H
  11
  12
  13 #include <linux/bitops.h>
  14 #include <linux/cdev.h>
  15 #include <linux/device.h>
  16 #include <linux/kernel.h>
  17 #include <linux/notifier.h>
  18 #include <uapi/linux/watchdog.h>
  19
  20 struct watchdog_ops;
  21 struct watchdog_device;
  22 struct watchdog_core_data;
  23 struct watchdog_governor;
  24
  25 /** struct watchdog_ops - The watchdog-devices operations
  26  *
  27  * @owner:      The module owner.
  28  * @start:      The routine for starting the watchdog device.
  29  * @stop:       The routine for stopping the watchdog device.
  30  * @ping:       The routine that sends a keepalive ping to the watchdog device.
  31  * @status:     The routine that shows the status of the watchdog device.
  32  * @set_timeout:The routine for setting the watchdog devices timeout value (in seconds).
  33  * @set_pretimeout:The routine for setting the watchdog devices pretimeout.
  34  * @get_timeleft:The routine that gets the time left before a reset (in seconds).
  35  * @restart:    The routine for restarting the machine.
  36  * @ioctl:      The routines that handles extra ioctl calls.
  37  *
  38  * The watchdog_ops structure contains a list of low-level operations
  39  * that control a watchdog device. It also contains the module that owns
  40  * these operations. The start function is mandatory, all other
  41  * functions are optional.
  42  */
  43 struct watchdog_ops {
  44         struct module *owner;
  45         /* mandatory operations */
  46         int (*start)(struct watchdog_device *);
  47         /* optional operations */
  48         int (*stop)(struct watchdog_device *);
  49         int (*ping)(struct watchdog_device *);
  50         unsigned int (*status)(struct watchdog_device *);
  51         int (*set_timeout)(struct watchdog_device *, unsigned int);
  52         int (*set_pretimeout)(struct watchdog_device *, unsigned int);
  53         unsigned int (*get_timeleft)(struct watchdog_device *);
  54         int (*restart)(struct watchdog_device *, unsigned long, void *);
  55         long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long);
  56 };
  57
  58 /** struct watchdog_device - The structure that defines a watchdog device
  59  *
  60  * @id:         The watchdog's ID. (Allocated by watchdog_register_device)
  61  * @parent:     The parent bus device
  62  * @groups:     List of sysfs attribute groups to create when creating the
  63  *              watchdog device.
  64  * @info:       Pointer to a watchdog_info structure.
  65  * @ops:        Pointer to the list of watchdog operations.
  66  * @gov:        Pointer to watchdog pretimeout governor.
  67  * @bootstatus: Status of the watchdog device at boot.
  68  * @timeout:    The watchdog devices timeout value (in seconds).
  69  * @pretimeout: The watchdog devices pre_timeout value.
  70  * @min_timeout:The watchdog devices minimum timeout value (in seconds).
  71  * @max_timeout:The watchdog devices maximum timeout value (in seconds)
  72  *              as configurable from user space. Only relevant if
  73  *              max_hw_heartbeat_ms is not provided.
  74  * @min_hw_heartbeat_ms:
  75  *              Hardware limit for minimum time between heartbeats,
  76  *              in milli-seconds.
  77  * @max_hw_heartbeat_ms:
  78  *              Hardware limit for maximum timeout, in milli-seconds.
  79  *              Replaces max_timeout if specified.
  80  * @reboot_nb:  The notifier block to stop watchdog on reboot.
  81  * @restart_nb: The notifier block to register a restart function.
  82  * @driver_data:Pointer to the drivers private data.
  83  * @wd_data:    Pointer to watchdog core internal data.
  84  * @status:     Field that contains the devices internal status bits.
  85  * @deferred:   Entry in wtd_deferred_reg_list which is used to
  86  *              register early initialized watchdogs.
  87  *
  88  * The watchdog_device structure contains all information about a
  89  * watchdog timer device.
  90  *
  91  * The driver-data field may not be accessed directly. It must be accessed
  92  * via the watchdog_set_drvdata and watchdog_get_drvdata helpers.
  93  */
  94 struct watchdog_device {
  95         int id;
  96         struct device *parent;
  97         const struct attribute_group **groups;
  98         const struct watchdog_info *info;
  99         const struct watchdog_ops *ops;
 100         const struct watchdog_governor *gov;
 101         unsigned int bootstatus;
 102         unsigned int timeout;
 103         unsigned int pretimeout;
 104         unsigned int min_timeout;
 105         unsigned int max_timeout;
 106         unsigned int min_hw_heartbeat_ms;
 107         unsigned int max_hw_heartbeat_ms;
 108         struct notifier_block reboot_nb;
 109         struct notifier_block restart_nb;
 110         struct notifier_block pm_nb;
 111         void *driver_data;
 112         struct watchdog_core_data *wd_data;
 113         unsigned long status;
 114 /* Bit numbers for status flags */
 115 #define WDOG_ACTIVE             0       /* Is the watchdog running/active */
 116 #define WDOG_NO_WAY_OUT         1       /* Is 'nowayout' feature set ? */
 117 #define WDOG_STOP_ON_REBOOT     2       /* Should be stopped on reboot */
 118 #define WDOG_HW_RUNNING         3       /* True if HW watchdog running */
 119 #define WDOG_STOP_ON_UNREGISTER 4       /* Should be stopped on unregister */
 120 #define WDOG_NO_PING_ON_SUSPEND 5       /* Ping worker should be stopped on suspend */
 121         struct list_head deferred;
 122 };
 123
 124 #define WATCHDOG_NOWAYOUT               IS_BUILTIN(CONFIG_WATCHDOG_NOWAYOUT)
 125 #define WATCHDOG_NOWAYOUT_INIT_STATUS   (WATCHDOG_NOWAYOUT << WDOG_NO_WAY_OUT)
 126
 127 /* Use the following function to check whether or not the watchdog is active */
 128 static inline bool watchdog_active(struct watchdog_device *wdd)
 129 {
 130         return test_bit(WDOG_ACTIVE, &wdd->status);
 131 }
 132
 133 /*
 134  * Use the following function to check whether or not the hardware watchdog
 135  * is running
 136  */
 137 static inline bool watchdog_hw_running(struct watchdog_device *wdd)
 138 {
 139         return test_bit(WDOG_HW_RUNNING, &wdd->status);
 140 }
 141
 142 /* Use the following function to set the nowayout feature */
 143 static inline void watchdog_set_nowayout(struct watchdog_device *wdd, bool nowayout)
 144 {
 145         if (nowayout)
 146                 set_bit(WDOG_NO_WAY_OUT, &wdd->status);
 147 }
 148
 149 /* Use the following function to stop the watchdog on reboot */
 150 static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd)
 151 {
 152         set_bit(WDOG_STOP_ON_REBOOT, &wdd->status);
 153 }
 154
 155 /* Use the following function to stop the watchdog when unregistering it */
 156 static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd)
 157 {
 158         set_bit(WDOG_STOP_ON_UNREGISTER, &wdd->status);
 159 }
 160
 161 /* Use the following function to stop the wdog ping worker when suspending */
 162 static inline void watchdog_stop_ping_on_suspend(struct watchdog_device *wdd)
 163 {
 164         set_bit(WDOG_NO_PING_ON_SUSPEND, &wdd->status);
 165 }
 166
 167 /* Use the following function to check if a timeout value is invalid */
 168 static inline bool watchdog_timeout_invalid(struct watchdog_device *wdd, unsigned int t)
 169 {
 170         /*
 171          * The timeout is invalid if
 172          * - the requested value is larger than UINT_MAX / 1000
 173          *   (since internal calculations are done in milli-seconds),
 174          * or
 175          * - the requested value is smaller than the configured minimum timeout,
 176          * or
 177          * - a maximum hardware timeout is not configured, a maximum timeout
 178          *   is configured, and the requested value is larger than the
 179          *   configured maximum timeout.
 180          */
 181         return t > UINT_MAX / 1000 || t < wdd->min_timeout ||
 182                 (!wdd->max_hw_heartbeat_ms && wdd->max_timeout &&
 183                  t > wdd->max_timeout);
 184 }
 185
 186 /* Use the following function to check if a pretimeout value is invalid */
 187 static inline bool watchdog_pretimeout_invalid(struct watchdog_device *wdd,
 188                                                unsigned int t)
 189 {
 190         return t && wdd->timeout && t >= wdd->timeout;
 191 }
 192
 193 /* Use the following functions to manipulate watchdog driver specific data */
 194 static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data)
 195 {
 196         wdd->driver_data = data;
 197 }
 198
 199 static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
 200 {
 201         return wdd->driver_data;
 202 }
 203
 204 /* Use the following functions to report watchdog pretimeout event */
 205 #if IS_ENABLED(CONFIG_WATCHDOG_PRETIMEOUT_GOV)
 206 void watchdog_notify_pretimeout(struct watchdog_device *wdd);
 207 #else
 208 static inline void watchdog_notify_pretimeout(struct watchdog_device *wdd)
 209 {
 210         pr_alert("watchdog%d: pretimeout event\n", wdd->id);
 211 }
 212 #endif
 213
 214 /* drivers/watchdog/watchdog_core.c */
 215 void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
 216 extern int watchdog_init_timeout(struct watchdog_device *wdd,
 217                                   unsigned int timeout_parm, struct device *dev);
 218 extern int watchdog_register_device(struct watchdog_device *);
 219 extern void watchdog_unregister_device(struct watchdog_device *);
 220 int watchdog_dev_suspend(struct watchdog_device *wdd);
 221 int watchdog_dev_resume(struct watchdog_device *wdd);
 222
 223 int watchdog_set_last_hw_keepalive(struct watchdog_device *, unsigned int);
 224
 225 /* devres register variant */
 226 int devm_watchdog_register_device(struct device *dev, struct watchdog_device *);
 227
 228 #endif  /* ifndef _LINUX_WATCHDOG_H */