blob: 6b9af7d479c21b88b373674cdaa50a5e0dfc18e2 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001This is a small guide for those who want to write kernel drivers for I2C
David Brownell4298cfc2007-05-01 23:26:31 +02002or SMBus devices, using Linux as the protocol host/master (not slave).
Linus Torvalds1da177e2005-04-16 15:20:36 -07003
4To set up a driver, you need to do several things. Some are optional, and
5some things can be done slightly or completely different. Use this as a
6guide, not as a rule book!
7
8
9General remarks
10===============
11
12Try to keep the kernel namespace as clean as possible. The best way to
Jean Delvare0e478582008-10-22 20:21:32 +020013do this is to use a unique prefix for all global symbols. This is
Linus Torvalds1da177e2005-04-16 15:20:36 -070014especially important for exported symbols, but it is a good idea to do
15it for non-exported symbols too. We will use the prefix `foo_' in this
Jean Delvare0e478582008-10-22 20:21:32 +020016tutorial.
Linus Torvalds1da177e2005-04-16 15:20:36 -070017
18
19The driver structure
20====================
21
22Usually, you will implement a single driver structure, and instantiate
Jean Delvare0e478582008-10-22 20:21:32 +020023all clients from it. Remember, a driver structure contains general access
David Brownellf37dd802007-02-13 22:09:00 +010024routines, and should be zero-initialized except for fields with data you
25provide. A client structure holds device-specific information like the
26driver model device node, and its I2C address.
Linus Torvalds1da177e2005-04-16 15:20:36 -070027
Ben Dooks2260e632008-07-01 22:38:18 +020028static struct i2c_device_id foo_idtable[] = {
29 { "foo", my_id_for_foo },
30 { "bar", my_id_for_bar },
31 { }
32};
33
34MODULE_DEVICE_TABLE(i2c, foo_idtable);
35
Linus Torvalds1da177e2005-04-16 15:20:36 -070036static struct i2c_driver foo_driver = {
Jean Delvared45d2042005-11-26 20:55:35 +010037 .driver = {
Jean Delvared45d2042005-11-26 20:55:35 +010038 .name = "foo",
39 },
David Brownell4298cfc2007-05-01 23:26:31 +020040
Ben Dooks2260e632008-07-01 22:38:18 +020041 .id_table = foo_ids,
David Brownell4298cfc2007-05-01 23:26:31 +020042 .probe = foo_probe,
43 .remove = foo_remove,
Jean Delvare4735c982008-07-14 22:38:36 +020044 /* if device autodetection is needed: */
45 .class = I2C_CLASS_SOMETHING,
46 .detect = foo_detect,
47 .address_data = &addr_data,
David Brownell4298cfc2007-05-01 23:26:31 +020048
David Brownellf37dd802007-02-13 22:09:00 +010049 .shutdown = foo_shutdown, /* optional */
50 .suspend = foo_suspend, /* optional */
51 .resume = foo_resume, /* optional */
Jean Delvare0e478582008-10-22 20:21:32 +020052 .command = foo_command, /* optional, deprecated */
Linus Torvalds1da177e2005-04-16 15:20:36 -070053}
Jean Delvare0e478582008-10-22 20:21:32 +020054
David Brownellf37dd802007-02-13 22:09:00 +010055The name field is the driver name, and must not contain spaces. It
56should match the module name (if the driver can be compiled as a module),
57although you can use MODULE_ALIAS (passing "foo" in this example) to add
David Brownell4298cfc2007-05-01 23:26:31 +020058another name for the module. If the driver name doesn't match the module
59name, the module won't be automatically loaded (hotplug/coldplug).
Linus Torvalds1da177e2005-04-16 15:20:36 -070060
Jean Delvare0e478582008-10-22 20:21:32 +020061All other fields are for call-back functions which will be explained
Linus Torvalds1da177e2005-04-16 15:20:36 -070062below.
63
Linus Torvalds1da177e2005-04-16 15:20:36 -070064
65Extra client data
66=================
67
David Brownellf37dd802007-02-13 22:09:00 +010068Each client structure has a special `data' field that can point to any
Jean Delvare0e478582008-10-22 20:21:32 +020069structure at all. You should use this to keep device-specific data.
Linus Torvalds1da177e2005-04-16 15:20:36 -070070
David Brownellf37dd802007-02-13 22:09:00 +010071 /* store the value */
72 void i2c_set_clientdata(struct i2c_client *client, void *data);
73
74 /* retrieve the value */
Jean Delvare7d1d8992008-10-22 20:21:31 +020075 void *i2c_get_clientdata(const struct i2c_client *client);
David Brownellf37dd802007-02-13 22:09:00 +010076
Linus Torvalds1da177e2005-04-16 15:20:36 -070077
78Accessing the client
79====================
80
81Let's say we have a valid client structure. At some time, we will need
82to gather information from the client, or write new information to the
Jean Delvare0e478582008-10-22 20:21:32 +020083client.
Linus Torvalds1da177e2005-04-16 15:20:36 -070084
Jean Delvare0e478582008-10-22 20:21:32 +020085I have found it useful to define foo_read and foo_write functions for this.
Linus Torvalds1da177e2005-04-16 15:20:36 -070086For some cases, it will be easier to call the i2c functions directly,
87but many chips have some kind of register-value idea that can easily
Jean Delvareeefcd752007-05-01 23:26:35 +020088be encapsulated.
Linus Torvalds1da177e2005-04-16 15:20:36 -070089
90The below functions are simple examples, and should not be copied
91literally.
92
Jean Delvare0e478582008-10-22 20:21:32 +020093int foo_read_value(struct i2c_client *client, u8 reg)
94{
95 if (reg < 0x10) /* byte-sized register */
96 return i2c_smbus_read_byte_data(client, reg);
97 else /* word-sized register */
98 return i2c_smbus_read_word_data(client, reg);
99}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700100
Jean Delvare0e478582008-10-22 20:21:32 +0200101int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
102{
103 if (reg == 0x10) /* Impossible to write - driver error! */
104 return -EINVAL;
105 else if (reg < 0x10) /* byte-sized register */
106 return i2c_smbus_write_byte_data(client, reg, value);
107 else /* word-sized register */
108 return i2c_smbus_write_word_data(client, reg, value);
109}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700110
Linus Torvalds1da177e2005-04-16 15:20:36 -0700111
112Probing and attaching
113=====================
114
David Brownell4298cfc2007-05-01 23:26:31 +0200115The Linux I2C stack was originally written to support access to hardware
Jean Delvaree3133532008-10-22 20:21:31 +0200116monitoring chips on PC motherboards, and thus used to embed some assumptions
117that were more appropriate to SMBus (and PCs) than to I2C. One of these
118assumptions was that most adapters and devices drivers support the SMBUS_QUICK
119protocol to probe device presence. Another was that devices and their drivers
David Brownell4298cfc2007-05-01 23:26:31 +0200120can be sufficiently configured using only such probe primitives.
121
122As Linux and its I2C stack became more widely used in embedded systems
123and complex components such as DVB adapters, those assumptions became more
124problematic. Drivers for I2C devices that issue interrupts need more (and
125different) configuration information, as do drivers handling chip variants
126that can't be distinguished by protocol probing, or which need some board
127specific information to operate correctly.
128
129Accordingly, the I2C stack now has two models for associating I2C devices
130with their drivers: the original "legacy" model, and a newer one that's
131fully compatible with the Linux 2.6 driver model. These models do not mix,
132since the "legacy" model requires drivers to create "i2c_client" device
133objects after SMBus style probing, while the Linux driver model expects
134drivers to be given such device objects in their probe() routines.
135
Jean Delvaree3133532008-10-22 20:21:31 +0200136The legacy model is deprecated now and will soon be removed, so we no
137longer document it here.
138
David Brownell4298cfc2007-05-01 23:26:31 +0200139
140Standard Driver Model Binding ("New Style")
141-------------------------------------------
142
143System infrastructure, typically board-specific initialization code or
144boot firmware, reports what I2C devices exist. For example, there may be
145a table, in the kernel or from the boot loader, identifying I2C devices
146and linking them to board-specific configuration information about IRQs
147and other wiring artifacts, chip type, and so on. That could be used to
148create i2c_client objects for each I2C device.
149
150I2C device drivers using this binding model work just like any other
151kind of driver in Linux: they provide a probe() method to bind to
152those devices, and a remove() method to unbind.
153
Jean Delvared2653e92008-04-29 23:11:39 +0200154 static int foo_probe(struct i2c_client *client,
155 const struct i2c_device_id *id);
David Brownell4298cfc2007-05-01 23:26:31 +0200156 static int foo_remove(struct i2c_client *client);
157
158Remember that the i2c_driver does not create those client handles. The
159handle may be used during foo_probe(). If foo_probe() reports success
160(zero not a negative status code) it may save the handle and use it until
161foo_remove() returns. That binding model is used by most Linux drivers.
162
Ben Dooks2260e632008-07-01 22:38:18 +0200163The probe function is called when an entry in the id_table name field
164matches the device's name. It is passed the entry that was matched so
165the driver knows which one in the table matched.
David Brownell4298cfc2007-05-01 23:26:31 +0200166
167
Jean Delvaree3133532008-10-22 20:21:31 +0200168Device Creation
169---------------
Jean Delvarece9e0792007-05-01 23:26:32 +0200170
171If you know for a fact that an I2C device is connected to a given I2C bus,
172you can instantiate that device by simply filling an i2c_board_info
173structure with the device address and driver name, and calling
174i2c_new_device(). This will create the device, then the driver core will
175take care of finding the right driver and will call its probe() method.
176If a driver supports different device types, you can specify the type you
177want using the type field. You can also specify an IRQ and platform data
178if needed.
179
180Sometimes you know that a device is connected to a given I2C bus, but you
181don't know the exact address it uses. This happens on TV adapters for
182example, where the same driver supports dozens of slightly different
183models, and I2C device addresses change from one model to the next. In
184that case, you can use the i2c_new_probed_device() variant, which is
185similar to i2c_new_device(), except that it takes an additional list of
186possible I2C addresses to probe. A device is created for the first
187responsive address in the list. If you expect more than one device to be
188present in the address range, simply call i2c_new_probed_device() that
189many times.
190
191The call to i2c_new_device() or i2c_new_probed_device() typically happens
192in the I2C bus driver. You may want to save the returned i2c_client
193reference for later use.
194
195
Jean Delvaree3133532008-10-22 20:21:31 +0200196Device Detection
197----------------
Jean Delvare4735c982008-07-14 22:38:36 +0200198
199Sometimes you do not know in advance which I2C devices are connected to
200a given I2C bus. This is for example the case of hardware monitoring
201devices on a PC's SMBus. In that case, you may want to let your driver
202detect supported devices automatically. This is how the legacy model
203was working, and is now available as an extension to the standard
204driver model (so that we can finally get rid of the legacy model.)
205
206You simply have to define a detect callback which will attempt to
207identify supported devices (returning 0 for supported ones and -ENODEV
208for unsupported ones), a list of addresses to probe, and a device type
209(or class) so that only I2C buses which may have that type of device
210connected (and not otherwise enumerated) will be probed. The i2c
211core will then call you back as needed and will instantiate a device
212for you for every successful detection.
213
214Note that this mechanism is purely optional and not suitable for all
215devices. You need some reliable way to identify the supported devices
216(typically using device-specific, dedicated identification registers),
217otherwise misdetections are likely to occur and things can get wrong
218quickly.
219
220
Jean Delvaree3133532008-10-22 20:21:31 +0200221Device Deletion
222---------------
Jean Delvarece9e0792007-05-01 23:26:32 +0200223
224Each I2C device which has been created using i2c_new_device() or
225i2c_new_probed_device() can be unregistered by calling
226i2c_unregister_device(). If you don't call it explicitly, it will be
227called automatically before the underlying I2C bus itself is removed, as a
228device can't survive its parent in the device driver model.
229
230
Jean Delvare0e478582008-10-22 20:21:32 +0200231Initializing the driver
232=======================
Linus Torvalds1da177e2005-04-16 15:20:36 -0700233
Jean Delvare0e478582008-10-22 20:21:32 +0200234When the kernel is booted, or when your foo driver module is inserted,
235you have to do some initializing. Fortunately, just registering the
236driver module is usually enough.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700237
Jean Delvare0e478582008-10-22 20:21:32 +0200238static int __init foo_init(void)
239{
240 return i2c_add_driver(&foo_driver);
241}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700242
Jean Delvare0e478582008-10-22 20:21:32 +0200243static void __exit foo_cleanup(void)
244{
245 i2c_del_driver(&foo_driver);
246}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700247
Jean Delvare0e478582008-10-22 20:21:32 +0200248/* Substitute your own name and email address */
249MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
250MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
Linus Torvalds1da177e2005-04-16 15:20:36 -0700251
Jean Delvare0e478582008-10-22 20:21:32 +0200252/* a few non-GPL license types are also allowed */
253MODULE_LICENSE("GPL");
Jean Delvareeefcd752007-05-01 23:26:35 +0200254
Jean Delvare0e478582008-10-22 20:21:32 +0200255module_init(foo_init);
256module_exit(foo_cleanup);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700257
Jean Delvare0e478582008-10-22 20:21:32 +0200258Note that some functions are marked by `__init'. These functions can
259be removed after kernel booting (or module loading) is completed.
260Likewise, functions marked by `__exit' are dropped by the compiler when
261the code is built into the kernel, as they would never be called.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700262
Jean Delvarefb687d72005-12-18 16:51:55 +0100263
David Brownellf37dd802007-02-13 22:09:00 +0100264Power Management
265================
266
267If your I2C device needs special handling when entering a system low
268power state -- like putting a transceiver into a low power mode, or
269activating a system wakeup mechanism -- do that in the suspend() method.
270The resume() method should reverse what the suspend() method does.
271
272These are standard driver model calls, and they work just like they
273would for any other driver stack. The calls can sleep, and can use
274I2C messaging to the device being suspended or resumed (since their
275parent I2C adapter is active when these calls are issued, and IRQs
276are still enabled).
277
278
279System Shutdown
280===============
281
282If your I2C device needs special handling when the system shuts down
283or reboots (including kexec) -- like turning something off -- use a
284shutdown() method.
285
286Again, this is a standard driver model call, working just like it
287would for any other driver stack: the calls can sleep, and can use
288I2C messaging.
289
290
Linus Torvalds1da177e2005-04-16 15:20:36 -0700291Command function
292================
293
294A generic ioctl-like function call back is supported. You will seldom
Jean Delvarefb687d72005-12-18 16:51:55 +0100295need this, and its use is deprecated anyway, so newer design should not
Jean Delvare0e478582008-10-22 20:21:32 +0200296use it.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700297
298
299Sending and receiving
300=====================
301
302If you want to communicate with your device, there are several functions
Jean Delvare0e478582008-10-22 20:21:32 +0200303to do this. You can find all of them in <linux/i2c.h>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700304
Jean Delvare0e478582008-10-22 20:21:32 +0200305If you can choose between plain I2C communication and SMBus level
306communication, please use the latter. All adapters understand SMBus level
307commands, but only some of them understand plain I2C!
Linus Torvalds1da177e2005-04-16 15:20:36 -0700308
309
Jean Delvare0e478582008-10-22 20:21:32 +0200310Plain I2C communication
Linus Torvalds1da177e2005-04-16 15:20:36 -0700311-----------------------
312
Jean Delvare0e478582008-10-22 20:21:32 +0200313 int i2c_master_send(struct i2c_client *client, const char *buf,
314 int count);
315 int i2c_master_recv(struct i2c_client *client, char *buf, int count);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700316
317These routines read and write some bytes from/to a client. The client
318contains the i2c address, so you do not have to include it. The second
Jean Delvare0e478582008-10-22 20:21:32 +0200319parameter contains the bytes to read/write, the third the number of bytes
320to read/write (must be less than the length of the buffer.) Returned is
321the actual number of bytes read/written.
322
323 int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
324 int num);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700325
326This sends a series of messages. Each message can be a read or write,
327and they can be mixed in any way. The transactions are combined: no
328stop bit is sent between transaction. The i2c_msg structure contains
329for each message the client address, the number of bytes of the message
330and the message data itself.
331
332You can read the file `i2c-protocol' for more information about the
Jean Delvare0e478582008-10-22 20:21:32 +0200333actual I2C protocol.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700334
335
336SMBus communication
337-------------------
338
Jean Delvare0e478582008-10-22 20:21:32 +0200339 s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
340 unsigned short flags, char read_write, u8 command,
341 int size, union i2c_smbus_data *data);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700342
Jean Delvare0e478582008-10-22 20:21:32 +0200343This is the generic SMBus function. All functions below are implemented
344in terms of it. Never use this function directly!
Linus Torvalds1da177e2005-04-16 15:20:36 -0700345
Jean Delvare0e478582008-10-22 20:21:32 +0200346 s32 i2c_smbus_read_byte(struct i2c_client *client);
347 s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
348 s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
349 s32 i2c_smbus_write_byte_data(struct i2c_client *client,
350 u8 command, u8 value);
351 s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command);
352 s32 i2c_smbus_write_word_data(struct i2c_client *client,
353 u8 command, u16 value);
354 s32 i2c_smbus_process_call(struct i2c_client *client,
355 u8 command, u16 value);
356 s32 i2c_smbus_read_block_data(struct i2c_client *client,
357 u8 command, u8 *values);
358 s32 i2c_smbus_write_block_data(struct i2c_client *client,
359 u8 command, u8 length, const u8 *values);
360 s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client,
361 u8 command, u8 length, u8 *values);
362 s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client,
363 u8 command, u8 length,
364 const u8 *values);
Jean Delvare67c2e662008-07-14 22:38:23 +0200365
366These ones were removed from i2c-core because they had no users, but could
367be added back later if needed:
368
Jean Delvare0e478582008-10-22 20:21:32 +0200369 s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
370 s32 i2c_smbus_block_process_call(struct i2c_client *client,
371 u8 command, u8 length, u8 *values);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700372
David Brownell24a5bb72008-07-14 22:38:23 +0200373All these transactions return a negative errno value on failure. The 'write'
374transactions return 0 on success; the 'read' transactions return the read
375value, except for block transactions, which return the number of values
376read. The block buffers need not be longer than 32 bytes.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700377
378You can read the file `smbus-protocol' for more information about the
379actual SMBus protocol.
380
381
382General purpose routines
383========================
384
385Below all general purpose routines are listed, that were not mentioned
386before.
387
Jean Delvare0e478582008-10-22 20:21:32 +0200388 /* Return the adapter number for a specific adapter */
389 int i2c_adapter_id(struct i2c_adapter *adap);