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