Commit | Line | Data |
---|---|---|
1da177e4 | 1 | This is a small guide for those who want to write kernel drivers for I2C |
4298cfc3 | 2 | or SMBus devices, using Linux as the protocol host/master (not slave). |
1da177e4 LT |
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 | |
f37dd80a DB |
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. | |
1da177e4 LT |
27 | |
28 | static struct i2c_driver foo_driver = { | |
d45d204f | 29 | .driver = { |
d45d204f JD |
30 | .name = "foo", |
31 | }, | |
4298cfc3 DB |
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: */ | |
f37dd80a DB |
38 | .attach_adapter = foo_attach_adapter, |
39 | .detach_client = foo_detach_client, | |
4298cfc3 DB |
40 | |
41 | /* these may be used regardless of the driver binding model */ | |
f37dd80a DB |
42 | .shutdown = foo_shutdown, /* optional */ |
43 | .suspend = foo_suspend, /* optional */ | |
44 | .resume = foo_resume, /* optional */ | |
45 | .command = foo_command, /* optional */ | |
1da177e4 LT |
46 | } |
47 | ||
f37dd80a DB |
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 | |
4298cfc3 DB |
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). | |
1da177e4 | 53 | |
1da177e4 LT |
54 | All other fields are for call-back functions which will be explained |
55 | below. | |
56 | ||
1da177e4 LT |
57 | |
58 | Extra client data | |
59 | ================= | |
60 | ||
f37dd80a DB |
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 | |
1da177e4 LT |
64 | do not always need this, but especially for `sensors' drivers, it can |
65 | be very useful. | |
66 | ||
f37dd80a DB |
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 | ||
1da177e4 LT |
73 | An example structure is below. |
74 | ||
75 | struct foo_data { | |
2445eb62 | 76 | struct i2c_client client; |
1da177e4 LT |
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 | ||
4298cfc3 DB |
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 | ||
1da177e4 LT |
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 | |
2ed2dc3c | 220 | function i2c_probe() if you don't. |
1da177e4 LT |
221 | |
222 | NOTE: If you want to write a `sensors' driver, the interface is slightly | |
223 | different! See below. | |
224 | ||
225 | ||
226 | ||
4298cfc3 DB |
227 | Probing classes (Legacy model) |
228 | ------------------------------ | |
1da177e4 LT |
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. | |
1da177e4 LT |
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. | |
1da177e4 LT |
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. | |
f4b50261 | 243 | This parameter overrules the 'normal_i2c' list only. |
1da177e4 LT |
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 | ||
f4b50261 JD |
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 | ||
b3d5496e JD |
255 | Fortunately, as a module writer, you just have to define the `normal_i2c' |
256 | parameter. The complete declaration could look like this: | |
1da177e4 | 257 | |
b3d5496e JD |
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 }; | |
1da177e4 LT |
261 | |
262 | /* Magic definition of all other variables and things */ | |
263 | I2C_CLIENT_INSMOD; | |
f4b50261 JD |
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. | |
1da177e4 | 270 | |
b3d5496e JD |
271 | Note that you *have* to call the defined variable `normal_i2c', |
272 | without any prefix! | |
1da177e4 LT |
273 | |
274 | ||
4298cfc3 DB |
275 | Attaching to an adapter (Legacy model) |
276 | -------------------------------------- | |
1da177e4 LT |
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 | ||
1da177e4 LT |
293 | Remember, structure `addr_data' is defined by the macros explained above, |
294 | so you do not have to define it yourself. | |
295 | ||
2ed2dc3c | 296 | The i2c_probe function will call the foo_detect_client |
1da177e4 LT |
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 | ||
4298cfc3 DB |
302 | The detect client function (Legacy model) |
303 | ----------------------------------------- | |
1da177e4 | 304 | |
2ed2dc3c JD |
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. | |
1da177e4 LT |
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 | ||
a89ba0bc JD |
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. | |
1da177e4 LT |
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 | ||
02ff982c JD |
341 | /* Do this only if the chip can additionally be found on the ISA bus |
342 | (hybrid chip). */ | |
1da177e4 | 343 | |
02ff982c | 344 | if (is_isa) { |
1da177e4 LT |
345 | |
346 | /* Discard immediately if this ISA range is already used */ | |
d61780c0 | 347 | /* FIXME: never use check_region(), only request_region() */ |
1da177e4 LT |
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 | ||
2445eb62 | 383 | if (!(data = kzalloc(sizeof(struct foo_data), GFP_KERNEL))) { |
1da177e4 LT |
384 | err = -ENOMEM; |
385 | goto ERROR0; | |
386 | } | |
387 | ||
2445eb62 JD |
388 | new_client = &data->client; |
389 | i2c_set_clientdata(new_client, data); | |
1da177e4 LT |
390 | |
391 | new_client->addr = address; | |
1da177e4 LT |
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: | |
a852daa0 | 486 | kfree(data); |
1da177e4 LT |
487 | ERROR0: |
488 | return err; | |
489 | } | |
490 | ||
491 | ||
4298cfc3 DB |
492 | Removing the client (Legacy model) |
493 | ================================== | |
1da177e4 LT |
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 */ | |
7bef5594 | 509 | if ((err = i2c_detach_client(client))) |
1da177e4 | 510 | return err; |
1da177e4 | 511 | |
02ff982c | 512 | /* HYBRID SENSORS CHIP ONLY START */ |
1da177e4 LT |
513 | if i2c_is_isa_client(client) |
514 | release_region(client->addr,LM78_EXTENT); | |
02ff982c | 515 | /* HYBRID SENSORS CHIP ONLY END */ |
1da177e4 | 516 | |
a852daa0 | 517 | kfree(i2c_get_clientdata(client)); |
1da177e4 LT |
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 | ||
fb687d73 | 570 | |
f37dd80a DB |
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 | ||
1da177e4 LT |
598 | Command function |
599 | ================ | |
600 | ||
601 | A generic ioctl-like function call back is supported. You will seldom | |
fb687d73 JD |
602 | need this, and its use is deprecated anyway, so newer design should not |
603 | use it. Set it to NULL. | |
1da177e4 LT |
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); | |
7865e249 JD |
665 | extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, |
666 | u8 command, u8 *values); | |
1da177e4 LT |
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 | ||
1da177e4 LT |
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 | } |