Commit | Line | Data |
---|---|---|
f4b50261 | 1 | Revision 5, 2005-07-29 |
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. | |
8 | ||
9 | There are two sets of points below. The first set concerns technical | |
10 | changes. The second set concerns coding policy. Both are mandatory. | |
11 | ||
12 | Although reading this guide will help you porting drivers, I suggest | |
13 | you keep an eye on an already ported driver while porting your own | |
14 | driver. This will help you a lot understanding what this guide | |
15 | exactly means. Choose the chip driver that is the more similar to | |
16 | yours for best results. | |
17 | ||
18 | Technical changes: | |
19 | ||
f4b50261 JD |
20 | * [Includes] Get rid of "version.h" and <linux/i2c-proc.h>. |
21 | Includes typically look like that: | |
1da177e4 LT |
22 | #include <linux/module.h> |
23 | #include <linux/init.h> | |
24 | #include <linux/slab.h> | |
25 | #include <linux/i2c.h> | |
303760b4 JD |
26 | #include <linux/hwmon.h> /* for hardware monitoring drivers */ |
27 | #include <linux/hwmon-sysfs.h> | |
28 | #include <linux/hwmon-vid.h> /* if you need VRM support */ | |
1da177e4 LT |
29 | #include <asm/io.h> /* if you have I/O operations */ |
30 | Please respect this inclusion order. Some extra headers may be | |
31 | required for a given driver (e.g. "lm75.h"). | |
32 | ||
5071860a JD |
33 | * [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, ISA addresses |
34 | are no more handled by the i2c core. | |
f4b50261 | 35 | SENSORS_INSMOD_<n> becomes I2C_CLIENT_INSMOD_<n>. |
1da177e4 LT |
36 | |
37 | * [Client data] Get rid of sysctl_id. Try using standard names for | |
38 | register values (for example, temp_os becomes temp_max). You're | |
39 | still relatively free here, but you *have* to follow the standard | |
40 | names for sysfs files (see the Sysctl section below). | |
41 | ||
42 | * [Function prototypes] The detect functions loses its flags | |
43 | parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions | |
44 | are off the list of prototypes. This usually leaves five | |
45 | prototypes: | |
46 | static int lm75_attach_adapter(struct i2c_adapter *adapter); | |
47 | static int lm75_detect(struct i2c_adapter *adapter, int address, | |
48 | int kind); | |
49 | static void lm75_init_client(struct i2c_client *client); | |
50 | static int lm75_detach_client(struct i2c_client *client); | |
51 | static void lm75_update_client(struct i2c_client *client); | |
52 | ||
53 | * [Sysctl] All sysctl stuff is of course gone (defines, ctl_table | |
54 | and functions). Instead, you have to define show and set functions for | |
55 | each sysfs file. Only define set for writable values. Take a look at an | |
56 | existing 2.6 driver for details (lm78 for example). Don't forget | |
57 | to define the attributes for each file (this is that step that | |
58 | links callback functions). Use the file names specified in | |
59 | Documentation/i2c/sysfs-interface for the individual files. Also | |
60 | convert the units these files read and write to the specified ones. | |
61 | If you need to add a new type of file, please discuss it on the | |
cc0b07ed | 62 | sensors mailing list <lm-sensors@lm-sensors.org> by providing a |
1da177e4 LT |
63 | patch to the Documentation/i2c/sysfs-interface file. |
64 | ||
65 | * [Attach] For I2C drivers, the attach function should make sure | |
66 | that the adapter's class has I2C_CLASS_HWMON, using the | |
67 | following construct: | |
68 | if (!(adapter->class & I2C_CLASS_HWMON)) | |
69 | return 0; | |
70 | ISA-only drivers of course don't need this. | |
2ed2dc3c | 71 | Call i2c_probe() instead of i2c_detect(). |
1da177e4 LT |
72 | |
73 | * [Detect] As mentioned earlier, the flags parameter is gone. | |
74 | The type_name and client_name strings are replaced by a single | |
75 | name string, which will be filled with a lowercase, short string | |
76 | (typically the driver name, e.g. "lm75"). | |
77 | In i2c-only drivers, drop the i2c_is_isa_adapter check, it's | |
5071860a JD |
78 | useless. Same for isa-only drivers, as the test would always be |
79 | true. Only hybrid drivers (which are quite rare) still need it. | |
1da177e4 LT |
80 | The errorN labels are reduced to the number needed. If that number |
81 | is 2 (i2c-only drivers), it is advised that the labels are named | |
82 | exit and exit_free. For i2c+isa drivers, labels should be named | |
83 | ERROR0, ERROR1 and ERROR2. Don't forget to properly set err before | |
84 | jumping to error labels. By the way, labels should be left-aligned. | |
85 | Use memset to fill the client and data area with 0x00. | |
86 | Use i2c_set_clientdata to set the client data (as opposed to | |
87 | a direct access to client->data). | |
88 | Use strlcpy instead of strcpy to copy the client name. | |
89 | Replace the sysctl directory registration by calls to | |
90 | device_create_file. Move the driver initialization before any | |
91 | sysfs file creation. | |
92 | Drop client->id. | |
4c9337da JD |
93 | Drop any 24RF08 corruption prevention you find, as this is now done |
94 | at the i2c-core level, and doing it twice voids it. | |
1da177e4 LT |
95 | |
96 | * [Init] Limits must not be set by the driver (can be done later in | |
97 | user-space). Chip should not be reset default (although a module | |
98 | parameter may be used to force is), and initialization should be | |
99 | limited to the strictly necessary steps. | |
100 | ||
101 | * [Detach] Get rid of data, remove the call to | |
7bef5594 JD |
102 | i2c_deregister_entry. Do not log an error message if |
103 | i2c_detach_client fails, as i2c-core will now do it for you. | |
1da177e4 LT |
104 | |
105 | * [Update] Don't access client->data directly, use | |
106 | i2c_get_clientdata(client) instead. | |
107 | ||
108 | * [Interface] Init function should not print anything. Make sure | |
109 | there is a MODULE_LICENSE() line, at the bottom of the file | |
110 | (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this order). | |
111 | ||
112 | Coding policy: | |
113 | ||
114 | * [Copyright] Use (C), not (c), for copyright. | |
115 | ||
116 | * [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you | |
117 | can. Calls to printk/pr_debug for debugging purposes are replaced | |
118 | by calls to dev_dbg. Here is an example on how to call it (taken | |
119 | from lm75_detect): | |
120 | dev_dbg(&client->dev, "Starting lm75 update\n"); | |
121 | Replace other printk calls with the dev_info, dev_err or dev_warn | |
122 | function, as appropriate. | |
123 | ||
124 | * [Constants] Constants defines (registers, conversions, initial | |
125 | values) should be aligned. This greatly improves readability. | |
126 | Same goes for variables declarations. Alignments are achieved by the | |
127 | means of tabs, not spaces. Remember that tabs are set to 8 in the | |
128 | Linux kernel code. | |
129 | ||
130 | * [Structure definition] The name field should be standardized. All | |
131 | lowercase and as simple as the driver name itself (e.g. "lm75"). | |
132 | ||
133 | * [Layout] Avoid extra empty lines between comments and what they | |
134 | comment. Respect the coding style (see Documentation/CodingStyle), | |
135 | in particular when it comes to placing curly braces. | |
136 | ||
137 | * [Comments] Make sure that no comment refers to a file that isn't | |
138 | part of the Linux source tree (typically doc/chips/<chip name>), | |
139 | and that remaining comments still match the code. Merging comment | |
140 | lines when possible is encouraged. |