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