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