1 This is a small guide for those who want to write kernel drivers for I2C
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!
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.
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
27 static struct i2c_driver foo_driver = {
29 .name = "Foo version 2.3 driver",
30 .flags = I2C_DF_NOTIFY,
31 .attach_adapter = &foo_attach_adapter,
32 .detach_client = &foo_detach_client,
33 .command = &foo_command /* may be NULL */
36 The name field must match the driver name, including the case. It must not
37 contain spaces, and may be up to 31 characters long.
39 Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This
40 means that your driver will be notified when new adapters are found.
41 This is almost always what you want.
43 All other fields are for call-back functions which will be explained
50 The client structure has a special `data' field that can point to any
51 structure at all. You can use this to keep client-specific data. You
52 do not always need this, but especially for `sensors' drivers, it can
55 An example structure is below.
58 struct semaphore lock; /* For ISA access in `sensors' drivers. */
59 int sysctl_id; /* To keep the /proc directory entry for
61 enum chips type; /* To keep the chips type for `sensors' drivers. */
63 /* Because the i2c bus is slow, it is often useful to cache the read
64 information of a chip for some time (for example, 1 or 2 seconds).
65 It depends of course on the device whether this is really worthwhile
67 struct semaphore update_lock; /* When we are reading lots of information,
68 another process should not update the
70 char valid; /* != 0 if the following fields are valid. */
71 unsigned long last_updated; /* In jiffies */
72 /* Add the read information here too */
79 Let's say we have a valid client structure. At some time, we will need
80 to gather information from the client, or write new information to the
81 client. How we will export this information to user-space is less
82 important at this moment (perhaps we do not need to do this at all for
83 some obscure clients). But we need generic reading and writing routines.
85 I have found it useful to define foo_read and foo_write function for this.
86 For some cases, it will be easier to call the i2c functions directly,
87 but many chips have some kind of register-value idea that can easily
88 be encapsulated. Also, some chips have both ISA and I2C interfaces, and
89 it useful to abstract from this (only for `sensors' drivers).
91 The below functions are simple examples, and should not be copied
94 int foo_read_value(struct i2c_client *client, u8 reg)
96 if (reg < 0x10) /* byte-sized register */
97 return i2c_smbus_read_byte_data(client,reg);
98 else /* word-sized register */
99 return i2c_smbus_read_word_data(client,reg);
102 int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
104 if (reg == 0x10) /* Impossible to write - driver error! */ {
106 else if (reg < 0x10) /* byte-sized register */
107 return i2c_smbus_write_byte_data(client,reg,value);
108 else /* word-sized register */
109 return i2c_smbus_write_word_data(client,reg,value);
112 For sensors code, you may have to cope with ISA registers too. Something
113 like the below often works. Note the locking!
115 int foo_read_value(struct i2c_client *client, u8 reg)
118 if (i2c_is_isa_client(client)) {
119 down(&(((struct foo_data *) (client->data)) -> lock));
120 outb_p(reg,client->addr + FOO_ADDR_REG_OFFSET);
121 res = inb_p(client->addr + FOO_DATA_REG_OFFSET);
122 up(&(((struct foo_data *) (client->data)) -> lock));
125 return i2c_smbus_read_byte_data(client,reg);
128 Writing is done the same way.
131 Probing and attaching
132 =====================
134 Most i2c devices can be present on several i2c addresses; for some this
135 is determined in hardware (by soldering some chip pins to Vcc or Ground),
136 for others this can be changed in software (by writing to specific client
137 registers). Some devices are usually on a specific address, but not always;
138 and some are even more tricky. So you will probably need to scan several
139 i2c addresses for your clients, and do some sort of detection to see
140 whether it is actually a device supported by your driver.
142 To give the user a maximum of possibilities, some default module parameters
143 are defined to help determine what addresses are scanned. Several macros
144 are defined in i2c.h to help you support them, as well as a generic
147 You do not have to use this parameter interface; but don't try to use
148 function i2c_probe() if you don't.
150 NOTE: If you want to write a `sensors' driver, the interface is slightly
151 different! See below.
158 All parameters are given as lists of unsigned 16-bit integers. Lists are
159 terminated by I2C_CLIENT_END.
160 The following lists are used internally:
162 normal_i2c: filled in by the module writer.
163 A list of I2C addresses which should normally be examined.
164 probe: insmod parameter.
165 A list of pairs. The first value is a bus number (-1 for any I2C bus),
166 the second is the address. These addresses are also probed, as if they
167 were in the 'normal' list.
168 ignore: insmod parameter.
169 A list of pairs. The first value is a bus number (-1 for any I2C bus),
170 the second is the I2C address. These addresses are never probed.
171 This parameter overrules the 'normal_i2c' list only.
172 force: insmod parameter.
173 A list of pairs. The first value is a bus number (-1 for any I2C bus),
174 the second is the I2C address. A device is blindly assumed to be on
175 the given address, no probing is done.
177 Additionally, kind-specific force lists may optionally be defined if
178 the driver supports several chip kinds. They are grouped in a
179 NULL-terminated list of pointers named forces, those first element if the
180 generic force list mentioned above. Each additional list correspond to an
181 insmod parameter of the form force_<kind>.
183 Fortunately, as a module writer, you just have to define the `normal_i2c'
184 parameter. The complete declaration could look like this:
186 /* Scan 0x37, and 0x48 to 0x4f */
187 static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c,
188 0x4d, 0x4e, 0x4f, I2C_CLIENT_END };
190 /* Magic definition of all other variables and things */
192 /* Or, if your driver supports, say, 2 kind of devices: */
193 I2C_CLIENT_INSMOD_2(foo, bar);
195 If you use the multi-kind form, an enum will be defined for you:
196 enum chips { any_chip, foo, bar, ... }
197 You can then (and certainly should) use it in the driver code.
199 Note that you *have* to call the defined variable `normal_i2c',
203 Attaching to an adapter
204 -----------------------
206 Whenever a new adapter is inserted, or for all adapters if the driver is
207 being registered, the callback attach_adapter() is called. Now is the
208 time to determine what devices are present on the adapter, and to register
209 a client for each of them.
211 The attach_adapter callback is really easy: we just call the generic
212 detection function. This function will scan the bus for us, using the
213 information as defined in the lists explained above. If a device is
214 detected at a specific address, another callback is called.
216 int foo_attach_adapter(struct i2c_adapter *adapter)
218 return i2c_probe(adapter,&addr_data,&foo_detect_client);
221 Remember, structure `addr_data' is defined by the macros explained above,
222 so you do not have to define it yourself.
224 The i2c_probe function will call the foo_detect_client
225 function only for those i2c addresses that actually have a device on
226 them (unless a `force' parameter was used). In addition, addresses that
227 are already in use (by some other registered client) are skipped.
230 The detect client function
231 --------------------------
233 The detect client function is called by i2c_probe. The `kind' parameter
234 contains -1 for a probed detection, 0 for a forced detection, or a positive
235 number for a forced detection with a chip type forced.
237 Below, some things are only needed if this is a `sensors' driver. Those
238 parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */
241 Returning an error different from -ENODEV in a detect function will cause
242 the detection to stop: other addresses and adapters won't be scanned.
243 This should only be done on fatal or internal errors, such as a memory
244 shortage or i2c_attach_client failing.
246 For now, you can ignore the `flags' parameter. It is there for future use.
248 int foo_detect_client(struct i2c_adapter *adapter, int address,
249 unsigned short flags, int kind)
253 struct i2c_client *new_client;
254 struct foo_data *data;
255 const char *client_name = ""; /* For non-`sensors' drivers, put the real
258 /* Let's see whether this adapter can support what we need.
259 Please substitute the things you need here!
260 For `sensors' drivers, add `! is_isa &&' to the if statement */
261 if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
262 I2C_FUNC_SMBUS_WRITE_BYTE))
265 /* SENSORS ONLY START */
266 const char *type_name = "";
267 int is_isa = i2c_is_isa_adapter(adapter);
269 /* Do this only if the chip can additionally be found on the ISA bus
274 /* Discard immediately if this ISA range is already used */
275 if (check_region(address,FOO_EXTENT))
278 /* Probe whether there is anything on this address.
279 Some example code is below, but you will have to adapt this
280 for your own driver */
282 if (kind < 0) /* Only if no force parameter was used */ {
283 /* We may need long timeouts at least for some chips. */
284 #define REALLY_SLOW_IO
285 i = inb_p(address + 1);
286 if (inb_p(address + 2) != i)
288 if (inb_p(address + 3) != i)
290 if (inb_p(address + 7) != i)
292 #undef REALLY_SLOW_IO
294 /* Let's just hope nothing breaks here */
295 i = inb_p(address + 5) & 0x7f;
296 outb_p(~i & 0x7f,address+5);
297 if ((inb_p(address + 5) & 0x7f) != (~i & 0x7f)) {
304 /* SENSORS ONLY END */
306 /* OK. For now, we presume we have a valid client. We now create the
307 client structure, even though we cannot fill it completely yet.
308 But it allows us to access several i2c functions safely */
310 /* Note that we reserve some space for foo_data too. If you don't
311 need it, remove it. We do it here to help to lessen memory
313 if (! (new_client = kmalloc(sizeof(struct i2c_client) +
314 sizeof(struct foo_data),
320 /* This is tricky, but it will set the data to the right value. */
321 client->data = new_client + 1;
322 data = (struct foo_data *) (client->data);
324 new_client->addr = address;
325 new_client->data = data;
326 new_client->adapter = adapter;
327 new_client->driver = &foo_driver;
328 new_client->flags = 0;
330 /* Now, we do the remaining detection. If no `force' parameter is used. */
332 /* First, the generic detection (if any), that is skipped if any force
333 parameter was used. */
335 /* The below is of course bogus */
336 if (foo_read(new_client,FOO_REG_GENERIC) != FOO_GENERIC_VALUE)
340 /* SENSORS ONLY START */
342 /* Next, specific detection. This is especially important for `sensors'
345 /* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter
348 i = foo_read(new_client,FOO_REG_CHIPTYPE);
350 kind = chip1; /* As defined in the enum */
351 else if (i == FOO_TYPE_2)
354 printk("foo: Ignoring 'force' parameter for unknown chip at "
355 "adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address);
360 /* Now set the type and chip names */
362 type_name = "chip1"; /* For /proc entry */
363 client_name = "CHIP 1";
364 } else if (kind == chip2) {
365 type_name = "chip2"; /* For /proc entry */
366 client_name = "CHIP 2";
369 /* Reserve the ISA region */
371 request_region(address,FOO_EXTENT,type_name);
373 /* SENSORS ONLY END */
375 /* Fill in the remaining client fields. */
376 strcpy(new_client->name,client_name);
378 /* SENSORS ONLY BEGIN */
380 /* SENSORS ONLY END */
382 data->valid = 0; /* Only if you use this field */
383 init_MUTEX(&data->update_lock); /* Only if you use this field */
385 /* Any other initializations in data must be done here too. */
387 /* Tell the i2c layer a new client has arrived */
388 if ((err = i2c_attach_client(new_client)))
391 /* SENSORS ONLY BEGIN */
392 /* Register a new directory entry with module sensors. See below for
393 the `template' structure. */
394 if ((i = i2c_register_entry(new_client, type_name,
395 foo_dir_table_template,THIS_MODULE)) < 0) {
401 /* SENSORS ONLY END */
403 /* This function can write default values to the client registers, if
405 foo_init_client(new_client);
408 /* OK, this is not exactly good programming practice, usually. But it is
409 very code-efficient in this case. */
412 i2c_detach_client(new_client);
415 /* SENSORS ONLY START */
417 release_region(address,FOO_EXTENT);
418 /* SENSORS ONLY END */
429 The detach_client call back function is called when a client should be
430 removed. It may actually fail, but only when panicking. This code is
431 much simpler than the attachment code, fortunately!
433 int foo_detach_client(struct i2c_client *client)
437 /* SENSORS ONLY START */
438 /* Deregister with the `i2c-proc' module. */
439 i2c_deregister_entry(((struct lm78_data *)(client->data))->sysctl_id);
440 /* SENSORS ONLY END */
442 /* Try to detach the client from i2c space */
443 if ((err = i2c_detach_client(client)))
446 /* HYBRID SENSORS CHIP ONLY START */
447 if i2c_is_isa_client(client)
448 release_region(client->addr,LM78_EXTENT);
449 /* HYBRID SENSORS CHIP ONLY END */
451 kfree(client); /* Frees client data too, if allocated at the same time */
456 Initializing the module or kernel
457 =================================
459 When the kernel is booted, or when your foo driver module is inserted,
460 you have to do some initializing. Fortunately, just attaching (registering)
461 the driver module is usually enough.
463 /* Keep track of how far we got in the initialization process. If several
464 things have to initialized, and we fail halfway, only those things
465 have to be cleaned up! */
466 static int __initdata foo_initialized = 0;
468 static int __init foo_init(void)
471 printk("foo version %s (%s)\n",FOO_VERSION,FOO_DATE);
473 if ((res = i2c_add_driver(&foo_driver))) {
474 printk("foo: Driver registration failed, module not inserted.\n");
482 void foo_cleanup(void)
484 if (foo_initialized == 1) {
485 if ((res = i2c_del_driver(&foo_driver))) {
486 printk("foo: Driver registration failed, module not removed.\n");
493 /* Substitute your own name and email address */
494 MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
495 MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
497 module_init(foo_init);
498 module_exit(foo_cleanup);
500 Note that some functions are marked by `__init', and some data structures
501 by `__init_data'. Hose functions and structures can be removed after
502 kernel booting (or module loading) is completed.
507 A generic ioctl-like function call back is supported. You will seldom
508 need this. You may even set it to NULL.
510 /* No commands defined */
511 int foo_command(struct i2c_client *client, unsigned int cmd, void *arg)
517 Sending and receiving
518 =====================
520 If you want to communicate with your device, there are several functions
521 to do this. You can find all of them in i2c.h.
523 If you can choose between plain i2c communication and SMBus level
524 communication, please use the last. All adapters understand SMBus level
525 commands, but only some of them understand plain i2c!
528 Plain i2c communication
529 -----------------------
531 extern int i2c_master_send(struct i2c_client *,const char* ,int);
532 extern int i2c_master_recv(struct i2c_client *,char* ,int);
534 These routines read and write some bytes from/to a client. The client
535 contains the i2c address, so you do not have to include it. The second
536 parameter contains the bytes the read/write, the third the length of the
537 buffer. Returned is the actual number of bytes read/written.
539 extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
542 This sends a series of messages. Each message can be a read or write,
543 and they can be mixed in any way. The transactions are combined: no
544 stop bit is sent between transaction. The i2c_msg structure contains
545 for each message the client address, the number of bytes of the message
546 and the message data itself.
548 You can read the file `i2c-protocol' for more information about the
555 extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr,
556 unsigned short flags,
557 char read_write, u8 command, int size,
558 union i2c_smbus_data * data);
560 This is the generic SMBus function. All functions below are implemented
561 in terms of it. Never use this function directly!
564 extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);
565 extern s32 i2c_smbus_read_byte(struct i2c_client * client);
566 extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value);
567 extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command);
568 extern s32 i2c_smbus_write_byte_data(struct i2c_client * client,
569 u8 command, u8 value);
570 extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command);
571 extern s32 i2c_smbus_write_word_data(struct i2c_client * client,
572 u8 command, u16 value);
573 extern s32 i2c_smbus_write_block_data(struct i2c_client * client,
574 u8 command, u8 length,
576 extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client,
577 u8 command, u8 *values);
579 These ones were removed in Linux 2.6.10 because they had no users, but could
580 be added back later if needed:
582 extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
583 u8 command, u8 *values);
584 extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client,
585 u8 command, u8 length,
587 extern s32 i2c_smbus_process_call(struct i2c_client * client,
588 u8 command, u16 value);
589 extern s32 i2c_smbus_block_process_call(struct i2c_client *client,
590 u8 command, u8 length,
593 All these transactions return -1 on failure. The 'write' transactions
594 return 0 on success; the 'read' transactions return the read value, except
595 for read_block, which returns the number of values read. The block buffers
596 need not be longer than 32 bytes.
598 You can read the file `smbus-protocol' for more information about the
599 actual SMBus protocol.
602 General purpose routines
603 ========================
605 Below all general purpose routines are listed, that were not mentioned
608 /* This call returns a unique low identifier for each registered adapter,
609 * or -1 if the adapter was not registered.
611 extern int i2c_adapter_id(struct i2c_adapter *adap);
614 The sensors sysctl/proc interface
615 =================================
617 This section only applies if you write `sensors' drivers.
619 Each sensors driver creates a directory in /proc/sys/dev/sensors for each
620 registered client. The directory is called something like foo-i2c-4-65.
621 The sensors module helps you to do this as easily as possible.
626 You will need to define a ctl_table template. This template will automatically
627 be copied to a newly allocated structure and filled in where necessary when
628 you call sensors_register_entry.
630 First, I will give an example definition.
631 static ctl_table foo_dir_table_template[] = {
632 { FOO_SYSCTL_FUNC1, "func1", NULL, 0, 0644, NULL, &i2c_proc_real,
633 &i2c_sysctl_real,NULL,&foo_func },
634 { FOO_SYSCTL_FUNC2, "func2", NULL, 0, 0644, NULL, &i2c_proc_real,
635 &i2c_sysctl_real,NULL,&foo_func },
636 { FOO_SYSCTL_DATA, "data", NULL, 0, 0644, NULL, &i2c_proc_real,
637 &i2c_sysctl_real,NULL,&foo_data },
641 In the above example, three entries are defined. They can either be
642 accessed through the /proc interface, in the /proc/sys/dev/sensors/*
643 directories, as files named func1, func2 and data, or alternatively
644 through the sysctl interface, in the appropriate table, with identifiers
645 FOO_SYSCTL_FUNC1, FOO_SYSCTL_FUNC2 and FOO_SYSCTL_DATA.
647 The third, sixth and ninth parameters should always be NULL, and the
648 fourth should always be 0. The fifth is the mode of the /proc file;
649 0644 is safe, as the file will be owned by root:root.
651 The seventh and eighth parameters should be &i2c_proc_real and
652 &i2c_sysctl_real if you want to export lists of reals (scaled
653 integers). You can also use your own function for them, as usual.
654 Finally, the last parameter is the call-back to gather the data
655 (see below) if you use the *_proc_real functions.
661 The call back functions (foo_func and foo_data in the above example)
662 can be called in several ways; the operation parameter determines
665 * If operation == SENSORS_PROC_REAL_INFO, you must return the
666 magnitude (scaling) in nrels_mag;
667 * If operation == SENSORS_PROC_REAL_READ, you must read information
668 from the chip and return it in results. The number of integers
669 to display should be put in nrels_mag;
670 * If operation == SENSORS_PROC_REAL_WRITE, you must write the
671 supplied information to the chip. nrels_mag will contain the number
672 of integers, results the integers themselves.
674 The *_proc_real functions will display the elements as reals for the
675 /proc interface. If you set the magnitude to 2, and supply 345 for
676 SENSORS_PROC_REAL_READ, it would display 3.45; and if the user would
677 write 45.6 to the /proc file, it would be returned as 4560 for
678 SENSORS_PROC_REAL_WRITE. A magnitude may even be negative!
682 /* FOO_FROM_REG and FOO_TO_REG translate between scaled values and
683 register values. Note the use of the read cache. */
684 void foo_in(struct i2c_client *client, int operation, int ctl_name,
685 int *nrels_mag, long *results)
687 struct foo_data *data = client->data;
688 int nr = ctl_name - FOO_SYSCTL_FUNC1; /* reduce to 0 upwards */
690 if (operation == SENSORS_PROC_REAL_INFO)
692 else if (operation == SENSORS_PROC_REAL_READ) {
693 /* Update the readings cache (if necessary) */
694 foo_update_client(client);
695 /* Get the readings from the cache */
696 results[0] = FOO_FROM_REG(data->foo_func_base[nr]);
697 results[1] = FOO_FROM_REG(data->foo_func_more[nr]);
698 results[2] = FOO_FROM_REG(data->foo_func_readonly[nr]);
700 } else if (operation == SENSORS_PROC_REAL_WRITE) {
701 if (*nrels_mag >= 1) {
702 /* Update the cache */
703 data->foo_base[nr] = FOO_TO_REG(results[0]);
704 /* Update the chip */
705 foo_write_value(client,FOO_REG_FUNC_BASE(nr),data->foo_base[nr]);
707 if (*nrels_mag >= 2) {
708 /* Update the cache */
709 data->foo_more[nr] = FOO_TO_REG(results[1]);
710 /* Update the chip */
711 foo_write_value(client,FOO_REG_FUNC_MORE(nr),data->foo_more[nr]);