Commit | Line | Data |
---|---|---|
eefcd75e | 1 | Revision 7, 2007-04-19 |
1da177e4 LT |
2 | Jean Delvare <khali@linux-fr.org> |
3 | Greg KH <greg@kroah.com> | |
4 | ||
5 | This is a guide on how to convert I2C chip drivers from Linux 2.4 to | |
6 | Linux 2.6. I have been using existing drivers (lm75, lm78) as examples. | |
7 | Then I converted a driver myself (lm83) and updated this document. | |
92b42946 JD |
8 | Note that this guide is strongly oriented towards hardware monitoring |
9 | drivers. Many points are still valid for other type of drivers, but | |
10 | others may be irrelevant. | |
1da177e4 LT |
11 | |
12 | There are two sets of points below. The first set concerns technical | |
13 | changes. The second set concerns coding policy. Both are mandatory. | |
14 | ||
15 | Although reading this guide will help you porting drivers, I suggest | |
16 | you keep an eye on an already ported driver while porting your own | |
17 | driver. This will help you a lot understanding what this guide | |
18 | exactly means. Choose the chip driver that is the more similar to | |
19 | yours for best results. | |
20 | ||
21 | Technical changes: | |
22 | ||
eefcd75e JD |
23 | * [Driver type] Any driver that was relying on i2c-isa has to be |
24 | converted to a proper isa, platform or pci driver. This is not | |
25 | covered by this guide. | |
26 | ||
f4b50261 JD |
27 | * [Includes] Get rid of "version.h" and <linux/i2c-proc.h>. |
28 | Includes typically look like that: | |
1da177e4 LT |
29 | #include <linux/module.h> |
30 | #include <linux/init.h> | |
31 | #include <linux/slab.h> | |
92b42946 | 32 | #include <linux/jiffies.h> |
1da177e4 | 33 | #include <linux/i2c.h> |
303760b4 JD |
34 | #include <linux/hwmon.h> /* for hardware monitoring drivers */ |
35 | #include <linux/hwmon-sysfs.h> | |
36 | #include <linux/hwmon-vid.h> /* if you need VRM support */ | |
92b42946 | 37 | #include <linux/err.h> /* for class registration */ |
1da177e4 LT |
38 | Please respect this inclusion order. Some extra headers may be |
39 | required for a given driver (e.g. "lm75.h"). | |
40 | ||
5071860a | 41 | * [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, ISA addresses |
92b42946 JD |
42 | are no more handled by the i2c core. Address ranges are no more |
43 | supported either, define each individual address separately. | |
f4b50261 | 44 | SENSORS_INSMOD_<n> becomes I2C_CLIENT_INSMOD_<n>. |
1da177e4 LT |
45 | |
46 | * [Client data] Get rid of sysctl_id. Try using standard names for | |
47 | register values (for example, temp_os becomes temp_max). You're | |
48 | still relatively free here, but you *have* to follow the standard | |
49 | names for sysfs files (see the Sysctl section below). | |
50 | ||
51 | * [Function prototypes] The detect functions loses its flags | |
52 | parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions | |
53 | are off the list of prototypes. This usually leaves five | |
54 | prototypes: | |
55 | static int lm75_attach_adapter(struct i2c_adapter *adapter); | |
56 | static int lm75_detect(struct i2c_adapter *adapter, int address, | |
57 | int kind); | |
58 | static void lm75_init_client(struct i2c_client *client); | |
59 | static int lm75_detach_client(struct i2c_client *client); | |
92b42946 | 60 | static struct lm75_data lm75_update_device(struct device *dev); |
1da177e4 LT |
61 | |
62 | * [Sysctl] All sysctl stuff is of course gone (defines, ctl_table | |
63 | and functions). Instead, you have to define show and set functions for | |
64 | each sysfs file. Only define set for writable values. Take a look at an | |
92b42946 | 65 | existing 2.6 driver for details (it87 for example). Don't forget |
1da177e4 LT |
66 | to define the attributes for each file (this is that step that |
67 | links callback functions). Use the file names specified in | |
92b42946 | 68 | Documentation/hwmon/sysfs-interface for the individual files. Also |
1da177e4 LT |
69 | convert the units these files read and write to the specified ones. |
70 | If you need to add a new type of file, please discuss it on the | |
cc0b07ed | 71 | sensors mailing list <lm-sensors@lm-sensors.org> by providing a |
92b42946 | 72 | patch to the Documentation/hwmon/sysfs-interface file. |
1da177e4 | 73 | |
eefcd75e JD |
74 | * [Attach] The attach function should make sure that the adapter's |
75 | class has I2C_CLASS_HWMON (or whatever class is suitable for your | |
76 | driver), using the following construct: | |
1da177e4 LT |
77 | if (!(adapter->class & I2C_CLASS_HWMON)) |
78 | return 0; | |
2ed2dc3c | 79 | Call i2c_probe() instead of i2c_detect(). |
1da177e4 LT |
80 | |
81 | * [Detect] As mentioned earlier, the flags parameter is gone. | |
82 | The type_name and client_name strings are replaced by a single | |
92b42946 | 83 | name string, which will be filled with a lowercase, short string. |
92b42946 JD |
84 | The labels used for error paths are reduced to the number needed. |
85 | It is advised that the labels are given descriptive names such as | |
86 | exit and exit_free. Don't forget to properly set err before | |
1da177e4 | 87 | jumping to error labels. By the way, labels should be left-aligned. |
2445eb62 | 88 | Use kzalloc instead of kmalloc. |
1da177e4 LT |
89 | Use i2c_set_clientdata to set the client data (as opposed to |
90 | a direct access to client->data). | |
92b42946 | 91 | Use strlcpy instead of strcpy or snprintf to copy the client name. |
1da177e4 LT |
92 | Replace the sysctl directory registration by calls to |
93 | device_create_file. Move the driver initialization before any | |
94 | sysfs file creation. | |
92b42946 JD |
95 | Register the client with the hwmon class (using hwmon_device_register) |
96 | if applicable. | |
1da177e4 | 97 | Drop client->id. |
4c9337da JD |
98 | Drop any 24RF08 corruption prevention you find, as this is now done |
99 | at the i2c-core level, and doing it twice voids it. | |
cf02df77 | 100 | Don't add I2C_CLIENT_ALLOW_USE to client->flags, it's the default now. |
1da177e4 LT |
101 | |
102 | * [Init] Limits must not be set by the driver (can be done later in | |
103 | user-space). Chip should not be reset default (although a module | |
92b42946 | 104 | parameter may be used to force it), and initialization should be |
1da177e4 LT |
105 | limited to the strictly necessary steps. |
106 | ||
92b42946 JD |
107 | * [Detach] Remove the call to i2c_deregister_entry. Do not log an |
108 | error message if i2c_detach_client fails, as i2c-core will now do | |
109 | it for you. | |
110 | Unregister from the hwmon class if applicable. | |
1da177e4 | 111 | |
92b42946 JD |
112 | * [Update] The function prototype changed, it is now |
113 | passed a device structure, which you have to convert to a client | |
114 | using to_i2c_client(dev). The update function should return a | |
115 | pointer to the client data. | |
116 | Don't access client->data directly, use i2c_get_clientdata(client) | |
117 | instead. | |
118 | Use time_after() instead of direct jiffies comparison. | |
1da177e4 | 119 | |
92b42946 JD |
120 | * [Interface] Make sure there is a MODULE_LICENSE() line, at the bottom |
121 | of the file (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this | |
122 | order). | |
1da177e4 | 123 | |
8a994755 JD |
124 | * [Driver] The flags field of the i2c_driver structure is gone. |
125 | I2C_DF_NOTIFY is now the default behavior. | |
d45d204f | 126 | The i2c_driver structure has a driver member, which is itself a |
d82c0bf8 JD |
127 | structure, those name member should be initialized to a driver name |
128 | string. i2c_driver itself has no name member anymore. | |
8a994755 | 129 | |
f37dd80a DB |
130 | * [Driver model] Instead of shutdown or reboot notifiers, provide a |
131 | shutdown() method in your driver. | |
132 | ||
133 | * [Power management] Use the driver model suspend() and resume() | |
134 | callbacks instead of the obsolete pm_register() calls. | |
135 | ||
1da177e4 LT |
136 | Coding policy: |
137 | ||
138 | * [Copyright] Use (C), not (c), for copyright. | |
139 | ||
140 | * [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you | |
92b42946 JD |
141 | can. Calls to printk for debugging purposes are replaced by calls to |
142 | dev_dbg where possible, else to pr_debug. Here is an example of how | |
143 | to call it (taken from lm75_detect): | |
1da177e4 LT |
144 | dev_dbg(&client->dev, "Starting lm75 update\n"); |
145 | Replace other printk calls with the dev_info, dev_err or dev_warn | |
146 | function, as appropriate. | |
147 | ||
92b42946 JD |
148 | * [Constants] Constants defines (registers, conversions) should be |
149 | aligned. This greatly improves readability. | |
150 | Alignments are achieved by the means of tabs, not spaces. Remember | |
151 | that tabs are set to 8 in the Linux kernel code. | |
1da177e4 LT |
152 | |
153 | * [Layout] Avoid extra empty lines between comments and what they | |
154 | comment. Respect the coding style (see Documentation/CodingStyle), | |
155 | in particular when it comes to placing curly braces. | |
156 | ||
157 | * [Comments] Make sure that no comment refers to a file that isn't | |
158 | part of the Linux source tree (typically doc/chips/<chip name>), | |
159 | and that remaining comments still match the code. Merging comment | |
160 | lines when possible is encouraged. |