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