^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) The Linux WatchDog Timer Driver Core kernel API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Last reviewed: 12-Feb-2013
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Wim Van Sebroeck <wim@iguana.be>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This document does not describe what a WatchDog Timer (WDT) Driver or Device is.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) It also does not describe the API which can be used by user space to communicate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) with a WatchDog Timer. If you want to know this then please read the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) file: Documentation/watchdog/watchdog-api.rst .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) So what does this document describe? It describes the API that can be used by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) WatchDog Timer Drivers that want to use the WatchDog Timer Driver Core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Framework. This framework provides all interfacing towards user space so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) the same code does not have to be reproduced each time. This also means that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) a watchdog timer driver then only needs to provide the different routines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) (operations) that control the watchdog timer (WDT).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) The API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) Each watchdog timer driver that wants to use the WatchDog Timer Driver Core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) must #include <linux/watchdog.h> (you would have to do this anyway when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) writing a watchdog device driver). This include file contains following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) register/unregister routines::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) extern int watchdog_register_device(struct watchdog_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) extern void watchdog_unregister_device(struct watchdog_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) The watchdog_register_device routine registers a watchdog timer device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) The parameter of this routine is a pointer to a watchdog_device structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) This routine returns zero on success and a negative errno code for failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) The watchdog_unregister_device routine deregisters a registered watchdog timer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) device. The parameter of this routine is the pointer to the registered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) watchdog_device structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) The watchdog subsystem includes an registration deferral mechanism,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) which allows you to register an watchdog as early as you wish during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) the boot process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) The watchdog device structure looks like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) struct watchdog_device {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) int id;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) struct device *parent;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) const struct attribute_group **groups;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) const struct watchdog_info *info;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) const struct watchdog_ops *ops;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) const struct watchdog_governor *gov;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) unsigned int bootstatus;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) unsigned int timeout;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) unsigned int pretimeout;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) unsigned int min_timeout;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) unsigned int max_timeout;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) unsigned int min_hw_heartbeat_ms;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) unsigned int max_hw_heartbeat_ms;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) struct notifier_block reboot_nb;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) struct notifier_block restart_nb;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) void *driver_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) struct watchdog_core_data *wd_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) unsigned long status;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) struct list_head deferred;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) It contains following fields:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) * id: set by watchdog_register_device, id 0 is special. It has both a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) /dev/watchdog0 cdev (dynamic major, minor 0) as well as the old
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) /dev/watchdog miscdev. The id is set automatically when calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) watchdog_register_device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) * parent: set this to the parent device (or NULL) before calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) watchdog_register_device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) * groups: List of sysfs attribute groups to create when creating the watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) * info: a pointer to a watchdog_info structure. This structure gives some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) additional information about the watchdog timer itself. (Like it's unique name)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) * ops: a pointer to the list of watchdog operations that the watchdog supports.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) * gov: a pointer to the assigned watchdog device pretimeout governor or NULL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) * timeout: the watchdog timer's timeout value (in seconds).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) This is the time after which the system will reboot if user space does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) not send a heartbeat request if WDOG_ACTIVE is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) * pretimeout: the watchdog timer's pretimeout value (in seconds).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) * min_timeout: the watchdog timer's minimum timeout value (in seconds).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) If set, the minimum configurable value for 'timeout'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) * max_timeout: the watchdog timer's maximum timeout value (in seconds),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) as seen from userspace. If set, the maximum configurable value for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) 'timeout'. Not used if max_hw_heartbeat_ms is non-zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) * min_hw_heartbeat_ms: Hardware limit for minimum time between heartbeats,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) in milli-seconds. This value is normally 0; it should only be provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) if the hardware can not tolerate lower intervals between heartbeats.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) * max_hw_heartbeat_ms: Maximum hardware heartbeat, in milli-seconds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) If set, the infrastructure will send heartbeats to the watchdog driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) if 'timeout' is larger than max_hw_heartbeat_ms, unless WDOG_ACTIVE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) is set and userspace failed to send a heartbeat for at least 'timeout'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) seconds. max_hw_heartbeat_ms must be set if a driver does not implement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) the stop function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) * reboot_nb: notifier block that is registered for reboot notifications, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) internal use only. If the driver calls watchdog_stop_on_reboot, watchdog core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) will stop the watchdog on such notifications.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) * restart_nb: notifier block that is registered for machine restart, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) internal use only. If a watchdog is capable of restarting the machine, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) should define ops->restart. Priority can be changed through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) watchdog_set_restart_priority.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) * bootstatus: status of the device after booting (reported with watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) WDIOF_* status bits).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) * driver_data: a pointer to the drivers private data of a watchdog device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) This data should only be accessed via the watchdog_set_drvdata and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) watchdog_get_drvdata routines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) * wd_data: a pointer to watchdog core internal data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) * status: this field contains a number of status bits that give extra
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) information about the status of the device (Like: is the watchdog timer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) running/active, or is the nowayout bit set).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) * deferred: entry in wtd_deferred_reg_list which is used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) register early initialized watchdogs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) The list of watchdog operations is defined as::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) struct watchdog_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) struct module *owner;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) /* mandatory operations */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) int (*start)(struct watchdog_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) /* optional operations */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) int (*stop)(struct watchdog_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) int (*ping)(struct watchdog_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) unsigned int (*status)(struct watchdog_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) int (*set_timeout)(struct watchdog_device *, unsigned int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) int (*set_pretimeout)(struct watchdog_device *, unsigned int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) unsigned int (*get_timeleft)(struct watchdog_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) int (*restart)(struct watchdog_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) It is important that you first define the module owner of the watchdog timer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) driver's operations. This module owner will be used to lock the module when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) the watchdog is active. (This to avoid a system crash when you unload the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) module and /dev/watchdog is still open).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) Some operations are mandatory and some are optional. The mandatory operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) * start: this is a pointer to the routine that starts the watchdog timer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) The routine needs a pointer to the watchdog timer device structure as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) parameter. It returns zero on success or a negative errno code for failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Not all watchdog timer hardware supports the same functionality. That's why
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) all other routines/operations are optional. They only need to be provided if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) they are supported. These optional routines/operations are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) * stop: with this routine the watchdog timer device is being stopped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) The routine needs a pointer to the watchdog timer device structure as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) parameter. It returns zero on success or a negative errno code for failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) Some watchdog timer hardware can only be started and not be stopped. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) driver supporting such hardware does not have to implement the stop routine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) If a driver has no stop function, the watchdog core will set WDOG_HW_RUNNING
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) and start calling the driver's keepalive pings function after the watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) device is closed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) If a watchdog driver does not implement the stop function, it must set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) max_hw_heartbeat_ms.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) * ping: this is the routine that sends a keepalive ping to the watchdog timer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) The routine needs a pointer to the watchdog timer device structure as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) parameter. It returns zero on success or a negative errno code for failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) Most hardware that does not support this as a separate function uses the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) start function to restart the watchdog timer hardware. And that's also what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) the watchdog timer driver core does: to send a keepalive ping to the watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) timer hardware it will either use the ping operation (when available) or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) start operation (when the ping operation is not available).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) (Note: the WDIOC_KEEPALIVE ioctl call will only be active when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) WDIOF_KEEPALIVEPING bit has been set in the option field on the watchdog's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) info structure).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) * status: this routine checks the status of the watchdog timer device. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) status of the device is reported with watchdog WDIOF_* status flags/bits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) WDIOF_MAGICCLOSE and WDIOF_KEEPALIVEPING are reported by the watchdog core;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) it is not necessary to report those bits from the driver. Also, if no status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) function is provided by the driver, the watchdog core reports the status bits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) provided in the bootstatus variable of struct watchdog_device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) * set_timeout: this routine checks and changes the timeout of the watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) timer device. It returns 0 on success, -EINVAL for "parameter out of range"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) and -EIO for "could not write value to the watchdog". On success this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) routine should set the timeout value of the watchdog_device to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) achieved timeout value (which may be different from the requested one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) because the watchdog does not necessarily have a 1 second resolution).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) Drivers implementing max_hw_heartbeat_ms set the hardware watchdog heartbeat
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) to the minimum of timeout and max_hw_heartbeat_ms. Those drivers set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) timeout value of the watchdog_device either to the requested timeout value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) (if it is larger than max_hw_heartbeat_ms), or to the achieved timeout value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) (Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) watchdog's info structure).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) If the watchdog driver does not have to perform any action but setting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) watchdog_device.timeout, this callback can be omitted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) If set_timeout is not provided but, WDIOF_SETTIMEOUT is set, the watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) infrastructure updates the timeout value of the watchdog_device internally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) to the requested value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) If the pretimeout feature is used (WDIOF_PRETIMEOUT), then set_timeout must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) also take care of checking if pretimeout is still valid and set up the timer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) accordingly. This can't be done in the core without races, so it is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) duty of the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) * set_pretimeout: this routine checks and changes the pretimeout value of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) the watchdog. It is optional because not all watchdogs support pretimeout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) notification. The timeout value is not an absolute time, but the number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) seconds before the actual timeout would happen. It returns 0 on success,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) -EINVAL for "parameter out of range" and -EIO for "could not write value to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) the watchdog". A value of 0 disables pretimeout notification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) (Note: the WDIOF_PRETIMEOUT needs to be set in the options field of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) watchdog's info structure).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) If the watchdog driver does not have to perform any action but setting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) watchdog_device.pretimeout, this callback can be omitted. That means if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) set_pretimeout is not provided but WDIOF_PRETIMEOUT is set, the watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) infrastructure updates the pretimeout value of the watchdog_device internally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) to the requested value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) * get_timeleft: this routines returns the time that's left before a reset.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) * restart: this routine restarts the machine. It returns 0 on success or a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) negative errno code for failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) * ioctl: if this routine is present then it will be called first before we do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) our own internal ioctl call handling. This routine should return -ENOIOCTLCMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) if a command is not supported. The parameters that are passed to the ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) call are: watchdog_device, cmd and arg.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) The status bits should (preferably) be set with the set_bit and clear_bit alike
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) bit-operations. The status bits that are defined are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) * WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) is active or not from user perspective. User space is expected to send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) heartbeat requests to the driver while this flag is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) * WDOG_NO_WAY_OUT: this bit stores the nowayout setting for the watchdog.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) If this bit is set then the watchdog timer will not be able to stop.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) * WDOG_HW_RUNNING: Set by the watchdog driver if the hardware watchdog is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) running. The bit must be set if the watchdog timer hardware can not be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) stopped. The bit may also be set if the watchdog timer is running after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) booting, before the watchdog device is opened. If set, the watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) infrastructure will send keepalives to the watchdog hardware while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) WDOG_ACTIVE is not set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) Note: when you register the watchdog timer device with this bit set,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) then opening /dev/watchdog will skip the start operation but send a keepalive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) request instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) timer device) you can either:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) * set it statically in your watchdog_device struct with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) .status = WATCHDOG_NOWAYOUT_INIT_STATUS,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) (this will set the value the same as CONFIG_WATCHDOG_NOWAYOUT) or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) * use the following helper function::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) static inline void watchdog_set_nowayout(struct watchdog_device *wdd,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) int nowayout)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) Note:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) The WatchDog Timer Driver Core supports the magic close feature and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) the nowayout feature. To use the magic close feature you must set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) The nowayout feature will overrule the magic close feature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) To get or set driver specific data the following two helper functions should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) used::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) static inline void watchdog_set_drvdata(struct watchdog_device *wdd,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) void *data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) The watchdog_set_drvdata function allows you to add driver specific data. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) arguments of this function are the watchdog device where you want to add the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) driver specific data to and a pointer to the data itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) The watchdog_get_drvdata function allows you to retrieve driver specific data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) The argument of this function is the watchdog device where you want to retrieve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) data from. The function returns the pointer to the driver specific data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) To initialize the timeout field, the following function can be used::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) extern int watchdog_init_timeout(struct watchdog_device *wdd,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) unsigned int timeout_parm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) The watchdog_init_timeout function allows you to initialize the timeout field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) using the module timeout parameter or by retrieving the timeout-sec property from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) the device tree (if the module timeout parameter is invalid). Best practice is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) to set the default timeout value as timeout value in the watchdog_device and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) then use this function to set the user "preferred" timeout value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) This routine returns zero on success and a negative errno code for failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) To disable the watchdog on reboot, the user must call the following helper::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) To disable the watchdog when unregistering the watchdog, the user must call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) the following helper. Note that this will only stop the watchdog if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) nowayout flag is not set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) To change the priority of the restart handler the following helper should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) used::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) User should follow the following guidelines for setting the priority:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) * 0: should be called in last resort, has limited restart capabilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) * 128: default restart handler, use if no other handler is expected to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) available, and/or if restart is sufficient to restart the entire system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) * 255: highest priority, will preempt all other restart handlers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) To raise a pretimeout notification, the following function should be used::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) void watchdog_notify_pretimeout(struct watchdog_device *wdd)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) The function can be called in the interrupt context. If watchdog pretimeout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) governor framework (kbuild CONFIG_WATCHDOG_PRETIMEOUT_GOV symbol) is enabled,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) an action is taken by a preconfigured pretimeout governor preassigned to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) the watchdog device. If watchdog pretimeout governor framework is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) enabled, watchdog_notify_pretimeout() prints a notification message to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) the kernel log buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) To set the last known HW keepalive time for a watchdog, the following function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) should be used::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) int watchdog_set_last_hw_keepalive(struct watchdog_device *wdd,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) unsigned int last_ping_ms)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) This function must be called immediately after watchdog registration. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) sets the last known hardware heartbeat to have happened last_ping_ms before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) current time. Calling this is only needed if the watchdog is already running
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) when probe is called, and the watchdog can only be pinged after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) min_hw_heartbeat_ms time has passed from the last ping.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags