Commit 2deca7365582b7568dbdd2c3d9eef7ac17d41fd6
Committed by
Wim Van Sebroeck
1 parent
5f2430f554
Documentation/watchdog: Fix a small typo
Signed-off-by: Devendra Naga <devendra.aaru@gmail.com> Signed-off-by: Wim Van Sebroeck <wim@iguana.be>
Showing 1 changed file with 1 additions and 1 deletions Inline Diff
Documentation/watchdog/watchdog-kernel-api.txt
1 | The Linux WatchDog Timer Driver Core kernel API. | 1 | The Linux WatchDog Timer Driver Core kernel API. |
2 | =============================================== | 2 | =============================================== |
3 | Last reviewed: 16-Mar-2012 | 3 | Last reviewed: 16-Mar-2012 |
4 | 4 | ||
5 | Wim Van Sebroeck <wim@iguana.be> | 5 | Wim Van Sebroeck <wim@iguana.be> |
6 | 6 | ||
7 | Introduction | 7 | Introduction |
8 | ------------ | 8 | ------------ |
9 | This document does not describe what a WatchDog Timer (WDT) Driver or Device is. | 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 | 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 | 11 | with a WatchDog Timer. If you want to know this then please read the following |
12 | file: Documentation/watchdog/watchdog-api.txt . | 12 | file: Documentation/watchdog/watchdog-api.txt . |
13 | 13 | ||
14 | So what does this document describe? It describes the API that can be used by | 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 | 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 | 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 | 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 | 18 | a watchdog timer driver then only needs to provide the different routines |
19 | (operations) that control the watchdog timer (WDT). | 19 | (operations) that control the watchdog timer (WDT). |
20 | 20 | ||
21 | The API | 21 | The API |
22 | ------- | 22 | ------- |
23 | Each watchdog timer driver that wants to use the WatchDog Timer Driver Core | 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 | 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 | 25 | writing a watchdog device driver). This include file contains following |
26 | register/unregister routines: | 26 | register/unregister routines: |
27 | 27 | ||
28 | extern int watchdog_register_device(struct watchdog_device *); | 28 | extern int watchdog_register_device(struct watchdog_device *); |
29 | extern void watchdog_unregister_device(struct watchdog_device *); | 29 | extern void watchdog_unregister_device(struct watchdog_device *); |
30 | 30 | ||
31 | The watchdog_register_device routine registers a watchdog timer device. | 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. | 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. | 33 | This routine returns zero on success and a negative errno code for failure. |
34 | 34 | ||
35 | The watchdog_unregister_device routine deregisters a registered watchdog timer | 35 | The watchdog_unregister_device routine deregisters a registered watchdog timer |
36 | device. The parameter of this routine is the pointer to the registered | 36 | device. The parameter of this routine is the pointer to the registered |
37 | watchdog_device structure. | 37 | watchdog_device structure. |
38 | 38 | ||
39 | The watchdog device structure looks like this: | 39 | The watchdog device structure looks like this: |
40 | 40 | ||
41 | struct watchdog_device { | 41 | struct watchdog_device { |
42 | const struct watchdog_info *info; | 42 | const struct watchdog_info *info; |
43 | const struct watchdog_ops *ops; | 43 | const struct watchdog_ops *ops; |
44 | unsigned int bootstatus; | 44 | unsigned int bootstatus; |
45 | unsigned int timeout; | 45 | unsigned int timeout; |
46 | unsigned int min_timeout; | 46 | unsigned int min_timeout; |
47 | unsigned int max_timeout; | 47 | unsigned int max_timeout; |
48 | void *driver_data; | 48 | void *driver_data; |
49 | unsigned long status; | 49 | unsigned long status; |
50 | }; | 50 | }; |
51 | 51 | ||
52 | It contains following fields: | 52 | It contains following fields: |
53 | * info: a pointer to a watchdog_info structure. This structure gives some | 53 | * info: a pointer to a watchdog_info structure. This structure gives some |
54 | additional information about the watchdog timer itself. (Like it's unique name) | 54 | additional information about the watchdog timer itself. (Like it's unique name) |
55 | * ops: a pointer to the list of watchdog operations that the watchdog supports. | 55 | * ops: a pointer to the list of watchdog operations that the watchdog supports. |
56 | * timeout: the watchdog timer's timeout value (in seconds). | 56 | * timeout: the watchdog timer's timeout value (in seconds). |
57 | * min_timeout: the watchdog timer's minimum timeout value (in seconds). | 57 | * min_timeout: the watchdog timer's minimum timeout value (in seconds). |
58 | * max_timeout: the watchdog timer's maximum timeout value (in seconds). | 58 | * max_timeout: the watchdog timer's maximum timeout value (in seconds). |
59 | * bootstatus: status of the device after booting (reported with watchdog | 59 | * bootstatus: status of the device after booting (reported with watchdog |
60 | WDIOF_* status bits). | 60 | WDIOF_* status bits). |
61 | * driver_data: a pointer to the drivers private data of a watchdog device. | 61 | * driver_data: a pointer to the drivers private data of a watchdog device. |
62 | This data should only be accessed via the watchdog_set_drvadata and | 62 | This data should only be accessed via the watchdog_set_drvdata and |
63 | watchdog_get_drvdata routines. | 63 | watchdog_get_drvdata routines. |
64 | * status: this field contains a number of status bits that give extra | 64 | * status: this field contains a number of status bits that give extra |
65 | information about the status of the device (Like: is the watchdog timer | 65 | information about the status of the device (Like: is the watchdog timer |
66 | running/active, is the nowayout bit set, is the device opened via | 66 | running/active, is the nowayout bit set, is the device opened via |
67 | the /dev/watchdog interface or not, ...). | 67 | the /dev/watchdog interface or not, ...). |
68 | 68 | ||
69 | The list of watchdog operations is defined as: | 69 | The list of watchdog operations is defined as: |
70 | 70 | ||
71 | struct watchdog_ops { | 71 | struct watchdog_ops { |
72 | struct module *owner; | 72 | struct module *owner; |
73 | /* mandatory operations */ | 73 | /* mandatory operations */ |
74 | int (*start)(struct watchdog_device *); | 74 | int (*start)(struct watchdog_device *); |
75 | int (*stop)(struct watchdog_device *); | 75 | int (*stop)(struct watchdog_device *); |
76 | /* optional operations */ | 76 | /* optional operations */ |
77 | int (*ping)(struct watchdog_device *); | 77 | int (*ping)(struct watchdog_device *); |
78 | unsigned int (*status)(struct watchdog_device *); | 78 | unsigned int (*status)(struct watchdog_device *); |
79 | int (*set_timeout)(struct watchdog_device *, unsigned int); | 79 | int (*set_timeout)(struct watchdog_device *, unsigned int); |
80 | unsigned int (*get_timeleft)(struct watchdog_device *); | 80 | unsigned int (*get_timeleft)(struct watchdog_device *); |
81 | long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long); | 81 | long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long); |
82 | }; | 82 | }; |
83 | 83 | ||
84 | It is important that you first define the module owner of the watchdog timer | 84 | It is important that you first define the module owner of the watchdog timer |
85 | driver's operations. This module owner will be used to lock the module when | 85 | driver's operations. This module owner will be used to lock the module when |
86 | the watchdog is active. (This to avoid a system crash when you unload the | 86 | the watchdog is active. (This to avoid a system crash when you unload the |
87 | module and /dev/watchdog is still open). | 87 | module and /dev/watchdog is still open). |
88 | Some operations are mandatory and some are optional. The mandatory operations | 88 | Some operations are mandatory and some are optional. The mandatory operations |
89 | are: | 89 | are: |
90 | * start: this is a pointer to the routine that starts the watchdog timer | 90 | * start: this is a pointer to the routine that starts the watchdog timer |
91 | device. | 91 | device. |
92 | The routine needs a pointer to the watchdog timer device structure as a | 92 | The routine needs a pointer to the watchdog timer device structure as a |
93 | parameter. It returns zero on success or a negative errno code for failure. | 93 | parameter. It returns zero on success or a negative errno code for failure. |
94 | * stop: with this routine the watchdog timer device is being stopped. | 94 | * stop: with this routine the watchdog timer device is being stopped. |
95 | The routine needs a pointer to the watchdog timer device structure as a | 95 | The routine needs a pointer to the watchdog timer device structure as a |
96 | parameter. It returns zero on success or a negative errno code for failure. | 96 | parameter. It returns zero on success or a negative errno code for failure. |
97 | Some watchdog timer hardware can only be started and not be stopped. The | 97 | Some watchdog timer hardware can only be started and not be stopped. The |
98 | driver supporting this hardware needs to make sure that a start and stop | 98 | driver supporting this hardware needs to make sure that a start and stop |
99 | routine is being provided. This can be done by using a timer in the driver | 99 | routine is being provided. This can be done by using a timer in the driver |
100 | that regularly sends a keepalive ping to the watchdog timer hardware. | 100 | that regularly sends a keepalive ping to the watchdog timer hardware. |
101 | 101 | ||
102 | Not all watchdog timer hardware supports the same functionality. That's why | 102 | Not all watchdog timer hardware supports the same functionality. That's why |
103 | all other routines/operations are optional. They only need to be provided if | 103 | all other routines/operations are optional. They only need to be provided if |
104 | they are supported. These optional routines/operations are: | 104 | they are supported. These optional routines/operations are: |
105 | * ping: this is the routine that sends a keepalive ping to the watchdog timer | 105 | * ping: this is the routine that sends a keepalive ping to the watchdog timer |
106 | hardware. | 106 | hardware. |
107 | The routine needs a pointer to the watchdog timer device structure as a | 107 | The routine needs a pointer to the watchdog timer device structure as a |
108 | parameter. It returns zero on success or a negative errno code for failure. | 108 | parameter. It returns zero on success or a negative errno code for failure. |
109 | Most hardware that does not support this as a separate function uses the | 109 | Most hardware that does not support this as a separate function uses the |
110 | start function to restart the watchdog timer hardware. And that's also what | 110 | start function to restart the watchdog timer hardware. And that's also what |
111 | the watchdog timer driver core does: to send a keepalive ping to the watchdog | 111 | the watchdog timer driver core does: to send a keepalive ping to the watchdog |
112 | timer hardware it will either use the ping operation (when available) or the | 112 | timer hardware it will either use the ping operation (when available) or the |
113 | start operation (when the ping operation is not available). | 113 | start operation (when the ping operation is not available). |
114 | (Note: the WDIOC_KEEPALIVE ioctl call will only be active when the | 114 | (Note: the WDIOC_KEEPALIVE ioctl call will only be active when the |
115 | WDIOF_KEEPALIVEPING bit has been set in the option field on the watchdog's | 115 | WDIOF_KEEPALIVEPING bit has been set in the option field on the watchdog's |
116 | info structure). | 116 | info structure). |
117 | * status: this routine checks the status of the watchdog timer device. The | 117 | * status: this routine checks the status of the watchdog timer device. The |
118 | status of the device is reported with watchdog WDIOF_* status flags/bits. | 118 | status of the device is reported with watchdog WDIOF_* status flags/bits. |
119 | * set_timeout: this routine checks and changes the timeout of the watchdog | 119 | * set_timeout: this routine checks and changes the timeout of the watchdog |
120 | timer device. It returns 0 on success, -EINVAL for "parameter out of range" | 120 | timer device. It returns 0 on success, -EINVAL for "parameter out of range" |
121 | and -EIO for "could not write value to the watchdog". On success this | 121 | and -EIO for "could not write value to the watchdog". On success this |
122 | routine should set the timeout value of the watchdog_device to the | 122 | routine should set the timeout value of the watchdog_device to the |
123 | achieved timeout value (which may be different from the requested one | 123 | achieved timeout value (which may be different from the requested one |
124 | because the watchdog does not necessarily has a 1 second resolution). | 124 | because the watchdog does not necessarily has a 1 second resolution). |
125 | (Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the | 125 | (Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the |
126 | watchdog's info structure). | 126 | watchdog's info structure). |
127 | * get_timeleft: this routines returns the time that's left before a reset. | 127 | * get_timeleft: this routines returns the time that's left before a reset. |
128 | * ioctl: if this routine is present then it will be called first before we do | 128 | * ioctl: if this routine is present then it will be called first before we do |
129 | our own internal ioctl call handling. This routine should return -ENOIOCTLCMD | 129 | our own internal ioctl call handling. This routine should return -ENOIOCTLCMD |
130 | if a command is not supported. The parameters that are passed to the ioctl | 130 | if a command is not supported. The parameters that are passed to the ioctl |
131 | call are: watchdog_device, cmd and arg. | 131 | call are: watchdog_device, cmd and arg. |
132 | 132 | ||
133 | The status bits should (preferably) be set with the set_bit and clear_bit alike | 133 | The status bits should (preferably) be set with the set_bit and clear_bit alike |
134 | bit-operations. The status bits that are defined are: | 134 | bit-operations. The status bits that are defined are: |
135 | * WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device | 135 | * WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device |
136 | is active or not. When the watchdog is active after booting, then you should | 136 | is active or not. When the watchdog is active after booting, then you should |
137 | set this status bit (Note: when you register the watchdog timer device with | 137 | set this status bit (Note: when you register the watchdog timer device with |
138 | this bit set, then opening /dev/watchdog will skip the start operation) | 138 | this bit set, then opening /dev/watchdog will skip the start operation) |
139 | * WDOG_DEV_OPEN: this status bit shows whether or not the watchdog device | 139 | * WDOG_DEV_OPEN: this status bit shows whether or not the watchdog device |
140 | was opened via /dev/watchdog. | 140 | was opened via /dev/watchdog. |
141 | (This bit should only be used by the WatchDog Timer Driver Core). | 141 | (This bit should only be used by the WatchDog Timer Driver Core). |
142 | * WDOG_ALLOW_RELEASE: this bit stores whether or not the magic close character | 142 | * WDOG_ALLOW_RELEASE: this bit stores whether or not the magic close character |
143 | has been sent (so that we can support the magic close feature). | 143 | has been sent (so that we can support the magic close feature). |
144 | (This bit should only be used by the WatchDog Timer Driver Core). | 144 | (This bit should only be used by the WatchDog Timer Driver Core). |
145 | * WDOG_NO_WAY_OUT: this bit stores the nowayout setting for the watchdog. | 145 | * WDOG_NO_WAY_OUT: this bit stores the nowayout setting for the watchdog. |
146 | If this bit is set then the watchdog timer will not be able to stop. | 146 | If this bit is set then the watchdog timer will not be able to stop. |
147 | 147 | ||
148 | To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog | 148 | To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog |
149 | timer device) you can either: | 149 | timer device) you can either: |
150 | * set it statically in your watchdog_device struct with | 150 | * set it statically in your watchdog_device struct with |
151 | .status = WATCHDOG_NOWAYOUT_INIT_STATUS, | 151 | .status = WATCHDOG_NOWAYOUT_INIT_STATUS, |
152 | (this will set the value the same as CONFIG_WATCHDOG_NOWAYOUT) or | 152 | (this will set the value the same as CONFIG_WATCHDOG_NOWAYOUT) or |
153 | * use the following helper function: | 153 | * use the following helper function: |
154 | static inline void watchdog_set_nowayout(struct watchdog_device *wdd, int nowayout) | 154 | static inline void watchdog_set_nowayout(struct watchdog_device *wdd, int nowayout) |
155 | 155 | ||
156 | Note: The WatchDog Timer Driver Core supports the magic close feature and | 156 | Note: The WatchDog Timer Driver Core supports the magic close feature and |
157 | the nowayout feature. To use the magic close feature you must set the | 157 | the nowayout feature. To use the magic close feature you must set the |
158 | WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure. | 158 | WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure. |
159 | The nowayout feature will overrule the magic close feature. | 159 | The nowayout feature will overrule the magic close feature. |
160 | 160 | ||
161 | To get or set driver specific data the following two helper functions should be | 161 | To get or set driver specific data the following two helper functions should be |
162 | used: | 162 | used: |
163 | 163 | ||
164 | static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data) | 164 | static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data) |
165 | static inline void *watchdog_get_drvdata(struct watchdog_device *wdd) | 165 | static inline void *watchdog_get_drvdata(struct watchdog_device *wdd) |
166 | 166 | ||
167 | The watchdog_set_drvdata function allows you to add driver specific data. The | 167 | The watchdog_set_drvdata function allows you to add driver specific data. The |
168 | arguments of this function are the watchdog device where you want to add the | 168 | arguments of this function are the watchdog device where you want to add the |
169 | driver specific data to and a pointer to the data itself. | 169 | driver specific data to and a pointer to the data itself. |
170 | 170 | ||
171 | The watchdog_get_drvdata function allows you to retrieve driver specific data. | 171 | The watchdog_get_drvdata function allows you to retrieve driver specific data. |
172 | The argument of this function is the watchdog device where you want to retrieve | 172 | The argument of this function is the watchdog device where you want to retrieve |
173 | data from. The function returns the pointer to the driver specific data. | 173 | data from. The function returns the pointer to the driver specific data. |
174 | 174 |