From 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 Mon Sep 17 00:00:00 2001 From: Linus Torvalds Date: Sat, 16 Apr 2005 15:20:36 -0700 Subject: Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip! --- Documentation/i2c/porting-clients | 133 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Documentation/i2c/porting-clients (limited to 'Documentation/i2c/porting-clients') diff --git a/Documentation/i2c/porting-clients b/Documentation/i2c/porting-clients new file mode 100644 index 0000000..5640491 --- /dev/null +++ b/Documentation/i2c/porting-clients @@ -0,0 +1,133 @@ +Revision 4, 2004-03-30 +Jean Delvare +Greg KH + +This is a guide on how to convert I2C chip drivers from Linux 2.4 to +Linux 2.6. I have been using existing drivers (lm75, lm78) as examples. +Then I converted a driver myself (lm83) and updated this document. + +There are two sets of points below. The first set concerns technical +changes. The second set concerns coding policy. Both are mandatory. + +Although reading this guide will help you porting drivers, I suggest +you keep an eye on an already ported driver while porting your own +driver. This will help you a lot understanding what this guide +exactly means. Choose the chip driver that is the more similar to +yours for best results. + +Technical changes: + +* [Includes] Get rid of "version.h". Replace with + . Includes typically look like that: + #include + #include + #include + #include + #include + #include /* if you need VRM support */ + #include /* if you have I/O operations */ + 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 + becomes I2C_CLIENT_ISA_END. + +* [Client data] Get rid of sysctl_id. Try using standard names for + register values (for example, temp_os becomes temp_max). You're + still relatively free here, but you *have* to follow the standard + names for sysfs files (see the Sysctl section below). + +* [Function prototypes] The detect functions loses its flags + parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions + are off the list of prototypes. This usually leaves five + prototypes: + static int lm75_attach_adapter(struct i2c_adapter *adapter); + static int lm75_detect(struct i2c_adapter *adapter, int address, + int kind); + static void lm75_init_client(struct i2c_client *client); + static int lm75_detach_client(struct i2c_client *client); + static void lm75_update_client(struct i2c_client *client); + +* [Sysctl] All sysctl stuff is of course gone (defines, ctl_table + and functions). Instead, you have to define show and set functions for + each sysfs file. Only define set for writable values. Take a look at an + existing 2.6 driver for details (lm78 for example). Don't forget + to define the attributes for each file (this is that step that + links callback functions). Use the file names specified in + Documentation/i2c/sysfs-interface for the individual files. Also + convert the units these files read and write to the specified ones. + If you need to add a new type of file, please discuss it on the + sensors mailing list by providing a + patch to the Documentation/i2c/sysfs-interface file. + +* [Attach] For I2C drivers, the attach function should make sure + that the adapter's class has I2C_CLASS_HWMON, using the + following construct: + if (!(adapter->class & I2C_CLASS_HWMON)) + return 0; + ISA-only drivers of course don't need this. + +* [Detect] As mentioned earlier, the flags parameter is gone. + The type_name and client_name strings are replaced by a single + name string, which will be filled with a lowercase, short string + (typically the driver name, e.g. "lm75"). + In i2c-only drivers, drop the i2c_is_isa_adapter check, it's + useless. + The errorN labels are reduced to the number needed. If that number + is 2 (i2c-only drivers), it is advised that the labels are named + exit and exit_free. For i2c+isa drivers, labels should be named + 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 i2c_set_clientdata to set the client data (as opposed to + a direct access to client->data). + Use strlcpy instead of strcpy to copy the client name. + Replace the sysctl directory registration by calls to + device_create_file. Move the driver initialization before any + sysfs file creation. + Drop client->id. + +* [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 + i2c_deregister_entry. + +* [Update] Don't access client->data directly, use + i2c_get_clientdata(client) instead. + +* [Interface] Init function should not print anything. Make sure + there is a MODULE_LICENSE() line, at the bottom of the file + (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this order). + +Coding policy: + +* [Copyright] Use (C), not (c), for copyright. + +* [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you + 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 + from lm75_detect): + dev_dbg(&client->dev, "Starting lm75 update\n"); + Replace other printk calls with the dev_info, dev_err or dev_warn + function, as appropriate. + +* [Constants] Constants defines (registers, conversions, initial + values) should be aligned. This greatly improves readability. + Same goes for variables declarations. Alignments are achieved by the + means of tabs, not spaces. Remember that tabs are set to 8 in the + Linux kernel code. + +* [Structure definition] The name field should be standardized. All + lowercase and as simple as the driver name itself (e.g. "lm75"). + +* [Layout] Avoid extra empty lines between comments and what they + comment. Respect the coding style (see Documentation/CodingStyle), + 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/), + and that remaining comments still match the code. Merging comment + lines when possible is encouraged. -- cgit v1.1