aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/i2c/porting-clients
diff options
context:
space:
mode:
authorJean Delvare <khali@linux-fr.org>2005-11-26 15:05:17 -0500
committerGreg Kroah-Hartman <gregkh@suse.de>2006-01-06 01:16:22 -0500
commit92b429461228f0f06a994dd3d4ccf1c9ff7596bd (patch)
tree1a32a26d6536076aa9d7eaf91aa25ecc0a086fbf /Documentation/i2c/porting-clients
parentcf02df770228350254251fde520007a2709db785 (diff)
[PATCH] i2c: Chip driver porting guide update
Update Documentation/i2c/porting-clients. Many recent changes to the i2c and hwmon subsystems were never reported there. Signed-off-by: Jean Delvare <khali@linux-fr.org> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation/i2c/porting-clients')
-rw-r--r--Documentation/i2c/porting-clients79
1 files changed, 44 insertions, 35 deletions
diff --git a/Documentation/i2c/porting-clients b/Documentation/i2c/porting-clients
index 6b07f23039d2..856274fc8e9f 100644
--- a/Documentation/i2c/porting-clients
+++ b/Documentation/i2c/porting-clients
@@ -1,10 +1,13 @@
1Revision 5, 2005-07-29 1Revision 6, 2005-11-20
2Jean Delvare <khali@linux-fr.org> 2Jean Delvare <khali@linux-fr.org>
3Greg KH <greg@kroah.com> 3Greg KH <greg@kroah.com>
4 4
5This is a guide on how to convert I2C chip drivers from Linux 2.4 to 5This is a guide on how to convert I2C chip drivers from Linux 2.4 to
6Linux 2.6. I have been using existing drivers (lm75, lm78) as examples. 6Linux 2.6. I have been using existing drivers (lm75, lm78) as examples.
7Then I converted a driver myself (lm83) and updated this document. 7Then I converted a driver myself (lm83) and updated this document.
8Note that this guide is strongly oriented towards hardware monitoring
9drivers. Many points are still valid for other type of drivers, but
10others may be irrelevant.
8 11
9There are two sets of points below. The first set concerns technical 12There are two sets of points below. The first set concerns technical
10changes. The second set concerns coding policy. Both are mandatory. 13changes. The second set concerns coding policy. Both are mandatory.
@@ -22,16 +25,20 @@ Technical changes:
22 #include <linux/module.h> 25 #include <linux/module.h>
23 #include <linux/init.h> 26 #include <linux/init.h>
24 #include <linux/slab.h> 27 #include <linux/slab.h>
28 #include <linux/jiffies.h>
25 #include <linux/i2c.h> 29 #include <linux/i2c.h>
30 #include <linux/i2c-isa.h> /* for ISA drivers */
26 #include <linux/hwmon.h> /* for hardware monitoring drivers */ 31 #include <linux/hwmon.h> /* for hardware monitoring drivers */
27 #include <linux/hwmon-sysfs.h> 32 #include <linux/hwmon-sysfs.h>
28 #include <linux/hwmon-vid.h> /* if you need VRM support */ 33 #include <linux/hwmon-vid.h> /* if you need VRM support */
34 #include <linux/err.h> /* for class registration */
29 #include <asm/io.h> /* if you have I/O operations */ 35 #include <asm/io.h> /* if you have I/O operations */
30 Please respect this inclusion order. Some extra headers may be 36 Please respect this inclusion order. Some extra headers may be
31 required for a given driver (e.g. "lm75.h"). 37 required for a given driver (e.g. "lm75.h").
32 38
33* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, ISA addresses 39* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, ISA addresses
34 are no more handled by the i2c core. 40 are no more handled by the i2c core. Address ranges are no more
41 supported either, define each individual address separately.
35 SENSORS_INSMOD_<n> becomes I2C_CLIENT_INSMOD_<n>. 42 SENSORS_INSMOD_<n> becomes I2C_CLIENT_INSMOD_<n>.
36 43
37* [Client data] Get rid of sysctl_id. Try using standard names for 44* [Client data] Get rid of sysctl_id. Try using standard names for
@@ -48,23 +55,23 @@ Technical changes:
48 int kind); 55 int kind);
49 static void lm75_init_client(struct i2c_client *client); 56 static void lm75_init_client(struct i2c_client *client);
50 static int lm75_detach_client(struct i2c_client *client); 57 static int lm75_detach_client(struct i2c_client *client);
51 static void lm75_update_client(struct i2c_client *client); 58 static struct lm75_data lm75_update_device(struct device *dev);
52 59
53* [Sysctl] All sysctl stuff is of course gone (defines, ctl_table 60* [Sysctl] All sysctl stuff is of course gone (defines, ctl_table
54 and functions). Instead, you have to define show and set functions for 61 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 62 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 63 existing 2.6 driver for details (it87 for example). Don't forget
57 to define the attributes for each file (this is that step that 64 to define the attributes for each file (this is that step that
58 links callback functions). Use the file names specified in 65 links callback functions). Use the file names specified in
59 Documentation/i2c/sysfs-interface for the individual files. Also 66 Documentation/hwmon/sysfs-interface for the individual files. Also
60 convert the units these files read and write to the specified ones. 67 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 68 If you need to add a new type of file, please discuss it on the
62 sensors mailing list <lm-sensors@lm-sensors.org> by providing a 69 sensors mailing list <lm-sensors@lm-sensors.org> by providing a
63 patch to the Documentation/i2c/sysfs-interface file. 70 patch to the Documentation/hwmon/sysfs-interface file.
64 71
65* [Attach] For I2C drivers, the attach function should make sure 72* [Attach] For I2C drivers, the attach function should make sure
66 that the adapter's class has I2C_CLASS_HWMON, using the 73 that the adapter's class has I2C_CLASS_HWMON (or whatever class is
67 following construct: 74 suitable for your driver), using the following construct:
68 if (!(adapter->class & I2C_CLASS_HWMON)) 75 if (!(adapter->class & I2C_CLASS_HWMON))
69 return 0; 76 return 0;
70 ISA-only drivers of course don't need this. 77 ISA-only drivers of course don't need this.
@@ -72,23 +79,23 @@ Technical changes:
72 79
73* [Detect] As mentioned earlier, the flags parameter is gone. 80* [Detect] As mentioned earlier, the flags parameter is gone.
74 The type_name and client_name strings are replaced by a single 81 The type_name and client_name strings are replaced by a single
75 name string, which will be filled with a lowercase, short string 82 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 83 In i2c-only drivers, drop the i2c_is_isa_adapter check, it's
78 useless. Same for isa-only drivers, as the test would always be 84 useless. Same for isa-only drivers, as the test would always be
79 true. Only hybrid drivers (which are quite rare) still need it. 85 true. Only hybrid drivers (which are quite rare) still need it.
80 The errorN labels are reduced to the number needed. If that number 86 The labels used for error paths are reduced to the number needed.
81 is 2 (i2c-only drivers), it is advised that the labels are named 87 It is advised that the labels are given descriptive names such as
82 exit and exit_free. For i2c+isa drivers, labels should be named 88 exit and exit_free. Don't forget to properly set err before
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. 89 jumping to error labels. By the way, labels should be left-aligned.
85 Use kzalloc instead of kmalloc. 90 Use kzalloc instead of kmalloc.
86 Use i2c_set_clientdata to set the client data (as opposed to 91 Use i2c_set_clientdata to set the client data (as opposed to
87 a direct access to client->data). 92 a direct access to client->data).
88 Use strlcpy instead of strcpy to copy the client name. 93 Use strlcpy instead of strcpy or snprintf to copy the client name.
89 Replace the sysctl directory registration by calls to 94 Replace the sysctl directory registration by calls to
90 device_create_file. Move the driver initialization before any 95 device_create_file. Move the driver initialization before any
91 sysfs file creation. 96 sysfs file creation.
97 Register the client with the hwmon class (using hwmon_device_register)
98 if applicable.
92 Drop client->id. 99 Drop client->id.
93 Drop any 24RF08 corruption prevention you find, as this is now done 100 Drop any 24RF08 corruption prevention you find, as this is now done
94 at the i2c-core level, and doing it twice voids it. 101 at the i2c-core level, and doing it twice voids it.
@@ -96,19 +103,25 @@ Technical changes:
96 103
97* [Init] Limits must not be set by the driver (can be done later in 104* [Init] Limits must not be set by the driver (can be done later in
98 user-space). Chip should not be reset default (although a module 105 user-space). Chip should not be reset default (although a module
99 parameter may be used to force is), and initialization should be 106 parameter may be used to force it), and initialization should be
100 limited to the strictly necessary steps. 107 limited to the strictly necessary steps.
101 108
102* [Detach] Get rid of data, remove the call to 109* [Detach] Remove the call to i2c_deregister_entry. Do not log an
103 i2c_deregister_entry. Do not log an error message if 110 error message if i2c_detach_client fails, as i2c-core will now do
104 i2c_detach_client fails, as i2c-core will now do it for you. 111 it for you.
112 Unregister from the hwmon class if applicable.
105 113
106* [Update] Don't access client->data directly, use 114* [Update] The function prototype changed, it is now
107 i2c_get_clientdata(client) instead. 115 passed a device structure, which you have to convert to a client
116 using to_i2c_client(dev). The update function should return a
117 pointer to the client data.
118 Don't access client->data directly, use i2c_get_clientdata(client)
119 instead.
120 Use time_after() instead of direct jiffies comparison.
108 121
109* [Interface] Init function should not print anything. Make sure 122* [Interface] Make sure there is a MODULE_LICENSE() line, at the bottom
110 there is a MODULE_LICENSE() line, at the bottom of the file 123 of the file (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this
111 (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this order). 124 order).
112 125
113* [Driver] The flags field of the i2c_driver structure is gone. 126* [Driver] The flags field of the i2c_driver structure is gone.
114 I2C_DF_NOTIFY is now the default behavior. 127 I2C_DF_NOTIFY is now the default behavior.
@@ -118,21 +131,17 @@ Coding policy:
118* [Copyright] Use (C), not (c), for copyright. 131* [Copyright] Use (C), not (c), for copyright.
119 132
120* [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you 133* [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you
121 can. Calls to printk/pr_debug for debugging purposes are replaced 134 can. Calls to printk for debugging purposes are replaced by calls to
122 by calls to dev_dbg. Here is an example on how to call it (taken 135 dev_dbg where possible, else to pr_debug. Here is an example of how
123 from lm75_detect): 136 to call it (taken from lm75_detect):
124 dev_dbg(&client->dev, "Starting lm75 update\n"); 137 dev_dbg(&client->dev, "Starting lm75 update\n");
125 Replace other printk calls with the dev_info, dev_err or dev_warn 138 Replace other printk calls with the dev_info, dev_err or dev_warn
126 function, as appropriate. 139 function, as appropriate.
127 140
128* [Constants] Constants defines (registers, conversions, initial 141* [Constants] Constants defines (registers, conversions) should be
129 values) should be aligned. This greatly improves readability. 142 aligned. This greatly improves readability.
130 Same goes for variables declarations. Alignments are achieved by the 143 Alignments are achieved by the means of tabs, not spaces. Remember
131 means of tabs, not spaces. Remember that tabs are set to 8 in the 144 that tabs are set to 8 in the Linux kernel code.
132 Linux kernel code.
133
134* [Structure definition] The name field should be standardized. All
135 lowercase and as simple as the driver name itself (e.g. "lm75").
136 145
137* [Layout] Avoid extra empty lines between comments and what they 146* [Layout] Avoid extra empty lines between comments and what they
138 comment. Respect the coding style (see Documentation/CodingStyle), 147 comment. Respect the coding style (see Documentation/CodingStyle),