Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 1 | The Linux WatchDog Timer Driver Core kernel API. |
| 2 | =============================================== |
Fabio Porcedda | 3048253 | 2013-01-08 11:04:10 +0100 | [diff] [blame] | 3 | Last reviewed: 12-Feb-2013 |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 4 | |
| 5 | Wim Van Sebroeck <wim@iguana.be> |
| 6 | |
| 7 | Introduction |
| 8 | ------------ |
| 9 | This document does not describe what a WatchDog Timer (WDT) Driver or Device is. |
| 10 | It also does not describe the API which can be used by user space to communicate |
| 11 | with a WatchDog Timer. If you want to know this then please read the following |
| 12 | file: Documentation/watchdog/watchdog-api.txt . |
| 13 | |
| 14 | So what does this document describe? It describes the API that can be used by |
| 15 | WatchDog Timer Drivers that want to use the WatchDog Timer Driver Core |
| 16 | Framework. This framework provides all interfacing towards user space so that |
| 17 | the same code does not have to be reproduced each time. This also means that |
| 18 | a watchdog timer driver then only needs to provide the different routines |
| 19 | (operations) that control the watchdog timer (WDT). |
| 20 | |
| 21 | The API |
| 22 | ------- |
| 23 | Each watchdog timer driver that wants to use the WatchDog Timer Driver Core |
| 24 | must #include <linux/watchdog.h> (you would have to do this anyway when |
| 25 | writing a watchdog device driver). This include file contains following |
| 26 | register/unregister routines: |
| 27 | |
| 28 | extern int watchdog_register_device(struct watchdog_device *); |
| 29 | extern void watchdog_unregister_device(struct watchdog_device *); |
| 30 | |
| 31 | The watchdog_register_device routine registers a watchdog timer device. |
| 32 | The parameter of this routine is a pointer to a watchdog_device structure. |
| 33 | This routine returns zero on success and a negative errno code for failure. |
| 34 | |
| 35 | The watchdog_unregister_device routine deregisters a registered watchdog timer |
| 36 | device. The parameter of this routine is the pointer to the registered |
| 37 | watchdog_device structure. |
| 38 | |
Jean-Baptiste Theou | ef90174 | 2015-06-09 09:55:02 -0700 | [diff] [blame] | 39 | The watchdog subsystem includes an registration deferral mechanism, |
| 40 | which allows you to register an watchdog as early as you wish during |
| 41 | the boot process. |
| 42 | |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 43 | The watchdog device structure looks like this: |
| 44 | |
| 45 | struct watchdog_device { |
Alan Cox | 45f5fed | 2012-05-10 21:48:59 +0200 | [diff] [blame] | 46 | int id; |
Alan Cox | d6b469d | 2012-05-11 12:00:20 +0200 | [diff] [blame] | 47 | struct device *parent; |
Guenter Roeck | faa5847 | 2016-01-03 15:11:56 -0800 | [diff] [blame] | 48 | const struct attribute_group **groups; |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 49 | const struct watchdog_info *info; |
| 50 | const struct watchdog_ops *ops; |
Wim Van Sebroeck | 2fa0356 | 2011-07-22 18:56:38 +0000 | [diff] [blame] | 51 | unsigned int bootstatus; |
Wim Van Sebroeck | 014d694 | 2011-07-22 18:58:21 +0000 | [diff] [blame] | 52 | unsigned int timeout; |
Wim Van Sebroeck | 3f43f68 | 2011-07-22 19:00:16 +0000 | [diff] [blame] | 53 | unsigned int min_timeout; |
| 54 | unsigned int max_timeout; |
Damien Riegel | e131319 | 2015-11-20 16:54:51 -0500 | [diff] [blame] | 55 | struct notifier_block reboot_nb; |
Damien Riegel | 2165bf5 | 2015-11-16 12:27:59 -0500 | [diff] [blame] | 56 | struct notifier_block restart_nb; |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 57 | void *driver_data; |
Guenter Roeck | b4ffb19 | 2015-12-25 16:01:42 -0800 | [diff] [blame] | 58 | struct watchdog_core_data *wd_data; |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 59 | unsigned long status; |
Jean-Baptiste Theou | ef90174 | 2015-06-09 09:55:02 -0700 | [diff] [blame] | 60 | struct list_head deferred; |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 61 | }; |
| 62 | |
| 63 | It contains following fields: |
Alan Cox | 45f5fed | 2012-05-10 21:48:59 +0200 | [diff] [blame] | 64 | * id: set by watchdog_register_device, id 0 is special. It has both a |
| 65 | /dev/watchdog0 cdev (dynamic major, minor 0) as well as the old |
| 66 | /dev/watchdog miscdev. The id is set automatically when calling |
| 67 | watchdog_register_device. |
Alan Cox | d6b469d | 2012-05-11 12:00:20 +0200 | [diff] [blame] | 68 | * parent: set this to the parent device (or NULL) before calling |
| 69 | watchdog_register_device. |
Guenter Roeck | faa5847 | 2016-01-03 15:11:56 -0800 | [diff] [blame] | 70 | * groups: List of sysfs attribute groups to create when creating the watchdog |
| 71 | device. |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 72 | * info: a pointer to a watchdog_info structure. This structure gives some |
| 73 | additional information about the watchdog timer itself. (Like it's unique name) |
| 74 | * ops: a pointer to the list of watchdog operations that the watchdog supports. |
Wim Van Sebroeck | 014d694 | 2011-07-22 18:58:21 +0000 | [diff] [blame] | 75 | * timeout: the watchdog timer's timeout value (in seconds). |
Wim Van Sebroeck | 3f43f68 | 2011-07-22 19:00:16 +0000 | [diff] [blame] | 76 | * min_timeout: the watchdog timer's minimum timeout value (in seconds). |
| 77 | * max_timeout: the watchdog timer's maximum timeout value (in seconds). |
Damien Riegel | e131319 | 2015-11-20 16:54:51 -0500 | [diff] [blame] | 78 | * reboot_nb: notifier block that is registered for reboot notifications, for |
| 79 | internal use only. If the driver calls watchdog_stop_on_reboot, watchdog core |
| 80 | will stop the watchdog on such notifications. |
Damien Riegel | 2165bf5 | 2015-11-16 12:27:59 -0500 | [diff] [blame] | 81 | * restart_nb: notifier block that is registered for machine restart, for |
| 82 | internal use only. If a watchdog is capable of restarting the machine, it |
| 83 | should define ops->restart. Priority can be changed through |
| 84 | watchdog_set_restart_priority. |
Wim Van Sebroeck | 2fa0356 | 2011-07-22 18:56:38 +0000 | [diff] [blame] | 85 | * bootstatus: status of the device after booting (reported with watchdog |
| 86 | WDIOF_* status bits). |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 87 | * driver_data: a pointer to the drivers private data of a watchdog device. |
Devendra Naga | 2deca73 | 2012-05-14 14:33:37 +0530 | [diff] [blame] | 88 | This data should only be accessed via the watchdog_set_drvdata and |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 89 | watchdog_get_drvdata routines. |
Guenter Roeck | b4ffb19 | 2015-12-25 16:01:42 -0800 | [diff] [blame] | 90 | * wd_data: a pointer to watchdog core internal data. |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 91 | * status: this field contains a number of status bits that give extra |
Wim Van Sebroeck | 234445b | 2011-07-22 18:57:55 +0000 | [diff] [blame] | 92 | information about the status of the device (Like: is the watchdog timer |
Guenter Roeck | b4ffb19 | 2015-12-25 16:01:42 -0800 | [diff] [blame] | 93 | running/active, or is the nowayout bit set). |
Jean-Baptiste Theou | ef90174 | 2015-06-09 09:55:02 -0700 | [diff] [blame] | 94 | * deferred: entry in wtd_deferred_reg_list which is used to |
| 95 | register early initialized watchdogs. |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 96 | |
| 97 | The list of watchdog operations is defined as: |
| 98 | |
| 99 | struct watchdog_ops { |
| 100 | struct module *owner; |
| 101 | /* mandatory operations */ |
| 102 | int (*start)(struct watchdog_device *); |
| 103 | int (*stop)(struct watchdog_device *); |
| 104 | /* optional operations */ |
| 105 | int (*ping)(struct watchdog_device *); |
Wim Van Sebroeck | 2fa0356 | 2011-07-22 18:56:38 +0000 | [diff] [blame] | 106 | unsigned int (*status)(struct watchdog_device *); |
Wim Van Sebroeck | 014d694 | 2011-07-22 18:58:21 +0000 | [diff] [blame] | 107 | int (*set_timeout)(struct watchdog_device *, unsigned int); |
Viresh Kumar | fd7b673 | 2012-03-16 09:14:00 +0100 | [diff] [blame] | 108 | unsigned int (*get_timeleft)(struct watchdog_device *); |
Damien Riegel | 2165bf5 | 2015-11-16 12:27:59 -0500 | [diff] [blame] | 109 | int (*restart)(struct watchdog_device *); |
Guenter Roeck | b4ffb19 | 2015-12-25 16:01:42 -0800 | [diff] [blame] | 110 | void (*ref)(struct watchdog_device *) __deprecated; |
| 111 | void (*unref)(struct watchdog_device *) __deprecated; |
Wim Van Sebroeck | 78d88fc | 2011-07-22 18:59:49 +0000 | [diff] [blame] | 112 | long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long); |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 113 | }; |
| 114 | |
| 115 | It is important that you first define the module owner of the watchdog timer |
| 116 | driver's operations. This module owner will be used to lock the module when |
| 117 | the watchdog is active. (This to avoid a system crash when you unload the |
| 118 | module and /dev/watchdog is still open). |
Hans de Goede | e907df3 | 2012-05-22 11:40:26 +0200 | [diff] [blame] | 119 | |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 120 | Some operations are mandatory and some are optional. The mandatory operations |
| 121 | are: |
| 122 | * start: this is a pointer to the routine that starts the watchdog timer |
| 123 | device. |
| 124 | The routine needs a pointer to the watchdog timer device structure as a |
| 125 | parameter. It returns zero on success or a negative errno code for failure. |
| 126 | * stop: with this routine the watchdog timer device is being stopped. |
| 127 | The routine needs a pointer to the watchdog timer device structure as a |
| 128 | parameter. It returns zero on success or a negative errno code for failure. |
| 129 | Some watchdog timer hardware can only be started and not be stopped. The |
| 130 | driver supporting this hardware needs to make sure that a start and stop |
| 131 | routine is being provided. This can be done by using a timer in the driver |
| 132 | that regularly sends a keepalive ping to the watchdog timer hardware. |
| 133 | |
| 134 | Not all watchdog timer hardware supports the same functionality. That's why |
| 135 | all other routines/operations are optional. They only need to be provided if |
| 136 | they are supported. These optional routines/operations are: |
| 137 | * ping: this is the routine that sends a keepalive ping to the watchdog timer |
| 138 | hardware. |
| 139 | The routine needs a pointer to the watchdog timer device structure as a |
| 140 | parameter. It returns zero on success or a negative errno code for failure. |
| 141 | Most hardware that does not support this as a separate function uses the |
| 142 | start function to restart the watchdog timer hardware. And that's also what |
| 143 | the watchdog timer driver core does: to send a keepalive ping to the watchdog |
| 144 | timer hardware it will either use the ping operation (when available) or the |
| 145 | start operation (when the ping operation is not available). |
Wim Van Sebroeck | c2dc00e | 2011-07-22 18:57:23 +0000 | [diff] [blame] | 146 | (Note: the WDIOC_KEEPALIVE ioctl call will only be active when the |
| 147 | WDIOF_KEEPALIVEPING bit has been set in the option field on the watchdog's |
| 148 | info structure). |
Wim Van Sebroeck | 2fa0356 | 2011-07-22 18:56:38 +0000 | [diff] [blame] | 149 | * status: this routine checks the status of the watchdog timer device. The |
| 150 | status of the device is reported with watchdog WDIOF_* status flags/bits. |
Wim Van Sebroeck | 014d694 | 2011-07-22 18:58:21 +0000 | [diff] [blame] | 151 | * set_timeout: this routine checks and changes the timeout of the watchdog |
| 152 | timer device. It returns 0 on success, -EINVAL for "parameter out of range" |
Hans de Goede | b10f7c1 | 2011-09-12 11:56:59 +0200 | [diff] [blame] | 153 | and -EIO for "could not write value to the watchdog". On success this |
| 154 | routine should set the timeout value of the watchdog_device to the |
| 155 | achieved timeout value (which may be different from the requested one |
| 156 | because the watchdog does not necessarily has a 1 second resolution). |
Wim Van Sebroeck | 014d694 | 2011-07-22 18:58:21 +0000 | [diff] [blame] | 157 | (Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the |
| 158 | watchdog's info structure). |
Viresh Kumar | fd7b673 | 2012-03-16 09:14:00 +0100 | [diff] [blame] | 159 | * get_timeleft: this routines returns the time that's left before a reset. |
Damien Riegel | 2165bf5 | 2015-11-16 12:27:59 -0500 | [diff] [blame] | 160 | * restart: this routine restarts the machine. It returns 0 on success or a |
| 161 | negative errno code for failure. |
Wim Van Sebroeck | 78d88fc | 2011-07-22 18:59:49 +0000 | [diff] [blame] | 162 | * ioctl: if this routine is present then it will be called first before we do |
| 163 | our own internal ioctl call handling. This routine should return -ENOIOCTLCMD |
| 164 | if a command is not supported. The parameters that are passed to the ioctl |
| 165 | call are: watchdog_device, cmd and arg. |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 166 | |
Guenter Roeck | b4ffb19 | 2015-12-25 16:01:42 -0800 | [diff] [blame] | 167 | The 'ref' and 'unref' operations are no longer used and deprecated. |
| 168 | |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 169 | The status bits should (preferably) be set with the set_bit and clear_bit alike |
| 170 | bit-operations. The status bits that are defined are: |
Wim Van Sebroeck | 234445b | 2011-07-22 18:57:55 +0000 | [diff] [blame] | 171 | * WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device |
| 172 | is active or not. When the watchdog is active after booting, then you should |
| 173 | set this status bit (Note: when you register the watchdog timer device with |
| 174 | this bit set, then opening /dev/watchdog will skip the start operation) |
Wim Van Sebroeck | 7e192b9 | 2011-07-22 18:59:17 +0000 | [diff] [blame] | 175 | * WDOG_NO_WAY_OUT: this bit stores the nowayout setting for the watchdog. |
| 176 | If this bit is set then the watchdog timer will not be able to stop. |
Wim Van Sebroeck | 017cf08 | 2011-07-22 18:58:54 +0000 | [diff] [blame] | 177 | |
Wim Van Sebroeck | ff0b3cd | 2011-11-29 16:24:16 +0100 | [diff] [blame] | 178 | To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog |
| 179 | timer device) you can either: |
| 180 | * set it statically in your watchdog_device struct with |
| 181 | .status = WATCHDOG_NOWAYOUT_INIT_STATUS, |
| 182 | (this will set the value the same as CONFIG_WATCHDOG_NOWAYOUT) or |
| 183 | * use the following helper function: |
| 184 | static inline void watchdog_set_nowayout(struct watchdog_device *wdd, int nowayout) |
| 185 | |
Wim Van Sebroeck | 7e192b9 | 2011-07-22 18:59:17 +0000 | [diff] [blame] | 186 | Note: The WatchDog Timer Driver Core supports the magic close feature and |
| 187 | the nowayout feature. To use the magic close feature you must set the |
| 188 | WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure. |
| 189 | The nowayout feature will overrule the magic close feature. |
Wim Van Sebroeck | 4331604 | 2011-07-22 18:55:18 +0000 | [diff] [blame] | 190 | |
| 191 | To get or set driver specific data the following two helper functions should be |
| 192 | used: |
| 193 | |
| 194 | static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data) |
| 195 | static inline void *watchdog_get_drvdata(struct watchdog_device *wdd) |
| 196 | |
| 197 | The watchdog_set_drvdata function allows you to add driver specific data. The |
| 198 | arguments of this function are the watchdog device where you want to add the |
| 199 | driver specific data to and a pointer to the data itself. |
| 200 | |
| 201 | The watchdog_get_drvdata function allows you to retrieve driver specific data. |
| 202 | The argument of this function is the watchdog device where you want to retrieve |
Masanari Iida | e198652 | 2012-02-11 00:09:20 +0900 | [diff] [blame] | 203 | data from. The function returns the pointer to the driver specific data. |
Fabio Porcedda | 3048253 | 2013-01-08 11:04:10 +0100 | [diff] [blame] | 204 | |
| 205 | To initialize the timeout field, the following function can be used: |
| 206 | |
| 207 | extern int watchdog_init_timeout(struct watchdog_device *wdd, |
| 208 | unsigned int timeout_parm, struct device *dev); |
| 209 | |
| 210 | The watchdog_init_timeout function allows you to initialize the timeout field |
| 211 | using the module timeout parameter or by retrieving the timeout-sec property from |
| 212 | the device tree (if the module timeout parameter is invalid). Best practice is |
| 213 | to set the default timeout value as timeout value in the watchdog_device and |
| 214 | then use this function to set the user "preferred" timeout value. |
| 215 | This routine returns zero on success and a negative errno code for failure. |
Damien Riegel | 2165bf5 | 2015-11-16 12:27:59 -0500 | [diff] [blame] | 216 | |
Damien Riegel | e131319 | 2015-11-20 16:54:51 -0500 | [diff] [blame] | 217 | To disable the watchdog on reboot, the user must call the following helper: |
| 218 | |
| 219 | static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd); |
| 220 | |
Damien Riegel | 2165bf5 | 2015-11-16 12:27:59 -0500 | [diff] [blame] | 221 | To change the priority of the restart handler the following helper should be |
| 222 | used: |
| 223 | |
| 224 | void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority); |
| 225 | |
| 226 | User should follow the following guidelines for setting the priority: |
| 227 | * 0: should be called in last resort, has limited restart capabilities |
| 228 | * 128: default restart handler, use if no other handler is expected to be |
| 229 | available, and/or if restart is sufficient to restart the entire system |
| 230 | * 255: highest priority, will preempt all other restart handlers |