Commit | Line | Data |
---|---|---|
1da177e4 | 1 | This is a small guide for those who want to write kernel drivers for I2C |
4298cfc3 | 2 | or SMBus devices, using Linux as the protocol host/master (not slave). |
1da177e4 LT |
3 | |
4 | To set up a driver, you need to do several things. Some are optional, and | |
5 | some things can be done slightly or completely different. Use this as a | |
6 | guide, not as a rule book! | |
7 | ||
8 | ||
9 | General remarks | |
10 | =============== | |
11 | ||
12 | Try to keep the kernel namespace as clean as possible. The best way to | |
13 | do this is to use a unique prefix for all global symbols. This is | |
14 | especially important for exported symbols, but it is a good idea to do | |
15 | it for non-exported symbols too. We will use the prefix `foo_' in this | |
16 | tutorial, and `FOO_' for preprocessor variables. | |
17 | ||
18 | ||
19 | The driver structure | |
20 | ==================== | |
21 | ||
22 | Usually, you will implement a single driver structure, and instantiate | |
23 | all clients from it. Remember, a driver structure contains general access | |
f37dd80a DB |
24 | routines, and should be zero-initialized except for fields with data you |
25 | provide. A client structure holds device-specific information like the | |
26 | driver model device node, and its I2C address. | |
1da177e4 | 27 | |
2260e63a BD |
28 | static struct i2c_device_id foo_idtable[] = { |
29 | { "foo", my_id_for_foo }, | |
30 | { "bar", my_id_for_bar }, | |
31 | { } | |
32 | }; | |
33 | ||
34 | MODULE_DEVICE_TABLE(i2c, foo_idtable); | |
35 | ||
1da177e4 | 36 | static struct i2c_driver foo_driver = { |
d45d204f | 37 | .driver = { |
d45d204f JD |
38 | .name = "foo", |
39 | }, | |
4298cfc3 | 40 | |
2260e63a | 41 | .id_table = foo_ids, |
4298cfc3 DB |
42 | .probe = foo_probe, |
43 | .remove = foo_remove, | |
4735c98f JD |
44 | /* if device autodetection is needed: */ |
45 | .class = I2C_CLASS_SOMETHING, | |
46 | .detect = foo_detect, | |
47 | .address_data = &addr_data, | |
4298cfc3 | 48 | |
f37dd80a DB |
49 | .shutdown = foo_shutdown, /* optional */ |
50 | .suspend = foo_suspend, /* optional */ | |
51 | .resume = foo_resume, /* optional */ | |
52 | .command = foo_command, /* optional */ | |
1da177e4 LT |
53 | } |
54 | ||
f37dd80a DB |
55 | The name field is the driver name, and must not contain spaces. It |
56 | should match the module name (if the driver can be compiled as a module), | |
57 | although you can use MODULE_ALIAS (passing "foo" in this example) to add | |
4298cfc3 DB |
58 | another name for the module. If the driver name doesn't match the module |
59 | name, the module won't be automatically loaded (hotplug/coldplug). | |
1da177e4 | 60 | |
1da177e4 LT |
61 | All other fields are for call-back functions which will be explained |
62 | below. | |
63 | ||
1da177e4 LT |
64 | |
65 | Extra client data | |
66 | ================= | |
67 | ||
f37dd80a DB |
68 | Each client structure has a special `data' field that can point to any |
69 | structure at all. You should use this to keep device-specific data, | |
70 | especially in drivers that handle multiple I2C or SMBUS devices. You | |
1da177e4 LT |
71 | do not always need this, but especially for `sensors' drivers, it can |
72 | be very useful. | |
73 | ||
f37dd80a DB |
74 | /* store the value */ |
75 | void i2c_set_clientdata(struct i2c_client *client, void *data); | |
76 | ||
77 | /* retrieve the value */ | |
7d1d8999 | 78 | void *i2c_get_clientdata(const struct i2c_client *client); |
f37dd80a | 79 | |
1da177e4 LT |
80 | An example structure is below. |
81 | ||
82 | struct foo_data { | |
e313353d | 83 | struct i2c_client *client; |
1da177e4 LT |
84 | enum chips type; /* To keep the chips type for `sensors' drivers. */ |
85 | ||
86 | /* Because the i2c bus is slow, it is often useful to cache the read | |
87 | information of a chip for some time (for example, 1 or 2 seconds). | |
88 | It depends of course on the device whether this is really worthwhile | |
89 | or even sensible. */ | |
eefcd75e | 90 | struct mutex update_lock; /* When we are reading lots of information, |
1da177e4 LT |
91 | another process should not update the |
92 | below information */ | |
93 | char valid; /* != 0 if the following fields are valid. */ | |
94 | unsigned long last_updated; /* In jiffies */ | |
95 | /* Add the read information here too */ | |
96 | }; | |
97 | ||
98 | ||
99 | Accessing the client | |
100 | ==================== | |
101 | ||
102 | Let's say we have a valid client structure. At some time, we will need | |
103 | to gather information from the client, or write new information to the | |
104 | client. How we will export this information to user-space is less | |
105 | important at this moment (perhaps we do not need to do this at all for | |
106 | some obscure clients). But we need generic reading and writing routines. | |
107 | ||
108 | I have found it useful to define foo_read and foo_write function for this. | |
109 | For some cases, it will be easier to call the i2c functions directly, | |
110 | but many chips have some kind of register-value idea that can easily | |
eefcd75e | 111 | be encapsulated. |
1da177e4 LT |
112 | |
113 | The below functions are simple examples, and should not be copied | |
114 | literally. | |
115 | ||
116 | int foo_read_value(struct i2c_client *client, u8 reg) | |
117 | { | |
118 | if (reg < 0x10) /* byte-sized register */ | |
119 | return i2c_smbus_read_byte_data(client,reg); | |
120 | else /* word-sized register */ | |
121 | return i2c_smbus_read_word_data(client,reg); | |
122 | } | |
123 | ||
124 | int foo_write_value(struct i2c_client *client, u8 reg, u16 value) | |
125 | { | |
126 | if (reg == 0x10) /* Impossible to write - driver error! */ { | |
127 | return -1; | |
128 | else if (reg < 0x10) /* byte-sized register */ | |
129 | return i2c_smbus_write_byte_data(client,reg,value); | |
130 | else /* word-sized register */ | |
131 | return i2c_smbus_write_word_data(client,reg,value); | |
132 | } | |
133 | ||
1da177e4 LT |
134 | |
135 | Probing and attaching | |
136 | ===================== | |
137 | ||
4298cfc3 | 138 | The Linux I2C stack was originally written to support access to hardware |
e313353d JD |
139 | monitoring chips on PC motherboards, and thus used to embed some assumptions |
140 | that were more appropriate to SMBus (and PCs) than to I2C. One of these | |
141 | assumptions was that most adapters and devices drivers support the SMBUS_QUICK | |
142 | protocol to probe device presence. Another was that devices and their drivers | |
4298cfc3 DB |
143 | can be sufficiently configured using only such probe primitives. |
144 | ||
145 | As Linux and its I2C stack became more widely used in embedded systems | |
146 | and complex components such as DVB adapters, those assumptions became more | |
147 | problematic. Drivers for I2C devices that issue interrupts need more (and | |
148 | different) configuration information, as do drivers handling chip variants | |
149 | that can't be distinguished by protocol probing, or which need some board | |
150 | specific information to operate correctly. | |
151 | ||
152 | Accordingly, the I2C stack now has two models for associating I2C devices | |
153 | with their drivers: the original "legacy" model, and a newer one that's | |
154 | fully compatible with the Linux 2.6 driver model. These models do not mix, | |
155 | since the "legacy" model requires drivers to create "i2c_client" device | |
156 | objects after SMBus style probing, while the Linux driver model expects | |
157 | drivers to be given such device objects in their probe() routines. | |
158 | ||
e313353d JD |
159 | The legacy model is deprecated now and will soon be removed, so we no |
160 | longer document it here. | |
161 | ||
4298cfc3 DB |
162 | |
163 | Standard Driver Model Binding ("New Style") | |
164 | ------------------------------------------- | |
165 | ||
166 | System infrastructure, typically board-specific initialization code or | |
167 | boot firmware, reports what I2C devices exist. For example, there may be | |
168 | a table, in the kernel or from the boot loader, identifying I2C devices | |
169 | and linking them to board-specific configuration information about IRQs | |
170 | and other wiring artifacts, chip type, and so on. That could be used to | |
171 | create i2c_client objects for each I2C device. | |
172 | ||
173 | I2C device drivers using this binding model work just like any other | |
174 | kind of driver in Linux: they provide a probe() method to bind to | |
175 | those devices, and a remove() method to unbind. | |
176 | ||
d2653e92 JD |
177 | static int foo_probe(struct i2c_client *client, |
178 | const struct i2c_device_id *id); | |
4298cfc3 DB |
179 | static int foo_remove(struct i2c_client *client); |
180 | ||
181 | Remember that the i2c_driver does not create those client handles. The | |
182 | handle may be used during foo_probe(). If foo_probe() reports success | |
183 | (zero not a negative status code) it may save the handle and use it until | |
184 | foo_remove() returns. That binding model is used by most Linux drivers. | |
185 | ||
2260e63a BD |
186 | The probe function is called when an entry in the id_table name field |
187 | matches the device's name. It is passed the entry that was matched so | |
188 | the driver knows which one in the table matched. | |
4298cfc3 DB |
189 | |
190 | ||
e313353d JD |
191 | Device Creation |
192 | --------------- | |
ce9e0794 JD |
193 | |
194 | If you know for a fact that an I2C device is connected to a given I2C bus, | |
195 | you can instantiate that device by simply filling an i2c_board_info | |
196 | structure with the device address and driver name, and calling | |
197 | i2c_new_device(). This will create the device, then the driver core will | |
198 | take care of finding the right driver and will call its probe() method. | |
199 | If a driver supports different device types, you can specify the type you | |
200 | want using the type field. You can also specify an IRQ and platform data | |
201 | if needed. | |
202 | ||
203 | Sometimes you know that a device is connected to a given I2C bus, but you | |
204 | don't know the exact address it uses. This happens on TV adapters for | |
205 | example, where the same driver supports dozens of slightly different | |
206 | models, and I2C device addresses change from one model to the next. In | |
207 | that case, you can use the i2c_new_probed_device() variant, which is | |
208 | similar to i2c_new_device(), except that it takes an additional list of | |
209 | possible I2C addresses to probe. A device is created for the first | |
210 | responsive address in the list. If you expect more than one device to be | |
211 | present in the address range, simply call i2c_new_probed_device() that | |
212 | many times. | |
213 | ||
214 | The call to i2c_new_device() or i2c_new_probed_device() typically happens | |
215 | in the I2C bus driver. You may want to save the returned i2c_client | |
216 | reference for later use. | |
217 | ||
218 | ||
e313353d JD |
219 | Device Detection |
220 | ---------------- | |
4735c98f JD |
221 | |
222 | Sometimes you do not know in advance which I2C devices are connected to | |
223 | a given I2C bus. This is for example the case of hardware monitoring | |
224 | devices on a PC's SMBus. In that case, you may want to let your driver | |
225 | detect supported devices automatically. This is how the legacy model | |
226 | was working, and is now available as an extension to the standard | |
227 | driver model (so that we can finally get rid of the legacy model.) | |
228 | ||
229 | You simply have to define a detect callback which will attempt to | |
230 | identify supported devices (returning 0 for supported ones and -ENODEV | |
231 | for unsupported ones), a list of addresses to probe, and a device type | |
232 | (or class) so that only I2C buses which may have that type of device | |
233 | connected (and not otherwise enumerated) will be probed. The i2c | |
234 | core will then call you back as needed and will instantiate a device | |
235 | for you for every successful detection. | |
236 | ||
237 | Note that this mechanism is purely optional and not suitable for all | |
238 | devices. You need some reliable way to identify the supported devices | |
239 | (typically using device-specific, dedicated identification registers), | |
240 | otherwise misdetections are likely to occur and things can get wrong | |
241 | quickly. | |
242 | ||
243 | ||
e313353d JD |
244 | Device Deletion |
245 | --------------- | |
ce9e0794 JD |
246 | |
247 | Each I2C device which has been created using i2c_new_device() or | |
248 | i2c_new_probed_device() can be unregistered by calling | |
249 | i2c_unregister_device(). If you don't call it explicitly, it will be | |
250 | called automatically before the underlying I2C bus itself is removed, as a | |
251 | device can't survive its parent in the device driver model. | |
252 | ||
253 | ||
1da177e4 LT |
254 | Initializing the module or kernel |
255 | ================================= | |
256 | ||
257 | When the kernel is booted, or when your foo driver module is inserted, | |
258 | you have to do some initializing. Fortunately, just attaching (registering) | |
259 | the driver module is usually enough. | |
260 | ||
1da177e4 LT |
261 | static int __init foo_init(void) |
262 | { | |
263 | int res; | |
1da177e4 LT |
264 | |
265 | if ((res = i2c_add_driver(&foo_driver))) { | |
266 | printk("foo: Driver registration failed, module not inserted.\n"); | |
1da177e4 LT |
267 | return res; |
268 | } | |
1da177e4 LT |
269 | return 0; |
270 | } | |
271 | ||
eefcd75e | 272 | static void __exit foo_cleanup(void) |
1da177e4 | 273 | { |
eefcd75e | 274 | i2c_del_driver(&foo_driver); |
1da177e4 LT |
275 | } |
276 | ||
277 | /* Substitute your own name and email address */ | |
278 | MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" | |
279 | MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); | |
280 | ||
eefcd75e JD |
281 | /* a few non-GPL license types are also allowed */ |
282 | MODULE_LICENSE("GPL"); | |
283 | ||
1da177e4 LT |
284 | module_init(foo_init); |
285 | module_exit(foo_cleanup); | |
286 | ||
287 | Note that some functions are marked by `__init', and some data structures | |
eefcd75e | 288 | by `__initdata'. These functions and structures can be removed after |
1da177e4 LT |
289 | kernel booting (or module loading) is completed. |
290 | ||
fb687d73 | 291 | |
f37dd80a DB |
292 | Power Management |
293 | ================ | |
294 | ||
295 | If your I2C device needs special handling when entering a system low | |
296 | power state -- like putting a transceiver into a low power mode, or | |
297 | activating a system wakeup mechanism -- do that in the suspend() method. | |
298 | The resume() method should reverse what the suspend() method does. | |
299 | ||
300 | These are standard driver model calls, and they work just like they | |
301 | would for any other driver stack. The calls can sleep, and can use | |
302 | I2C messaging to the device being suspended or resumed (since their | |
303 | parent I2C adapter is active when these calls are issued, and IRQs | |
304 | are still enabled). | |
305 | ||
306 | ||
307 | System Shutdown | |
308 | =============== | |
309 | ||
310 | If your I2C device needs special handling when the system shuts down | |
311 | or reboots (including kexec) -- like turning something off -- use a | |
312 | shutdown() method. | |
313 | ||
314 | Again, this is a standard driver model call, working just like it | |
315 | would for any other driver stack: the calls can sleep, and can use | |
316 | I2C messaging. | |
317 | ||
318 | ||
1da177e4 LT |
319 | Command function |
320 | ================ | |
321 | ||
322 | A generic ioctl-like function call back is supported. You will seldom | |
fb687d73 JD |
323 | need this, and its use is deprecated anyway, so newer design should not |
324 | use it. Set it to NULL. | |
1da177e4 LT |
325 | |
326 | ||
327 | Sending and receiving | |
328 | ===================== | |
329 | ||
330 | If you want to communicate with your device, there are several functions | |
331 | to do this. You can find all of them in i2c.h. | |
332 | ||
333 | If you can choose between plain i2c communication and SMBus level | |
334 | communication, please use the last. All adapters understand SMBus level | |
335 | commands, but only some of them understand plain i2c! | |
336 | ||
337 | ||
338 | Plain i2c communication | |
339 | ----------------------- | |
340 | ||
341 | extern int i2c_master_send(struct i2c_client *,const char* ,int); | |
342 | extern int i2c_master_recv(struct i2c_client *,char* ,int); | |
343 | ||
344 | These routines read and write some bytes from/to a client. The client | |
345 | contains the i2c address, so you do not have to include it. The second | |
346 | parameter contains the bytes the read/write, the third the length of the | |
347 | buffer. Returned is the actual number of bytes read/written. | |
348 | ||
349 | extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, | |
350 | int num); | |
351 | ||
352 | This sends a series of messages. Each message can be a read or write, | |
353 | and they can be mixed in any way. The transactions are combined: no | |
354 | stop bit is sent between transaction. The i2c_msg structure contains | |
355 | for each message the client address, the number of bytes of the message | |
356 | and the message data itself. | |
357 | ||
358 | You can read the file `i2c-protocol' for more information about the | |
359 | actual i2c protocol. | |
360 | ||
361 | ||
362 | SMBus communication | |
363 | ------------------- | |
364 | ||
365 | extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr, | |
366 | unsigned short flags, | |
367 | char read_write, u8 command, int size, | |
368 | union i2c_smbus_data * data); | |
369 | ||
370 | This is the generic SMBus function. All functions below are implemented | |
371 | in terms of it. Never use this function directly! | |
372 | ||
373 | ||
1da177e4 LT |
374 | extern s32 i2c_smbus_read_byte(struct i2c_client * client); |
375 | extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value); | |
376 | extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command); | |
377 | extern s32 i2c_smbus_write_byte_data(struct i2c_client * client, | |
378 | u8 command, u8 value); | |
379 | extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command); | |
380 | extern s32 i2c_smbus_write_word_data(struct i2c_client * client, | |
381 | u8 command, u16 value); | |
596c88f4 PM |
382 | extern s32 i2c_smbus_process_call(struct i2c_client *client, |
383 | u8 command, u16 value); | |
67c2e665 JD |
384 | extern s32 i2c_smbus_read_block_data(struct i2c_client * client, |
385 | u8 command, u8 *values); | |
1da177e4 LT |
386 | extern s32 i2c_smbus_write_block_data(struct i2c_client * client, |
387 | u8 command, u8 length, | |
388 | u8 *values); | |
7865e249 | 389 | extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, |
4b2643d7 | 390 | u8 command, u8 length, u8 *values); |
1da177e4 LT |
391 | extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client, |
392 | u8 command, u8 length, | |
393 | u8 *values); | |
67c2e665 JD |
394 | |
395 | These ones were removed from i2c-core because they had no users, but could | |
396 | be added back later if needed: | |
397 | ||
398 | extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value); | |
1da177e4 LT |
399 | extern s32 i2c_smbus_block_process_call(struct i2c_client *client, |
400 | u8 command, u8 length, | |
401 | u8 *values) | |
402 | ||
24a5bb7b DB |
403 | All these transactions return a negative errno value on failure. The 'write' |
404 | transactions return 0 on success; the 'read' transactions return the read | |
405 | value, except for block transactions, which return the number of values | |
406 | read. The block buffers need not be longer than 32 bytes. | |
1da177e4 LT |
407 | |
408 | You can read the file `smbus-protocol' for more information about the | |
409 | actual SMBus protocol. | |
410 | ||
411 | ||
412 | General purpose routines | |
413 | ======================== | |
414 | ||
415 | Below all general purpose routines are listed, that were not mentioned | |
416 | before. | |
417 | ||
eefcd75e | 418 | /* This call returns a unique low identifier for each registered adapter. |
1da177e4 LT |
419 | */ |
420 | extern int i2c_adapter_id(struct i2c_adapter *adap); | |
421 |