Documentation/watchdog/convert_drivers_to_kernel_api.rst

2 Converting old watchdog drivers to the watchdog framework
7 Before the watchdog framework came into the kernel, every driver had to
8 implement the API on its own. Now, as the framework factored out the common
9 components, those drivers can be lightened making it a user of the framework.
10 This document shall guide you for this task. The necessary steps are described
14 Remove the file_operations struct
15 ---------------------------------
18 etc... These are now handled by the framework and just call the driver when
19 needed. So, in general, the 'file_operations' struct and assorted functions can
20 go. Only very few driver-specific details have to be moved to other functions.
21 Here is a overview of the functions and probably needed actions:
23 - open: Everything dealing with resource management (file-open checks, magic
24   close preparations) can simply go. Device specific stuff needs to go to the
25   driver specific start-function. Note that for some drivers, the start-function
26   also serves as the ping-function. If that is the case and you need start/stop
27   to be balanced (clocks!), you are better off refactoring a separate start-function.
29 - close: Same hints as for open apply.
31 - write: Can simply go, all defined behaviour is taken care of by the framework,
32   i.e. ping on write and magic char ('V') handling.
34 - ioctl: While the driver is allowed to have extensions to the IOCTL interface,
35   the most common ones are handled by the framework, supported by some assistance
36   from the driver:
39 		Returns the mandatory watchdog_info struct from the driver
42 		Needs the status-callback defined, otherwise returns 0
45 		Needs the bootstatus member properly set. Make sure it is 0 if you
57 		and a set_timeout-callback has to be defined. The core will also
58 		do limit-checking, if min_timeout and max_timeout in the watchdog
68   Other IOCTLs can be served using the ioctl-callback. Note that this is mainly
70   Private IOCTLs are processed first. When the callback returns with
71   -ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error
72   is directly given to the user.
76   -static const struct file_operations s3c2410wdt_fops = {
77   -       .owner          = THIS_MODULE,
78   -       .write          = s3c2410wdt_write,
79   -       .unlocked_ioctl = s3c2410wdt_ioctl,
80   -       .open           = s3c2410wdt_open,
81   -       .release        = s3c2410wdt_release,
82   -};
84 Check the functions for device-specific stuff and keep it for later
85 refactoring. The rest can go.
88 Remove the miscdevice
89 ---------------------
91 Since the file_operations are gone now, you can also remove the 'struct
92 miscdevice'. The framework will create it on watchdog_dev_register() called by
95   -static struct miscdevice s3c2410wdt_miscdev = {
96   -       .minor          = WATCHDOG_MINOR,
97   -       .name           = "watchdog",
98   -       .fops           = &s3c2410wdt_fops,
99   -};
103 ------------------------------------
105 Because of the simplifications, a few defines are probably unused now. Remove
108   - #include <linux/fs.h>
109   - #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
110   - #include <linux/uaccess.h> (if no custom IOCTLs are used)
113 Add the watchdog operations
114 ---------------------------
117 explained in 'watchdog-kernel-api.txt' in this directory. start() and
118 owner must be set, the rest are optional. You will easily find corresponding
119 functions in the old driver. Note that you will now get a pointer to the
121 change the function header. Other changes are most likely not needed, because
122 here simply happens the direct hardware access. If you have device-specific
123 code left from the above steps, it should be refactored into these callbacks.
135 A typical function-header change looks like::
137   -static void s3c2410wdt_keepalive(void)
147   -       s3c2410wdt_keepalive();
151 Add the watchdog device
152 -----------------------
154 Now we need to create a 'struct watchdog_device' and populate it with the
155 necessary information for the framework. The struct is also explained in detail
156 in 'watchdog-kernel-api.txt' in this directory. We pass it the mandatory
157 watchdog_info struct and the newly created watchdog_ops. Often, old drivers
158 have their own record-keeping for things like bootstatus and timeout using
159 static variables. Those have to be converted to use the members in
160 watchdog_device. Note that the timeout values are unsigned int. Some drivers
171 Handle the 'nowayout' feature
172 -----------------------------
175 and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be
176 used. This needs to be converted by initializing the status variable of the
182 by adding a module parameter. The conversion for this would be something like::
186 The module parameter itself needs to stay, everything else related to nowayout
187 can go, though. This will likely be some code in open(), close() or write().
190 Register the watchdog device
191 ----------------------------
194 Make sure the return value gets checked and the error message, if present,
195 still fits. Also convert the unregister case::
197   -       ret = misc_register(&s3c2410wdt_miscdev);
202   -       misc_deregister(&s3c2410wdt_miscdev);
206 Update the Kconfig-entry
207 ------------------------
209 The entry for the driver now needs to select WATCHDOG_CORE:
215 --------------------------------------
217 Make sure you understood Documentation/process/submitting-patches.rst and send your patch to
218 linux-watchdog@vger.kernel.org. We are looking forward to it :)