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