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