Documentation/i2c/writing-clients.rst

2 Implementing I2C device drivers
5 This is a small guide for those who want to write kernel drivers for I2C
19 it for non-exported symbols too. We will use the prefix ``foo_`` in this
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.
40   MODULE_DEVICE_TABLE(i2c, foo_idtable);
66 All other fields are for call-back functions which will be explained
74 structure at all.  You should use this to keep device-specific data.
85 to NULL in remove() or if probe() failed anymore. The i2c-core does this
98 For some cases, it will be easier to call the I2C functions directly,
99 but many chips have some kind of register-value idea that can easily
107 	if (reg < 0x10)	/* byte-sized register */
109 	else		/* word-sized register */
115 	if (reg == 0x10)	/* Impossible to write - driver error! */
116 		return -EINVAL;
117 	else if (reg < 0x10)	/* byte-sized register */
119 	else			/* word-sized register */
127 The Linux I2C stack was originally written to support access to hardware
129 that were more appropriate to SMBus (and PCs) than to I2C.  One of these
134 As Linux and its I2C stack became more widely used in embedded systems
136 problematic.  Drivers for I2C devices that issue interrupts need more (and
143 ---------------------
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
150 create i2c_client objects for each I2C device.
152 I2C device drivers using this binding model work just like any other
176 ---------------
178 If you know for a fact that an I2C device is connected to a given I2C bus,
187 Sometimes you know that a device is connected to a given I2C bus, but you
190 models, and I2C device addresses change from one model to the next.  In
193 of possible I2C addresses to probe.  A device is created for the first
199 happens in the I2C bus driver. You may want to save the returned i2c_client
204 ----------------
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
214 identify supported devices (returning 0 for supported ones and -ENODEV
216 (or class) so that only I2C buses which may have that type of device
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
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.
227 (typically using device-specific, dedicated identification registers),
229 quickly.  Keep in mind that the I2C protocol doesn't include any
235 instantiation should always be preferred to auto-detection where
240 ---------------
242 Each I2C device which has been created using i2c_new_client_device()
245 called automatically before the underlying I2C bus itself is removed,
287   MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
289   /* a few non-GPL license types are also allowed */
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
298 activating a system wakeup mechanism -- do that by implementing the
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
312 If your I2C device needs special handling when the system shuts down
313 or reboots (including kexec) -- like turning something off -- use a
318 I2C messaging.
324 A generic ioctl-like function call back is supported. You will seldom
333 to do this. You can find all of them in <linux/i2c.h>.
335 If you can choose between plain I2C communication and SMBus level
337 commands, but only some of them understand plain I2C!
340 Plain I2C communication
341 -----------------------
350 contains the I2C address, so you do not have to include it. The second
367 You can read the file i2c-protocol.rst for more information about the
368 actual I2C protocol.
372 -------------------
403 These ones were removed from i2c-core because they had no users, but could
417 You can read the file smbus-protocol.rst for more information about the