Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | This is a small guide for those who want to write kernel drivers for I2C |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 2 | or SMBus devices, using Linux as the protocol host/master (not slave). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 3 | |
| 4 | To set up a driver, you need to do several things. Some are optional, and |
| 5 | some things can be done slightly or completely different. Use this as a |
| 6 | guide, not as a rule book! |
| 7 | |
| 8 | |
| 9 | General remarks |
| 10 | =============== |
| 11 | |
| 12 | Try to keep the kernel namespace as clean as possible. The best way to |
| 13 | do this is to use a unique prefix for all global symbols. This is |
| 14 | especially important for exported symbols, but it is a good idea to do |
| 15 | it for non-exported symbols too. We will use the prefix `foo_' in this |
| 16 | tutorial, and `FOO_' for preprocessor variables. |
| 17 | |
| 18 | |
| 19 | The driver structure |
| 20 | ==================== |
| 21 | |
| 22 | Usually, you will implement a single driver structure, and instantiate |
| 23 | all clients from it. Remember, a driver structure contains general access |
David Brownell | f37dd80 | 2007-02-13 22:09:00 +0100 | [diff] [blame] | 24 | routines, and should be zero-initialized except for fields with data you |
| 25 | provide. A client structure holds device-specific information like the |
| 26 | driver model device node, and its I2C address. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 27 | |
| 28 | static struct i2c_driver foo_driver = { |
Jean Delvare | d45d204 | 2005-11-26 20:55:35 +0100 | [diff] [blame] | 29 | .driver = { |
Jean Delvare | d45d204 | 2005-11-26 20:55:35 +0100 | [diff] [blame] | 30 | .name = "foo", |
| 31 | }, |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 32 | |
| 33 | /* iff driver uses driver model ("new style") binding model: */ |
| 34 | .probe = foo_probe, |
| 35 | .remove = foo_remove, |
| 36 | |
| 37 | /* else, driver uses "legacy" binding model: */ |
David Brownell | f37dd80 | 2007-02-13 22:09:00 +0100 | [diff] [blame] | 38 | .attach_adapter = foo_attach_adapter, |
| 39 | .detach_client = foo_detach_client, |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 40 | |
| 41 | /* these may be used regardless of the driver binding model */ |
David Brownell | f37dd80 | 2007-02-13 22:09:00 +0100 | [diff] [blame] | 42 | .shutdown = foo_shutdown, /* optional */ |
| 43 | .suspend = foo_suspend, /* optional */ |
| 44 | .resume = foo_resume, /* optional */ |
| 45 | .command = foo_command, /* optional */ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 46 | } |
| 47 | |
David Brownell | f37dd80 | 2007-02-13 22:09:00 +0100 | [diff] [blame] | 48 | The name field is the driver name, and must not contain spaces. It |
| 49 | should match the module name (if the driver can be compiled as a module), |
| 50 | although you can use MODULE_ALIAS (passing "foo" in this example) to add |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 51 | another name for the module. If the driver name doesn't match the module |
| 52 | name, the module won't be automatically loaded (hotplug/coldplug). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 53 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 54 | All other fields are for call-back functions which will be explained |
| 55 | below. |
| 56 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 57 | |
| 58 | Extra client data |
| 59 | ================= |
| 60 | |
David Brownell | f37dd80 | 2007-02-13 22:09:00 +0100 | [diff] [blame] | 61 | Each client structure has a special `data' field that can point to any |
| 62 | structure at all. You should use this to keep device-specific data, |
| 63 | especially in drivers that handle multiple I2C or SMBUS devices. You |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 64 | do not always need this, but especially for `sensors' drivers, it can |
| 65 | be very useful. |
| 66 | |
David Brownell | f37dd80 | 2007-02-13 22:09:00 +0100 | [diff] [blame] | 67 | /* store the value */ |
| 68 | void i2c_set_clientdata(struct i2c_client *client, void *data); |
| 69 | |
| 70 | /* retrieve the value */ |
| 71 | void *i2c_get_clientdata(struct i2c_client *client); |
| 72 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 73 | An example structure is below. |
| 74 | |
| 75 | struct foo_data { |
Jean Delvare | 2445eb6 | 2005-10-17 23:16:25 +0200 | [diff] [blame] | 76 | struct i2c_client client; |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 77 | struct semaphore lock; /* For ISA access in `sensors' drivers. */ |
| 78 | int sysctl_id; /* To keep the /proc directory entry for |
| 79 | `sensors' drivers. */ |
| 80 | enum chips type; /* To keep the chips type for `sensors' drivers. */ |
| 81 | |
| 82 | /* Because the i2c bus is slow, it is often useful to cache the read |
| 83 | information of a chip for some time (for example, 1 or 2 seconds). |
| 84 | It depends of course on the device whether this is really worthwhile |
| 85 | or even sensible. */ |
| 86 | struct semaphore update_lock; /* When we are reading lots of information, |
| 87 | another process should not update the |
| 88 | below information */ |
| 89 | char valid; /* != 0 if the following fields are valid. */ |
| 90 | unsigned long last_updated; /* In jiffies */ |
| 91 | /* Add the read information here too */ |
| 92 | }; |
| 93 | |
| 94 | |
| 95 | Accessing the client |
| 96 | ==================== |
| 97 | |
| 98 | Let's say we have a valid client structure. At some time, we will need |
| 99 | to gather information from the client, or write new information to the |
| 100 | client. How we will export this information to user-space is less |
| 101 | important at this moment (perhaps we do not need to do this at all for |
| 102 | some obscure clients). But we need generic reading and writing routines. |
| 103 | |
| 104 | I have found it useful to define foo_read and foo_write function for this. |
| 105 | For some cases, it will be easier to call the i2c functions directly, |
| 106 | but many chips have some kind of register-value idea that can easily |
| 107 | be encapsulated. Also, some chips have both ISA and I2C interfaces, and |
| 108 | it useful to abstract from this (only for `sensors' drivers). |
| 109 | |
| 110 | The below functions are simple examples, and should not be copied |
| 111 | literally. |
| 112 | |
| 113 | int foo_read_value(struct i2c_client *client, u8 reg) |
| 114 | { |
| 115 | if (reg < 0x10) /* byte-sized register */ |
| 116 | return i2c_smbus_read_byte_data(client,reg); |
| 117 | else /* word-sized register */ |
| 118 | return i2c_smbus_read_word_data(client,reg); |
| 119 | } |
| 120 | |
| 121 | int foo_write_value(struct i2c_client *client, u8 reg, u16 value) |
| 122 | { |
| 123 | if (reg == 0x10) /* Impossible to write - driver error! */ { |
| 124 | return -1; |
| 125 | else if (reg < 0x10) /* byte-sized register */ |
| 126 | return i2c_smbus_write_byte_data(client,reg,value); |
| 127 | else /* word-sized register */ |
| 128 | return i2c_smbus_write_word_data(client,reg,value); |
| 129 | } |
| 130 | |
| 131 | For sensors code, you may have to cope with ISA registers too. Something |
| 132 | like the below often works. Note the locking! |
| 133 | |
| 134 | int foo_read_value(struct i2c_client *client, u8 reg) |
| 135 | { |
| 136 | int res; |
| 137 | if (i2c_is_isa_client(client)) { |
| 138 | down(&(((struct foo_data *) (client->data)) -> lock)); |
| 139 | outb_p(reg,client->addr + FOO_ADDR_REG_OFFSET); |
| 140 | res = inb_p(client->addr + FOO_DATA_REG_OFFSET); |
| 141 | up(&(((struct foo_data *) (client->data)) -> lock)); |
| 142 | return res; |
| 143 | } else |
| 144 | return i2c_smbus_read_byte_data(client,reg); |
| 145 | } |
| 146 | |
| 147 | Writing is done the same way. |
| 148 | |
| 149 | |
| 150 | Probing and attaching |
| 151 | ===================== |
| 152 | |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 153 | The Linux I2C stack was originally written to support access to hardware |
| 154 | monitoring chips on PC motherboards, and thus it embeds some assumptions |
| 155 | that are more appropriate to SMBus (and PCs) than to I2C. One of these |
| 156 | assumptions is that most adapters and devices drivers support the SMBUS_QUICK |
| 157 | protocol to probe device presence. Another is that devices and their drivers |
| 158 | can be sufficiently configured using only such probe primitives. |
| 159 | |
| 160 | As Linux and its I2C stack became more widely used in embedded systems |
| 161 | and complex components such as DVB adapters, those assumptions became more |
| 162 | problematic. Drivers for I2C devices that issue interrupts need more (and |
| 163 | different) configuration information, as do drivers handling chip variants |
| 164 | that can't be distinguished by protocol probing, or which need some board |
| 165 | specific information to operate correctly. |
| 166 | |
| 167 | Accordingly, the I2C stack now has two models for associating I2C devices |
| 168 | with their drivers: the original "legacy" model, and a newer one that's |
| 169 | fully compatible with the Linux 2.6 driver model. These models do not mix, |
| 170 | since the "legacy" model requires drivers to create "i2c_client" device |
| 171 | objects after SMBus style probing, while the Linux driver model expects |
| 172 | drivers to be given such device objects in their probe() routines. |
| 173 | |
| 174 | |
| 175 | Standard Driver Model Binding ("New Style") |
| 176 | ------------------------------------------- |
| 177 | |
| 178 | System infrastructure, typically board-specific initialization code or |
| 179 | boot firmware, reports what I2C devices exist. For example, there may be |
| 180 | a table, in the kernel or from the boot loader, identifying I2C devices |
| 181 | and linking them to board-specific configuration information about IRQs |
| 182 | and other wiring artifacts, chip type, and so on. That could be used to |
| 183 | create i2c_client objects for each I2C device. |
| 184 | |
| 185 | I2C device drivers using this binding model work just like any other |
| 186 | kind of driver in Linux: they provide a probe() method to bind to |
| 187 | those devices, and a remove() method to unbind. |
| 188 | |
| 189 | static int foo_probe(struct i2c_client *client); |
| 190 | static int foo_remove(struct i2c_client *client); |
| 191 | |
| 192 | Remember that the i2c_driver does not create those client handles. The |
| 193 | handle may be used during foo_probe(). If foo_probe() reports success |
| 194 | (zero not a negative status code) it may save the handle and use it until |
| 195 | foo_remove() returns. That binding model is used by most Linux drivers. |
| 196 | |
| 197 | Drivers match devices when i2c_client.driver_name and the driver name are |
| 198 | the same; this approach is used in several other busses that don't have |
| 199 | device typing support in the hardware. The driver and module name should |
| 200 | match, so hotplug/coldplug mechanisms will modprobe the driver. |
| 201 | |
| 202 | |
| 203 | Legacy Driver Binding Model |
| 204 | --------------------------- |
| 205 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 206 | Most i2c devices can be present on several i2c addresses; for some this |
| 207 | is determined in hardware (by soldering some chip pins to Vcc or Ground), |
| 208 | for others this can be changed in software (by writing to specific client |
| 209 | registers). Some devices are usually on a specific address, but not always; |
| 210 | and some are even more tricky. So you will probably need to scan several |
| 211 | i2c addresses for your clients, and do some sort of detection to see |
| 212 | whether it is actually a device supported by your driver. |
| 213 | |
| 214 | To give the user a maximum of possibilities, some default module parameters |
| 215 | are defined to help determine what addresses are scanned. Several macros |
| 216 | are defined in i2c.h to help you support them, as well as a generic |
| 217 | detection algorithm. |
| 218 | |
| 219 | You do not have to use this parameter interface; but don't try to use |
Jean Delvare | 2ed2dc3 | 2005-07-31 21:42:02 +0200 | [diff] [blame] | 220 | function i2c_probe() if you don't. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 221 | |
| 222 | NOTE: If you want to write a `sensors' driver, the interface is slightly |
| 223 | different! See below. |
| 224 | |
| 225 | |
| 226 | |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 227 | Probing classes (Legacy model) |
| 228 | ------------------------------ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 229 | |
| 230 | All parameters are given as lists of unsigned 16-bit integers. Lists are |
| 231 | terminated by I2C_CLIENT_END. |
| 232 | The following lists are used internally: |
| 233 | |
| 234 | normal_i2c: filled in by the module writer. |
| 235 | A list of I2C addresses which should normally be examined. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 236 | probe: insmod parameter. |
| 237 | A list of pairs. The first value is a bus number (-1 for any I2C bus), |
| 238 | the second is the address. These addresses are also probed, as if they |
| 239 | were in the 'normal' list. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 240 | ignore: insmod parameter. |
| 241 | A list of pairs. The first value is a bus number (-1 for any I2C bus), |
| 242 | the second is the I2C address. These addresses are never probed. |
Jean Delvare | f4b5026 | 2005-07-31 21:49:03 +0200 | [diff] [blame] | 243 | This parameter overrules the 'normal_i2c' list only. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 244 | force: insmod parameter. |
| 245 | A list of pairs. The first value is a bus number (-1 for any I2C bus), |
| 246 | the second is the I2C address. A device is blindly assumed to be on |
| 247 | the given address, no probing is done. |
| 248 | |
Jean Delvare | f4b5026 | 2005-07-31 21:49:03 +0200 | [diff] [blame] | 249 | Additionally, kind-specific force lists may optionally be defined if |
| 250 | the driver supports several chip kinds. They are grouped in a |
| 251 | NULL-terminated list of pointers named forces, those first element if the |
| 252 | generic force list mentioned above. Each additional list correspond to an |
| 253 | insmod parameter of the form force_<kind>. |
| 254 | |
Jean Delvare | b3d5496 | 2005-04-02 20:31:02 +0200 | [diff] [blame] | 255 | Fortunately, as a module writer, you just have to define the `normal_i2c' |
| 256 | parameter. The complete declaration could look like this: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 257 | |
Jean Delvare | b3d5496 | 2005-04-02 20:31:02 +0200 | [diff] [blame] | 258 | /* Scan 0x37, and 0x48 to 0x4f */ |
| 259 | static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c, |
| 260 | 0x4d, 0x4e, 0x4f, I2C_CLIENT_END }; |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 261 | |
| 262 | /* Magic definition of all other variables and things */ |
| 263 | I2C_CLIENT_INSMOD; |
Jean Delvare | f4b5026 | 2005-07-31 21:49:03 +0200 | [diff] [blame] | 264 | /* Or, if your driver supports, say, 2 kind of devices: */ |
| 265 | I2C_CLIENT_INSMOD_2(foo, bar); |
| 266 | |
| 267 | If you use the multi-kind form, an enum will be defined for you: |
| 268 | enum chips { any_chip, foo, bar, ... } |
| 269 | You can then (and certainly should) use it in the driver code. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 270 | |
Jean Delvare | b3d5496 | 2005-04-02 20:31:02 +0200 | [diff] [blame] | 271 | Note that you *have* to call the defined variable `normal_i2c', |
| 272 | without any prefix! |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 273 | |
| 274 | |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 275 | Attaching to an adapter (Legacy model) |
| 276 | -------------------------------------- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 277 | |
| 278 | Whenever a new adapter is inserted, or for all adapters if the driver is |
| 279 | being registered, the callback attach_adapter() is called. Now is the |
| 280 | time to determine what devices are present on the adapter, and to register |
| 281 | a client for each of them. |
| 282 | |
| 283 | The attach_adapter callback is really easy: we just call the generic |
| 284 | detection function. This function will scan the bus for us, using the |
| 285 | information as defined in the lists explained above. If a device is |
| 286 | detected at a specific address, another callback is called. |
| 287 | |
| 288 | int foo_attach_adapter(struct i2c_adapter *adapter) |
| 289 | { |
| 290 | return i2c_probe(adapter,&addr_data,&foo_detect_client); |
| 291 | } |
| 292 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 293 | Remember, structure `addr_data' is defined by the macros explained above, |
| 294 | so you do not have to define it yourself. |
| 295 | |
Jean Delvare | 2ed2dc3 | 2005-07-31 21:42:02 +0200 | [diff] [blame] | 296 | The i2c_probe function will call the foo_detect_client |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 297 | function only for those i2c addresses that actually have a device on |
| 298 | them (unless a `force' parameter was used). In addition, addresses that |
| 299 | are already in use (by some other registered client) are skipped. |
| 300 | |
| 301 | |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 302 | The detect client function (Legacy model) |
| 303 | ----------------------------------------- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 304 | |
Jean Delvare | 2ed2dc3 | 2005-07-31 21:42:02 +0200 | [diff] [blame] | 305 | The detect client function is called by i2c_probe. The `kind' parameter |
| 306 | contains -1 for a probed detection, 0 for a forced detection, or a positive |
| 307 | number for a forced detection with a chip type forced. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 308 | |
| 309 | Below, some things are only needed if this is a `sensors' driver. Those |
| 310 | parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */ |
| 311 | markers. |
| 312 | |
Jean Delvare | a89ba0b | 2005-08-09 20:17:55 +0200 | [diff] [blame] | 313 | Returning an error different from -ENODEV in a detect function will cause |
| 314 | the detection to stop: other addresses and adapters won't be scanned. |
| 315 | This should only be done on fatal or internal errors, such as a memory |
| 316 | shortage or i2c_attach_client failing. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 317 | |
| 318 | For now, you can ignore the `flags' parameter. It is there for future use. |
| 319 | |
| 320 | int foo_detect_client(struct i2c_adapter *adapter, int address, |
| 321 | unsigned short flags, int kind) |
| 322 | { |
| 323 | int err = 0; |
| 324 | int i; |
| 325 | struct i2c_client *new_client; |
| 326 | struct foo_data *data; |
| 327 | const char *client_name = ""; /* For non-`sensors' drivers, put the real |
| 328 | name here! */ |
| 329 | |
| 330 | /* Let's see whether this adapter can support what we need. |
| 331 | Please substitute the things you need here! |
| 332 | For `sensors' drivers, add `! is_isa &&' to the if statement */ |
| 333 | if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA | |
| 334 | I2C_FUNC_SMBUS_WRITE_BYTE)) |
| 335 | goto ERROR0; |
| 336 | |
| 337 | /* SENSORS ONLY START */ |
| 338 | const char *type_name = ""; |
| 339 | int is_isa = i2c_is_isa_adapter(adapter); |
| 340 | |
Jean Delvare | 02ff982 | 2005-07-20 00:05:33 +0200 | [diff] [blame] | 341 | /* Do this only if the chip can additionally be found on the ISA bus |
| 342 | (hybrid chip). */ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 343 | |
Jean Delvare | 02ff982 | 2005-07-20 00:05:33 +0200 | [diff] [blame] | 344 | if (is_isa) { |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 345 | |
| 346 | /* Discard immediately if this ISA range is already used */ |
Jeff Garzik | d61780c0 | 2005-10-30 15:01:51 -0800 | [diff] [blame] | 347 | /* FIXME: never use check_region(), only request_region() */ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 348 | if (check_region(address,FOO_EXTENT)) |
| 349 | goto ERROR0; |
| 350 | |
| 351 | /* Probe whether there is anything on this address. |
| 352 | Some example code is below, but you will have to adapt this |
| 353 | for your own driver */ |
| 354 | |
| 355 | if (kind < 0) /* Only if no force parameter was used */ { |
| 356 | /* We may need long timeouts at least for some chips. */ |
| 357 | #define REALLY_SLOW_IO |
| 358 | i = inb_p(address + 1); |
| 359 | if (inb_p(address + 2) != i) |
| 360 | goto ERROR0; |
| 361 | if (inb_p(address + 3) != i) |
| 362 | goto ERROR0; |
| 363 | if (inb_p(address + 7) != i) |
| 364 | goto ERROR0; |
| 365 | #undef REALLY_SLOW_IO |
| 366 | |
| 367 | /* Let's just hope nothing breaks here */ |
| 368 | i = inb_p(address + 5) & 0x7f; |
| 369 | outb_p(~i & 0x7f,address+5); |
| 370 | if ((inb_p(address + 5) & 0x7f) != (~i & 0x7f)) { |
| 371 | outb_p(i,address+5); |
| 372 | return 0; |
| 373 | } |
| 374 | } |
| 375 | } |
| 376 | |
| 377 | /* SENSORS ONLY END */ |
| 378 | |
| 379 | /* OK. For now, we presume we have a valid client. We now create the |
| 380 | client structure, even though we cannot fill it completely yet. |
| 381 | But it allows us to access several i2c functions safely */ |
| 382 | |
Jean Delvare | 2445eb6 | 2005-10-17 23:16:25 +0200 | [diff] [blame] | 383 | if (!(data = kzalloc(sizeof(struct foo_data), GFP_KERNEL))) { |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 384 | err = -ENOMEM; |
| 385 | goto ERROR0; |
| 386 | } |
| 387 | |
Jean Delvare | 2445eb6 | 2005-10-17 23:16:25 +0200 | [diff] [blame] | 388 | new_client = &data->client; |
| 389 | i2c_set_clientdata(new_client, data); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 390 | |
| 391 | new_client->addr = address; |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 392 | new_client->adapter = adapter; |
| 393 | new_client->driver = &foo_driver; |
| 394 | new_client->flags = 0; |
| 395 | |
| 396 | /* Now, we do the remaining detection. If no `force' parameter is used. */ |
| 397 | |
| 398 | /* First, the generic detection (if any), that is skipped if any force |
| 399 | parameter was used. */ |
| 400 | if (kind < 0) { |
| 401 | /* The below is of course bogus */ |
| 402 | if (foo_read(new_client,FOO_REG_GENERIC) != FOO_GENERIC_VALUE) |
| 403 | goto ERROR1; |
| 404 | } |
| 405 | |
| 406 | /* SENSORS ONLY START */ |
| 407 | |
| 408 | /* Next, specific detection. This is especially important for `sensors' |
| 409 | devices. */ |
| 410 | |
| 411 | /* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter |
| 412 | was used. */ |
| 413 | if (kind <= 0) { |
| 414 | i = foo_read(new_client,FOO_REG_CHIPTYPE); |
| 415 | if (i == FOO_TYPE_1) |
| 416 | kind = chip1; /* As defined in the enum */ |
| 417 | else if (i == FOO_TYPE_2) |
| 418 | kind = chip2; |
| 419 | else { |
| 420 | printk("foo: Ignoring 'force' parameter for unknown chip at " |
| 421 | "adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address); |
| 422 | goto ERROR1; |
| 423 | } |
| 424 | } |
| 425 | |
| 426 | /* Now set the type and chip names */ |
| 427 | if (kind == chip1) { |
| 428 | type_name = "chip1"; /* For /proc entry */ |
| 429 | client_name = "CHIP 1"; |
| 430 | } else if (kind == chip2) { |
| 431 | type_name = "chip2"; /* For /proc entry */ |
| 432 | client_name = "CHIP 2"; |
| 433 | } |
| 434 | |
| 435 | /* Reserve the ISA region */ |
| 436 | if (is_isa) |
| 437 | request_region(address,FOO_EXTENT,type_name); |
| 438 | |
| 439 | /* SENSORS ONLY END */ |
| 440 | |
| 441 | /* Fill in the remaining client fields. */ |
| 442 | strcpy(new_client->name,client_name); |
| 443 | |
| 444 | /* SENSORS ONLY BEGIN */ |
| 445 | data->type = kind; |
| 446 | /* SENSORS ONLY END */ |
| 447 | |
| 448 | data->valid = 0; /* Only if you use this field */ |
| 449 | init_MUTEX(&data->update_lock); /* Only if you use this field */ |
| 450 | |
| 451 | /* Any other initializations in data must be done here too. */ |
| 452 | |
| 453 | /* Tell the i2c layer a new client has arrived */ |
| 454 | if ((err = i2c_attach_client(new_client))) |
| 455 | goto ERROR3; |
| 456 | |
| 457 | /* SENSORS ONLY BEGIN */ |
| 458 | /* Register a new directory entry with module sensors. See below for |
| 459 | the `template' structure. */ |
| 460 | if ((i = i2c_register_entry(new_client, type_name, |
| 461 | foo_dir_table_template,THIS_MODULE)) < 0) { |
| 462 | err = i; |
| 463 | goto ERROR4; |
| 464 | } |
| 465 | data->sysctl_id = i; |
| 466 | |
| 467 | /* SENSORS ONLY END */ |
| 468 | |
| 469 | /* This function can write default values to the client registers, if |
| 470 | needed. */ |
| 471 | foo_init_client(new_client); |
| 472 | return 0; |
| 473 | |
| 474 | /* OK, this is not exactly good programming practice, usually. But it is |
| 475 | very code-efficient in this case. */ |
| 476 | |
| 477 | ERROR4: |
| 478 | i2c_detach_client(new_client); |
| 479 | ERROR3: |
| 480 | ERROR2: |
| 481 | /* SENSORS ONLY START */ |
| 482 | if (is_isa) |
| 483 | release_region(address,FOO_EXTENT); |
| 484 | /* SENSORS ONLY END */ |
| 485 | ERROR1: |
Jean Delvare | a852daa | 2005-11-02 21:42:48 +0100 | [diff] [blame] | 486 | kfree(data); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 487 | ERROR0: |
| 488 | return err; |
| 489 | } |
| 490 | |
| 491 | |
David Brownell | 4298cfc | 2007-05-01 23:26:31 +0200 | [diff] [blame^] | 492 | Removing the client (Legacy model) |
| 493 | ================================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 494 | |
| 495 | The detach_client call back function is called when a client should be |
| 496 | removed. It may actually fail, but only when panicking. This code is |
| 497 | much simpler than the attachment code, fortunately! |
| 498 | |
| 499 | int foo_detach_client(struct i2c_client *client) |
| 500 | { |
| 501 | int err,i; |
| 502 | |
| 503 | /* SENSORS ONLY START */ |
| 504 | /* Deregister with the `i2c-proc' module. */ |
| 505 | i2c_deregister_entry(((struct lm78_data *)(client->data))->sysctl_id); |
| 506 | /* SENSORS ONLY END */ |
| 507 | |
| 508 | /* Try to detach the client from i2c space */ |
Jean Delvare | 7bef559 | 2005-07-27 22:14:49 +0200 | [diff] [blame] | 509 | if ((err = i2c_detach_client(client))) |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 510 | return err; |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 511 | |
Jean Delvare | 02ff982 | 2005-07-20 00:05:33 +0200 | [diff] [blame] | 512 | /* HYBRID SENSORS CHIP ONLY START */ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 513 | if i2c_is_isa_client(client) |
| 514 | release_region(client->addr,LM78_EXTENT); |
Jean Delvare | 02ff982 | 2005-07-20 00:05:33 +0200 | [diff] [blame] | 515 | /* HYBRID SENSORS CHIP ONLY END */ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 516 | |
Jean Delvare | a852daa | 2005-11-02 21:42:48 +0100 | [diff] [blame] | 517 | kfree(i2c_get_clientdata(client)); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 518 | return 0; |
| 519 | } |
| 520 | |
| 521 | |
| 522 | Initializing the module or kernel |
| 523 | ================================= |
| 524 | |
| 525 | When the kernel is booted, or when your foo driver module is inserted, |
| 526 | you have to do some initializing. Fortunately, just attaching (registering) |
| 527 | the driver module is usually enough. |
| 528 | |
| 529 | /* Keep track of how far we got in the initialization process. If several |
| 530 | things have to initialized, and we fail halfway, only those things |
| 531 | have to be cleaned up! */ |
| 532 | static int __initdata foo_initialized = 0; |
| 533 | |
| 534 | static int __init foo_init(void) |
| 535 | { |
| 536 | int res; |
| 537 | printk("foo version %s (%s)\n",FOO_VERSION,FOO_DATE); |
| 538 | |
| 539 | if ((res = i2c_add_driver(&foo_driver))) { |
| 540 | printk("foo: Driver registration failed, module not inserted.\n"); |
| 541 | foo_cleanup(); |
| 542 | return res; |
| 543 | } |
| 544 | foo_initialized ++; |
| 545 | return 0; |
| 546 | } |
| 547 | |
| 548 | void foo_cleanup(void) |
| 549 | { |
| 550 | if (foo_initialized == 1) { |
| 551 | if ((res = i2c_del_driver(&foo_driver))) { |
| 552 | printk("foo: Driver registration failed, module not removed.\n"); |
| 553 | return; |
| 554 | } |
| 555 | foo_initialized --; |
| 556 | } |
| 557 | } |
| 558 | |
| 559 | /* Substitute your own name and email address */ |
| 560 | MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" |
| 561 | MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); |
| 562 | |
| 563 | module_init(foo_init); |
| 564 | module_exit(foo_cleanup); |
| 565 | |
| 566 | Note that some functions are marked by `__init', and some data structures |
| 567 | by `__init_data'. Hose functions and structures can be removed after |
| 568 | kernel booting (or module loading) is completed. |
| 569 | |
Jean Delvare | fb687d7 | 2005-12-18 16:51:55 +0100 | [diff] [blame] | 570 | |
David Brownell | f37dd80 | 2007-02-13 22:09:00 +0100 | [diff] [blame] | 571 | Power Management |
| 572 | ================ |
| 573 | |
| 574 | If your I2C device needs special handling when entering a system low |
| 575 | power state -- like putting a transceiver into a low power mode, or |
| 576 | activating a system wakeup mechanism -- do that in the suspend() method. |
| 577 | The resume() method should reverse what the suspend() method does. |
| 578 | |
| 579 | These are standard driver model calls, and they work just like they |
| 580 | would for any other driver stack. The calls can sleep, and can use |
| 581 | I2C messaging to the device being suspended or resumed (since their |
| 582 | parent I2C adapter is active when these calls are issued, and IRQs |
| 583 | are still enabled). |
| 584 | |
| 585 | |
| 586 | System Shutdown |
| 587 | =============== |
| 588 | |
| 589 | If your I2C device needs special handling when the system shuts down |
| 590 | or reboots (including kexec) -- like turning something off -- use a |
| 591 | shutdown() method. |
| 592 | |
| 593 | Again, this is a standard driver model call, working just like it |
| 594 | would for any other driver stack: the calls can sleep, and can use |
| 595 | I2C messaging. |
| 596 | |
| 597 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 598 | Command function |
| 599 | ================ |
| 600 | |
| 601 | A generic ioctl-like function call back is supported. You will seldom |
Jean Delvare | fb687d7 | 2005-12-18 16:51:55 +0100 | [diff] [blame] | 602 | need this, and its use is deprecated anyway, so newer design should not |
| 603 | use it. Set it to NULL. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 604 | |
| 605 | |
| 606 | Sending and receiving |
| 607 | ===================== |
| 608 | |
| 609 | If you want to communicate with your device, there are several functions |
| 610 | to do this. You can find all of them in i2c.h. |
| 611 | |
| 612 | If you can choose between plain i2c communication and SMBus level |
| 613 | communication, please use the last. All adapters understand SMBus level |
| 614 | commands, but only some of them understand plain i2c! |
| 615 | |
| 616 | |
| 617 | Plain i2c communication |
| 618 | ----------------------- |
| 619 | |
| 620 | extern int i2c_master_send(struct i2c_client *,const char* ,int); |
| 621 | extern int i2c_master_recv(struct i2c_client *,char* ,int); |
| 622 | |
| 623 | These routines read and write some bytes from/to a client. The client |
| 624 | contains the i2c address, so you do not have to include it. The second |
| 625 | parameter contains the bytes the read/write, the third the length of the |
| 626 | buffer. Returned is the actual number of bytes read/written. |
| 627 | |
| 628 | extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, |
| 629 | int num); |
| 630 | |
| 631 | This sends a series of messages. Each message can be a read or write, |
| 632 | and they can be mixed in any way. The transactions are combined: no |
| 633 | stop bit is sent between transaction. The i2c_msg structure contains |
| 634 | for each message the client address, the number of bytes of the message |
| 635 | and the message data itself. |
| 636 | |
| 637 | You can read the file `i2c-protocol' for more information about the |
| 638 | actual i2c protocol. |
| 639 | |
| 640 | |
| 641 | SMBus communication |
| 642 | ------------------- |
| 643 | |
| 644 | extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr, |
| 645 | unsigned short flags, |
| 646 | char read_write, u8 command, int size, |
| 647 | union i2c_smbus_data * data); |
| 648 | |
| 649 | This is the generic SMBus function. All functions below are implemented |
| 650 | in terms of it. Never use this function directly! |
| 651 | |
| 652 | |
| 653 | extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value); |
| 654 | extern s32 i2c_smbus_read_byte(struct i2c_client * client); |
| 655 | extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value); |
| 656 | extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command); |
| 657 | extern s32 i2c_smbus_write_byte_data(struct i2c_client * client, |
| 658 | u8 command, u8 value); |
| 659 | extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command); |
| 660 | extern s32 i2c_smbus_write_word_data(struct i2c_client * client, |
| 661 | u8 command, u16 value); |
| 662 | extern s32 i2c_smbus_write_block_data(struct i2c_client * client, |
| 663 | u8 command, u8 length, |
| 664 | u8 *values); |
Jean Delvare | 7865e24 | 2005-10-08 00:00:31 +0200 | [diff] [blame] | 665 | extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, |
| 666 | u8 command, u8 *values); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 667 | |
| 668 | These ones were removed in Linux 2.6.10 because they had no users, but could |
| 669 | be added back later if needed: |
| 670 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 671 | extern s32 i2c_smbus_read_block_data(struct i2c_client * client, |
| 672 | u8 command, u8 *values); |
| 673 | extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client, |
| 674 | u8 command, u8 length, |
| 675 | u8 *values); |
| 676 | extern s32 i2c_smbus_process_call(struct i2c_client * client, |
| 677 | u8 command, u16 value); |
| 678 | extern s32 i2c_smbus_block_process_call(struct i2c_client *client, |
| 679 | u8 command, u8 length, |
| 680 | u8 *values) |
| 681 | |
| 682 | All these transactions return -1 on failure. The 'write' transactions |
| 683 | return 0 on success; the 'read' transactions return the read value, except |
| 684 | for read_block, which returns the number of values read. The block buffers |
| 685 | need not be longer than 32 bytes. |
| 686 | |
| 687 | You can read the file `smbus-protocol' for more information about the |
| 688 | actual SMBus protocol. |
| 689 | |
| 690 | |
| 691 | General purpose routines |
| 692 | ======================== |
| 693 | |
| 694 | Below all general purpose routines are listed, that were not mentioned |
| 695 | before. |
| 696 | |
| 697 | /* This call returns a unique low identifier for each registered adapter, |
| 698 | * or -1 if the adapter was not registered. |
| 699 | */ |
| 700 | extern int i2c_adapter_id(struct i2c_adapter *adap); |
| 701 | |
| 702 | |
| 703 | The sensors sysctl/proc interface |
| 704 | ================================= |
| 705 | |
| 706 | This section only applies if you write `sensors' drivers. |
| 707 | |
| 708 | Each sensors driver creates a directory in /proc/sys/dev/sensors for each |
| 709 | registered client. The directory is called something like foo-i2c-4-65. |
| 710 | The sensors module helps you to do this as easily as possible. |
| 711 | |
| 712 | The template |
| 713 | ------------ |
| 714 | |
| 715 | You will need to define a ctl_table template. This template will automatically |
| 716 | be copied to a newly allocated structure and filled in where necessary when |
| 717 | you call sensors_register_entry. |
| 718 | |
| 719 | First, I will give an example definition. |
| 720 | static ctl_table foo_dir_table_template[] = { |
| 721 | { FOO_SYSCTL_FUNC1, "func1", NULL, 0, 0644, NULL, &i2c_proc_real, |
| 722 | &i2c_sysctl_real,NULL,&foo_func }, |
| 723 | { FOO_SYSCTL_FUNC2, "func2", NULL, 0, 0644, NULL, &i2c_proc_real, |
| 724 | &i2c_sysctl_real,NULL,&foo_func }, |
| 725 | { FOO_SYSCTL_DATA, "data", NULL, 0, 0644, NULL, &i2c_proc_real, |
| 726 | &i2c_sysctl_real,NULL,&foo_data }, |
| 727 | { 0 } |
| 728 | }; |
| 729 | |
| 730 | In the above example, three entries are defined. They can either be |
| 731 | accessed through the /proc interface, in the /proc/sys/dev/sensors/* |
| 732 | directories, as files named func1, func2 and data, or alternatively |
| 733 | through the sysctl interface, in the appropriate table, with identifiers |
| 734 | FOO_SYSCTL_FUNC1, FOO_SYSCTL_FUNC2 and FOO_SYSCTL_DATA. |
| 735 | |
| 736 | The third, sixth and ninth parameters should always be NULL, and the |
| 737 | fourth should always be 0. The fifth is the mode of the /proc file; |
| 738 | 0644 is safe, as the file will be owned by root:root. |
| 739 | |
| 740 | The seventh and eighth parameters should be &i2c_proc_real and |
| 741 | &i2c_sysctl_real if you want to export lists of reals (scaled |
| 742 | integers). You can also use your own function for them, as usual. |
| 743 | Finally, the last parameter is the call-back to gather the data |
| 744 | (see below) if you use the *_proc_real functions. |
| 745 | |
| 746 | |
| 747 | Gathering the data |
| 748 | ------------------ |
| 749 | |
| 750 | The call back functions (foo_func and foo_data in the above example) |
| 751 | can be called in several ways; the operation parameter determines |
| 752 | what should be done: |
| 753 | |
| 754 | * If operation == SENSORS_PROC_REAL_INFO, you must return the |
| 755 | magnitude (scaling) in nrels_mag; |
| 756 | * If operation == SENSORS_PROC_REAL_READ, you must read information |
| 757 | from the chip and return it in results. The number of integers |
| 758 | to display should be put in nrels_mag; |
| 759 | * If operation == SENSORS_PROC_REAL_WRITE, you must write the |
| 760 | supplied information to the chip. nrels_mag will contain the number |
| 761 | of integers, results the integers themselves. |
| 762 | |
| 763 | The *_proc_real functions will display the elements as reals for the |
| 764 | /proc interface. If you set the magnitude to 2, and supply 345 for |
| 765 | SENSORS_PROC_REAL_READ, it would display 3.45; and if the user would |
| 766 | write 45.6 to the /proc file, it would be returned as 4560 for |
| 767 | SENSORS_PROC_REAL_WRITE. A magnitude may even be negative! |
| 768 | |
| 769 | An example function: |
| 770 | |
| 771 | /* FOO_FROM_REG and FOO_TO_REG translate between scaled values and |
| 772 | register values. Note the use of the read cache. */ |
| 773 | void foo_in(struct i2c_client *client, int operation, int ctl_name, |
| 774 | int *nrels_mag, long *results) |
| 775 | { |
| 776 | struct foo_data *data = client->data; |
| 777 | int nr = ctl_name - FOO_SYSCTL_FUNC1; /* reduce to 0 upwards */ |
| 778 | |
| 779 | if (operation == SENSORS_PROC_REAL_INFO) |
| 780 | *nrels_mag = 2; |
| 781 | else if (operation == SENSORS_PROC_REAL_READ) { |
| 782 | /* Update the readings cache (if necessary) */ |
| 783 | foo_update_client(client); |
| 784 | /* Get the readings from the cache */ |
| 785 | results[0] = FOO_FROM_REG(data->foo_func_base[nr]); |
| 786 | results[1] = FOO_FROM_REG(data->foo_func_more[nr]); |
| 787 | results[2] = FOO_FROM_REG(data->foo_func_readonly[nr]); |
| 788 | *nrels_mag = 2; |
| 789 | } else if (operation == SENSORS_PROC_REAL_WRITE) { |
| 790 | if (*nrels_mag >= 1) { |
| 791 | /* Update the cache */ |
| 792 | data->foo_base[nr] = FOO_TO_REG(results[0]); |
| 793 | /* Update the chip */ |
| 794 | foo_write_value(client,FOO_REG_FUNC_BASE(nr),data->foo_base[nr]); |
| 795 | } |
| 796 | if (*nrels_mag >= 2) { |
| 797 | /* Update the cache */ |
| 798 | data->foo_more[nr] = FOO_TO_REG(results[1]); |
| 799 | /* Update the chip */ |
| 800 | foo_write_value(client,FOO_REG_FUNC_MORE(nr),data->foo_more[nr]); |
| 801 | } |
| 802 | } |
| 803 | } |