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