LXR linux/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
  20struct watchdog_ops;
  21struct watchdog_device;
  22struct watchdog_core_data;
  23struct 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 and stop function are mandatory, all other
  41 * functions are optional.
  42 */
  43struct watchdog_ops {
  44        struct module *owner;
  45        /* mandatory operations */
  46        int (*start)(struct watchdog_device *);
  47        int (*stop)(struct watchdog_device *);
  48        /* optional operations */
  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 */
  94struct 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        void *driver_data;
 111        struct watchdog_core_data *wd_data;
 112        unsigned long status;
 113/* Bit numbers for status flags */
 114#define WDOG_ACTIVE             0       /* Is the watchdog running/active */
 115#define WDOG_NO_WAY_OUT         1       /* Is 'nowayout' feature set ? */
 116#define WDOG_STOP_ON_REBOOT     2       /* Should be stopped on reboot */
 117#define WDOG_HW_RUNNING         3       /* True if HW watchdog running */
 118#define WDOG_STOP_ON_UNREGISTER 4       /* Should be stopped on unregister */
 119        struct list_head deferred;
 120};
 121
 122#define WATCHDOG_NOWAYOUT               IS_BUILTIN(CONFIG_WATCHDOG_NOWAYOUT)
 123#define WATCHDOG_NOWAYOUT_INIT_STATUS   (WATCHDOG_NOWAYOUT << WDOG_NO_WAY_OUT)
 124
 125/* Use the following function to check whether or not the watchdog is active */
 126static inline bool watchdog_active(struct watchdog_device *wdd)
 127{
 128        return test_bit(WDOG_ACTIVE, &wdd->status);
 129}
 130
 131/*
 132 * Use the following function to check whether or not the hardware watchdog
 133 * is running
 134 */
 135static inline bool watchdog_hw_running(struct watchdog_device *wdd)
 136{
 137        return test_bit(WDOG_HW_RUNNING, &wdd->status);
 138}
 139
 140/* Use the following function to set the nowayout feature */
 141static inline void watchdog_set_nowayout(struct watchdog_device *wdd, bool nowayout)
 142{
 143        if (nowayout)
 144                set_bit(WDOG_NO_WAY_OUT, &wdd->status);
 145}
 146
 147/* Use the following function to stop the watchdog on reboot */
 148static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd)
 149{
 150        set_bit(WDOG_STOP_ON_REBOOT, &wdd->status);
 151}
 152
 153/* Use the following function to stop the watchdog when unregistering it */
 154static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd)
 155{
 156        set_bit(WDOG_STOP_ON_UNREGISTER, &wdd->status);
 157}
 158
 159/* Use the following function to check if a timeout value is invalid */
 160static inline bool watchdog_timeout_invalid(struct watchdog_device *wdd, unsigned int t)
 161{
 162        /*
 163         * The timeout is invalid if
 164         * - the requested value is larger than UINT_MAX / 1000
 165         *   (since internal calculations are done in milli-seconds),
 166         * or
 167         * - the requested value is smaller than the configured minimum timeout,
 168         * or
 169         * - a maximum hardware timeout is not configured, a maximum timeout
 170         *   is configured, and the requested value is larger than the
 171         *   configured maximum timeout.
 172         */
 173        return t > UINT_MAX / 1000 || t < wdd->min_timeout ||
 174                (!wdd->max_hw_heartbeat_ms && wdd->max_timeout &&
 175                 t > wdd->max_timeout);
 176}
 177
 178/* Use the following function to check if a pretimeout value is invalid */
 179static inline bool watchdog_pretimeout_invalid(struct watchdog_device *wdd,
 180                                               unsigned int t)
 181{
 182        return t && wdd->timeout && t >= wdd->timeout;
 183}
 184
 185/* Use the following functions to manipulate watchdog driver specific data */
 186static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data)
 187{
 188        wdd->driver_data = data;
 189}
 190
 191static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
 192{
 193        return wdd->driver_data;
 194}
 195
 196/* Use the following functions to report watchdog pretimeout event */
 197#if IS_ENABLED(CONFIG_WATCHDOG_PRETIMEOUT_GOV)
 198void watchdog_notify_pretimeout(struct watchdog_device *wdd);
 199#else
 200static inline void watchdog_notify_pretimeout(struct watchdog_device *wdd)
 201{
 202        pr_alert("watchdog%d: pretimeout event\n", wdd->id);
 203}
 204#endif
 205
 206/* drivers/watchdog/watchdog_core.c */
 207void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
 208extern int watchdog_init_timeout(struct watchdog_device *wdd,
 209                                  unsigned int timeout_parm, struct device *dev);
 210extern int watchdog_register_device(struct watchdog_device *);
 211extern void watchdog_unregister_device(struct watchdog_device *);
 212
 213/* devres register variant */
 214int devm_watchdog_register_device(struct device *dev, struct watchdog_device *);
 215
 216#endif  /* ifndef _LINUX_WATCHDOG_H */
 217