Commit 92e54f42 authored by Jean Delvare's avatar Jean Delvare Committed by Patrick Mochel

[PATCH] I2C: i2c documentation update (1/2)

Here is an update to my 2.4 to 2.6 i2c client porting guide. The changes
were inspired by the feedback I got with the drivers that have been
ported so far.
parent 9f3e7af6
Revision 3, 2003-10-04 Revision 4, 2004-03-30
Jean Delvare <khali@linux-fr.org> Jean Delvare <khali@linux-fr.org>
Greg KH <greg@kroah.com> Greg KH <greg@kroah.com>
...@@ -24,9 +24,10 @@ Technical changes: ...@@ -24,9 +24,10 @@ Technical changes:
#include <linux/slab.h> #include <linux/slab.h>
#include <linux/i2c.h> #include <linux/i2c.h>
#include <linux/i2c-sensor.h> #include <linux/i2c-sensor.h>
#include <linux/i2c-vid.h> /* if you need VRM support */ #include <linux/i2c-vid.h> /* if you need VRM support */
#include <asm/io.h> /* if you have I/O operations */ #include <asm/io.h> /* if you have I/O operations */
Some extra headers may be required for a given driver. Please respect this inclusion order. Some extra headers may be
required for a given driver (e.g. "lm75.h").
* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, SENSORS_ISA_END * [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, SENSORS_ISA_END
becomes I2C_CLIENT_ISA_END. becomes I2C_CLIENT_ISA_END.
...@@ -37,9 +38,9 @@ Technical changes: ...@@ -37,9 +38,9 @@ Technical changes:
names for sysfs files (see the Sysctl section below). names for sysfs files (see the Sysctl section below).
* [Function prototypes] The detect functions loses its flags * [Function prototypes] The detect functions loses its flags
parameter. Sysctl (e.g. lm75_temp) and miscellaneous (e.g. parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions
swap_bytes) functions are off the list of prototypes. This are off the list of prototypes. This usually leaves five
usually leaves five prototypes: prototypes:
static int lm75_attach_adapter(struct i2c_adapter *adapter); static int lm75_attach_adapter(struct i2c_adapter *adapter);
static int lm75_detect(struct i2c_adapter *adapter, int address, static int lm75_detect(struct i2c_adapter *adapter, int address,
int kind); int kind);
...@@ -70,13 +71,14 @@ Technical changes: ...@@ -70,13 +71,14 @@ Technical changes:
* [Detect] As mentioned earlier, the flags parameter is gone. * [Detect] As mentioned earlier, the flags parameter is gone.
The type_name and client_name strings are replaced by a single The type_name and client_name strings are replaced by a single
name string, which will be filled with a lowercase, short string name string, which will be filled with a lowercase, short string
(typically the driver name, e.g. "lm75"). The errorN labels are (typically the driver name, e.g. "lm75").
reduced to the number needed. If that number is 2 (i2c-only In i2c-only drivers, drop the i2c_is_isa_adapter check, it's
drivers), it is advised that the labels are named exit and useless.
exit_free. For i2c+isa drivers, labels should be named ERROR0, The errorN labels are reduced to the number needed. If that number
ERROR1 and ERROR2. Don't forget to properly set err before is 2 (i2c-only drivers), it is advised that the labels are named
jumping to error labels. By the way, labels should be exit and exit_free. For i2c+isa drivers, labels should be named
left-aligned. ERROR0, ERROR1 and ERROR2. Don't forget to properly set err before
jumping to error labels. By the way, labels should be left-aligned.
Use memset to fill the client and data area with 0x00. Use memset to fill the client and data area with 0x00.
Use i2c_set_clientdata to set the client data (as opposed to Use i2c_set_clientdata to set the client data (as opposed to
a direct access to client->data). a direct access to client->data).
...@@ -85,6 +87,11 @@ Technical changes: ...@@ -85,6 +87,11 @@ Technical changes:
device_create_file. Move the driver initialization before any device_create_file. Move the driver initialization before any
sysfs file creation. sysfs file creation.
* [Init] Limits must not be set by the driver (can be done later in
user-space). Chip should not be reset default (although a module
parameter may be used to force is), and initialization should be
limited to the strictly necessary steps.
* [Detach] Get rid of data, remove the call to * [Detach] Get rid of data, remove the call to
i2c_deregister_entry. i2c_deregister_entry.
...@@ -92,7 +99,8 @@ Technical changes: ...@@ -92,7 +99,8 @@ Technical changes:
i2c_get_clientdata(client) instead. i2c_get_clientdata(client) instead.
* [Interface] Init function should not print anything. Make sure * [Interface] Init function should not print anything. Make sure
there is a MODULE_LICENSE() line. there is a MODULE_LICENSE() line, at the bottom of the file
(after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this order).
Coding policy: Coding policy:
...@@ -102,8 +110,7 @@ Coding policy: ...@@ -102,8 +110,7 @@ Coding policy:
can. Calls to printk/pr_debug for debugging purposes are replaced can. Calls to printk/pr_debug for debugging purposes are replaced
by calls to dev_dbg. Here is an example on how to call it (taken by calls to dev_dbg. Here is an example on how to call it (taken
from lm75_detect): from lm75_detect):
dev_dbg(&adapter->dev, dev_dbg(&client->dev, "Starting lm75 update\n");
"lm75_detect called for an ISA bus adapter?!?\n");
Replace other printk calls with the dev_info, dev_err or dev_warn Replace other printk calls with the dev_info, dev_err or dev_warn
function, as appropriate. function, as appropriate.
...@@ -119,3 +126,8 @@ Coding policy: ...@@ -119,3 +126,8 @@ Coding policy:
* [Layout] Avoid extra empty lines between comments and what they * [Layout] Avoid extra empty lines between comments and what they
comment. Respect the coding style (see Documentation/CodingStyle), comment. Respect the coding style (see Documentation/CodingStyle),
in particular when it comes to placing curly braces. in particular when it comes to placing curly braces.
* [Comments] Make sure that no comment refers to a file that isn't
part of the Linux source tree (typically doc/chips/<chip name>),
and that remaining comments still match the code. Merging comment
lines when possible is encouraged.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment