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