1f6fcefa1SLuca Ceresoli=============================== 2f6fcefa1SLuca CeresoliImplementing I2C device drivers 3f6fcefa1SLuca Ceresoli=============================== 4ccf988b6SMauro Carvalho Chehab 5ccf988b6SMauro Carvalho ChehabThis is a small guide for those who want to write kernel drivers for I2C 6ccf988b6SMauro Carvalho Chehabor SMBus devices, using Linux as the protocol host/master (not slave). 7ccf988b6SMauro Carvalho Chehab 8ccf988b6SMauro Carvalho ChehabTo set up a driver, you need to do several things. Some are optional, and 9ccf988b6SMauro Carvalho Chehabsome things can be done slightly or completely different. Use this as a 10ccf988b6SMauro Carvalho Chehabguide, not as a rule book! 11ccf988b6SMauro Carvalho Chehab 12ccf988b6SMauro Carvalho Chehab 13ccf988b6SMauro Carvalho ChehabGeneral remarks 14ccf988b6SMauro Carvalho Chehab=============== 15ccf988b6SMauro Carvalho Chehab 16ccf988b6SMauro Carvalho ChehabTry to keep the kernel namespace as clean as possible. The best way to 17ccf988b6SMauro Carvalho Chehabdo this is to use a unique prefix for all global symbols. This is 18ccf988b6SMauro Carvalho Chehabespecially important for exported symbols, but it is a good idea to do 19ccf988b6SMauro Carvalho Chehabit for non-exported symbols too. We will use the prefix ``foo_`` in this 20ccf988b6SMauro Carvalho Chehabtutorial. 21ccf988b6SMauro Carvalho Chehab 22ccf988b6SMauro Carvalho Chehab 23ccf988b6SMauro Carvalho ChehabThe driver structure 24ccf988b6SMauro Carvalho Chehab==================== 25ccf988b6SMauro Carvalho Chehab 26ccf988b6SMauro Carvalho ChehabUsually, you will implement a single driver structure, and instantiate 27ccf988b6SMauro Carvalho Chehaball clients from it. Remember, a driver structure contains general access 28ccf988b6SMauro Carvalho Chehabroutines, and should be zero-initialized except for fields with data you 29ccf988b6SMauro Carvalho Chehabprovide. A client structure holds device-specific information like the 30ccf988b6SMauro Carvalho Chehabdriver model device node, and its I2C address. 31ccf988b6SMauro Carvalho Chehab 32ccf988b6SMauro Carvalho Chehab:: 33ccf988b6SMauro Carvalho Chehab 34ccf988b6SMauro Carvalho Chehab static struct i2c_device_id foo_idtable[] = { 35ccf988b6SMauro Carvalho Chehab { "foo", my_id_for_foo }, 36ccf988b6SMauro Carvalho Chehab { "bar", my_id_for_bar }, 37ccf988b6SMauro Carvalho Chehab { } 38ccf988b6SMauro Carvalho Chehab }; 39ccf988b6SMauro Carvalho Chehab 40ccf988b6SMauro Carvalho Chehab MODULE_DEVICE_TABLE(i2c, foo_idtable); 41ccf988b6SMauro Carvalho Chehab 42ccf988b6SMauro Carvalho Chehab static struct i2c_driver foo_driver = { 43ccf988b6SMauro Carvalho Chehab .driver = { 44ccf988b6SMauro Carvalho Chehab .name = "foo", 45ccf988b6SMauro Carvalho Chehab .pm = &foo_pm_ops, /* optional */ 46ccf988b6SMauro Carvalho Chehab }, 47ccf988b6SMauro Carvalho Chehab 48ccf988b6SMauro Carvalho Chehab .id_table = foo_idtable, 497d711966SUwe Kleine-König .probe = foo_probe, 50ccf988b6SMauro Carvalho Chehab .remove = foo_remove, 51ccf988b6SMauro Carvalho Chehab 52ccf988b6SMauro Carvalho Chehab .shutdown = foo_shutdown, /* optional */ 53ccf988b6SMauro Carvalho Chehab .command = foo_command, /* optional, deprecated */ 54ccf988b6SMauro Carvalho Chehab } 55ccf988b6SMauro Carvalho Chehab 56ccf988b6SMauro Carvalho ChehabThe name field is the driver name, and must not contain spaces. It 57ccf988b6SMauro Carvalho Chehabshould match the module name (if the driver can be compiled as a module), 58ccf988b6SMauro Carvalho Chehabalthough you can use MODULE_ALIAS (passing "foo" in this example) to add 59ccf988b6SMauro Carvalho Chehabanother name for the module. If the driver name doesn't match the module 60ccf988b6SMauro Carvalho Chehabname, the module won't be automatically loaded (hotplug/coldplug). 61ccf988b6SMauro Carvalho Chehab 62ccf988b6SMauro Carvalho ChehabAll other fields are for call-back functions which will be explained 63ccf988b6SMauro Carvalho Chehabbelow. 64ccf988b6SMauro Carvalho Chehab 65ccf988b6SMauro Carvalho Chehab 66ccf988b6SMauro Carvalho ChehabExtra client data 67ccf988b6SMauro Carvalho Chehab================= 68ccf988b6SMauro Carvalho Chehab 69ccf988b6SMauro Carvalho ChehabEach client structure has a special ``data`` field that can point to any 70ccf988b6SMauro Carvalho Chehabstructure at all. You should use this to keep device-specific data. 71ccf988b6SMauro Carvalho Chehab 72ccf988b6SMauro Carvalho Chehab:: 73ccf988b6SMauro Carvalho Chehab 74ccf988b6SMauro Carvalho Chehab /* store the value */ 75ccf988b6SMauro Carvalho Chehab void i2c_set_clientdata(struct i2c_client *client, void *data); 76ccf988b6SMauro Carvalho Chehab 77ccf988b6SMauro Carvalho Chehab /* retrieve the value */ 78ccf988b6SMauro Carvalho Chehab void *i2c_get_clientdata(const struct i2c_client *client); 79ccf988b6SMauro Carvalho Chehab 80ccf988b6SMauro Carvalho ChehabNote that starting with kernel 2.6.34, you don't have to set the ``data`` field 81ccf988b6SMauro Carvalho Chehabto NULL in remove() or if probe() failed anymore. The i2c-core does this 82ccf988b6SMauro Carvalho Chehabautomatically on these occasions. Those are also the only times the core will 83ccf988b6SMauro Carvalho Chehabtouch this field. 84ccf988b6SMauro Carvalho Chehab 85ccf988b6SMauro Carvalho Chehab 86ccf988b6SMauro Carvalho ChehabAccessing the client 87ccf988b6SMauro Carvalho Chehab==================== 88ccf988b6SMauro Carvalho Chehab 89ccf988b6SMauro Carvalho ChehabLet's say we have a valid client structure. At some time, we will need 90ccf988b6SMauro Carvalho Chehabto gather information from the client, or write new information to the 91ccf988b6SMauro Carvalho Chehabclient. 92ccf988b6SMauro Carvalho Chehab 93ccf988b6SMauro Carvalho ChehabI have found it useful to define foo_read and foo_write functions for this. 942f07c05fSLuca CeresoliFor some cases, it will be easier to call the I2C functions directly, 95ccf988b6SMauro Carvalho Chehabbut many chips have some kind of register-value idea that can easily 96ccf988b6SMauro Carvalho Chehabbe encapsulated. 97ccf988b6SMauro Carvalho Chehab 98ccf988b6SMauro Carvalho ChehabThe below functions are simple examples, and should not be copied 99ccf988b6SMauro Carvalho Chehabliterally:: 100ccf988b6SMauro Carvalho Chehab 101ccf988b6SMauro Carvalho Chehab int foo_read_value(struct i2c_client *client, u8 reg) 102ccf988b6SMauro Carvalho Chehab { 103ccf988b6SMauro Carvalho Chehab if (reg < 0x10) /* byte-sized register */ 104ccf988b6SMauro Carvalho Chehab return i2c_smbus_read_byte_data(client, reg); 105ccf988b6SMauro Carvalho Chehab else /* word-sized register */ 106ccf988b6SMauro Carvalho Chehab return i2c_smbus_read_word_data(client, reg); 107ccf988b6SMauro Carvalho Chehab } 108ccf988b6SMauro Carvalho Chehab 109ccf988b6SMauro Carvalho Chehab int foo_write_value(struct i2c_client *client, u8 reg, u16 value) 110ccf988b6SMauro Carvalho Chehab { 111ccf988b6SMauro Carvalho Chehab if (reg == 0x10) /* Impossible to write - driver error! */ 112ccf988b6SMauro Carvalho Chehab return -EINVAL; 113ccf988b6SMauro Carvalho Chehab else if (reg < 0x10) /* byte-sized register */ 114ccf988b6SMauro Carvalho Chehab return i2c_smbus_write_byte_data(client, reg, value); 115ccf988b6SMauro Carvalho Chehab else /* word-sized register */ 116ccf988b6SMauro Carvalho Chehab return i2c_smbus_write_word_data(client, reg, value); 117ccf988b6SMauro Carvalho Chehab } 118ccf988b6SMauro Carvalho Chehab 119ccf988b6SMauro Carvalho Chehab 120ccf988b6SMauro Carvalho ChehabProbing and attaching 121ccf988b6SMauro Carvalho Chehab===================== 122ccf988b6SMauro Carvalho Chehab 123ccf988b6SMauro Carvalho ChehabThe Linux I2C stack was originally written to support access to hardware 124ccf988b6SMauro Carvalho Chehabmonitoring chips on PC motherboards, and thus used to embed some assumptions 125ccf988b6SMauro Carvalho Chehabthat were more appropriate to SMBus (and PCs) than to I2C. One of these 126ccf988b6SMauro Carvalho Chehabassumptions was that most adapters and devices drivers support the SMBUS_QUICK 127ccf988b6SMauro Carvalho Chehabprotocol to probe device presence. Another was that devices and their drivers 128ccf988b6SMauro Carvalho Chehabcan be sufficiently configured using only such probe primitives. 129ccf988b6SMauro Carvalho Chehab 130ccf988b6SMauro Carvalho ChehabAs Linux and its I2C stack became more widely used in embedded systems 131ccf988b6SMauro Carvalho Chehaband complex components such as DVB adapters, those assumptions became more 132ccf988b6SMauro Carvalho Chehabproblematic. Drivers for I2C devices that issue interrupts need more (and 133ccf988b6SMauro Carvalho Chehabdifferent) configuration information, as do drivers handling chip variants 134ccf988b6SMauro Carvalho Chehabthat can't be distinguished by protocol probing, or which need some board 135ccf988b6SMauro Carvalho Chehabspecific information to operate correctly. 136ccf988b6SMauro Carvalho Chehab 137ccf988b6SMauro Carvalho Chehab 138ccf988b6SMauro Carvalho ChehabDevice/Driver Binding 139ccf988b6SMauro Carvalho Chehab--------------------- 140ccf988b6SMauro Carvalho Chehab 141ccf988b6SMauro Carvalho ChehabSystem infrastructure, typically board-specific initialization code or 142ccf988b6SMauro Carvalho Chehabboot firmware, reports what I2C devices exist. For example, there may be 143ccf988b6SMauro Carvalho Chehaba table, in the kernel or from the boot loader, identifying I2C devices 144ccf988b6SMauro Carvalho Chehaband linking them to board-specific configuration information about IRQs 145ccf988b6SMauro Carvalho Chehaband other wiring artifacts, chip type, and so on. That could be used to 146ccf988b6SMauro Carvalho Chehabcreate i2c_client objects for each I2C device. 147ccf988b6SMauro Carvalho Chehab 148ccf988b6SMauro Carvalho ChehabI2C device drivers using this binding model work just like any other 149ccf988b6SMauro Carvalho Chehabkind of driver in Linux: they provide a probe() method to bind to 150ccf988b6SMauro Carvalho Chehabthose devices, and a remove() method to unbind. 151ccf988b6SMauro Carvalho Chehab 152ccf988b6SMauro Carvalho Chehab:: 153ccf988b6SMauro Carvalho Chehab 15432d45361SStephen Kitt static int foo_probe(struct i2c_client *client); 155ed5c2f5fSUwe Kleine-König static void foo_remove(struct i2c_client *client); 156ccf988b6SMauro Carvalho Chehab 157ccf988b6SMauro Carvalho ChehabRemember that the i2c_driver does not create those client handles. The 158ccf988b6SMauro Carvalho Chehabhandle may be used during foo_probe(). If foo_probe() reports success 159ccf988b6SMauro Carvalho Chehab(zero not a negative status code) it may save the handle and use it until 160ccf988b6SMauro Carvalho Chehabfoo_remove() returns. That binding model is used by most Linux drivers. 161ccf988b6SMauro Carvalho Chehab 162ccf988b6SMauro Carvalho ChehabThe probe function is called when an entry in the id_table name field 16332d45361SStephen Kittmatches the device's name. If the probe function needs that entry, it 16432d45361SStephen Kittcan retrieve it using 16532d45361SStephen Kitt 16632d45361SStephen Kitt:: 16732d45361SStephen Kitt 16832d45361SStephen Kitt const struct i2c_device_id *id = i2c_match_id(foo_idtable, client); 169ccf988b6SMauro Carvalho Chehab 170ccf988b6SMauro Carvalho Chehab 171ccf988b6SMauro Carvalho ChehabDevice Creation 172ccf988b6SMauro Carvalho Chehab--------------- 173ccf988b6SMauro Carvalho Chehab 174ccf988b6SMauro Carvalho ChehabIf you know for a fact that an I2C device is connected to a given I2C bus, 175ccf988b6SMauro Carvalho Chehabyou can instantiate that device by simply filling an i2c_board_info 176ccf988b6SMauro Carvalho Chehabstructure with the device address and driver name, and calling 177e8d51e96SWolfram Sangi2c_new_client_device(). This will create the device, then the driver core 178e8d51e96SWolfram Sangwill take care of finding the right driver and will call its probe() method. 179ccf988b6SMauro Carvalho ChehabIf a driver supports different device types, you can specify the type you 180ccf988b6SMauro Carvalho Chehabwant using the type field. You can also specify an IRQ and platform data 181ccf988b6SMauro Carvalho Chehabif needed. 182ccf988b6SMauro Carvalho Chehab 183ccf988b6SMauro Carvalho ChehabSometimes you know that a device is connected to a given I2C bus, but you 184ccf988b6SMauro Carvalho Chehabdon't know the exact address it uses. This happens on TV adapters for 185ccf988b6SMauro Carvalho Chehabexample, where the same driver supports dozens of slightly different 186ccf988b6SMauro Carvalho Chehabmodels, and I2C device addresses change from one model to the next. In 187c1d08475SWolfram Sangthat case, you can use the i2c_new_scanned_device() variant, which is 188e8d51e96SWolfram Sangsimilar to i2c_new_client_device(), except that it takes an additional list 189e8d51e96SWolfram Sangof possible I2C addresses to probe. A device is created for the first 190ccf988b6SMauro Carvalho Chehabresponsive address in the list. If you expect more than one device to be 191c1d08475SWolfram Sangpresent in the address range, simply call i2c_new_scanned_device() that 192ccf988b6SMauro Carvalho Chehabmany times. 193ccf988b6SMauro Carvalho Chehab 194e8d51e96SWolfram SangThe call to i2c_new_client_device() or i2c_new_scanned_device() typically 195e8d51e96SWolfram Sanghappens in the I2C bus driver. You may want to save the returned i2c_client 196ccf988b6SMauro Carvalho Chehabreference for later use. 197ccf988b6SMauro Carvalho Chehab 198ccf988b6SMauro Carvalho Chehab 199ccf988b6SMauro Carvalho ChehabDevice Detection 200ccf988b6SMauro Carvalho Chehab---------------- 201ccf988b6SMauro Carvalho Chehab 202*68a04aeeSHeiner KallweitThe device detection mechanism comes with a number of disadvantages. 203*68a04aeeSHeiner KallweitYou need some reliable way to identify the supported devices 204ccf988b6SMauro Carvalho Chehab(typically using device-specific, dedicated identification registers), 205ccf988b6SMauro Carvalho Chehabotherwise misdetections are likely to occur and things can get wrong 206ccf988b6SMauro Carvalho Chehabquickly. Keep in mind that the I2C protocol doesn't include any 207ccf988b6SMauro Carvalho Chehabstandard way to detect the presence of a chip at a given address, let 208ccf988b6SMauro Carvalho Chehabalone a standard way to identify devices. Even worse is the lack of 209ccf988b6SMauro Carvalho Chehabsemantics associated to bus transfers, which means that the same 210ccf988b6SMauro Carvalho Chehabtransfer can be seen as a read operation by a chip and as a write 211*68a04aeeSHeiner Kallweitoperation by another chip. For these reasons, device detection is 212*68a04aeeSHeiner Kallweitconsidered a legacy mechanism and shouldn't be used in new code. 213ccf988b6SMauro Carvalho Chehab 214ccf988b6SMauro Carvalho Chehab 215ccf988b6SMauro Carvalho ChehabDevice Deletion 216ccf988b6SMauro Carvalho Chehab--------------- 217ccf988b6SMauro Carvalho Chehab 218e8d51e96SWolfram SangEach I2C device which has been created using i2c_new_client_device() 219e8d51e96SWolfram Sangor i2c_new_scanned_device() can be unregistered by calling 220ccf988b6SMauro Carvalho Chehabi2c_unregister_device(). If you don't call it explicitly, it will be 221e8d51e96SWolfram Sangcalled automatically before the underlying I2C bus itself is removed, 222e8d51e96SWolfram Sangas a device can't survive its parent in the device driver model. 223ccf988b6SMauro Carvalho Chehab 224ccf988b6SMauro Carvalho Chehab 225ccf988b6SMauro Carvalho ChehabInitializing the driver 226ccf988b6SMauro Carvalho Chehab======================= 227ccf988b6SMauro Carvalho Chehab 228ccf988b6SMauro Carvalho ChehabWhen the kernel is booted, or when your foo driver module is inserted, 229ccf988b6SMauro Carvalho Chehabyou have to do some initializing. Fortunately, just registering the 230ccf988b6SMauro Carvalho Chehabdriver module is usually enough. 231ccf988b6SMauro Carvalho Chehab 232ccf988b6SMauro Carvalho Chehab:: 233ccf988b6SMauro Carvalho Chehab 234ccf988b6SMauro Carvalho Chehab static int __init foo_init(void) 235ccf988b6SMauro Carvalho Chehab { 236ccf988b6SMauro Carvalho Chehab return i2c_add_driver(&foo_driver); 237ccf988b6SMauro Carvalho Chehab } 238ccf988b6SMauro Carvalho Chehab module_init(foo_init); 239ccf988b6SMauro Carvalho Chehab 240ccf988b6SMauro Carvalho Chehab static void __exit foo_cleanup(void) 241ccf988b6SMauro Carvalho Chehab { 242ccf988b6SMauro Carvalho Chehab i2c_del_driver(&foo_driver); 243ccf988b6SMauro Carvalho Chehab } 244ccf988b6SMauro Carvalho Chehab module_exit(foo_cleanup); 245ccf988b6SMauro Carvalho Chehab 246ccf988b6SMauro Carvalho Chehab The module_i2c_driver() macro can be used to reduce above code. 247ccf988b6SMauro Carvalho Chehab 248ccf988b6SMauro Carvalho Chehab module_i2c_driver(foo_driver); 249ccf988b6SMauro Carvalho Chehab 250ccf988b6SMauro Carvalho ChehabNote that some functions are marked by ``__init``. These functions can 251ccf988b6SMauro Carvalho Chehabbe removed after kernel booting (or module loading) is completed. 252ccf988b6SMauro Carvalho ChehabLikewise, functions marked by ``__exit`` are dropped by the compiler when 253ccf988b6SMauro Carvalho Chehabthe code is built into the kernel, as they would never be called. 254ccf988b6SMauro Carvalho Chehab 255ccf988b6SMauro Carvalho Chehab 256ccf988b6SMauro Carvalho ChehabDriver Information 257ccf988b6SMauro Carvalho Chehab================== 258ccf988b6SMauro Carvalho Chehab 259ccf988b6SMauro Carvalho Chehab:: 260ccf988b6SMauro Carvalho Chehab 261ccf988b6SMauro Carvalho Chehab /* Substitute your own name and email address */ 262ccf988b6SMauro Carvalho Chehab MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" 263ccf988b6SMauro Carvalho Chehab MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); 264ccf988b6SMauro Carvalho Chehab 265ccf988b6SMauro Carvalho Chehab /* a few non-GPL license types are also allowed */ 266ccf988b6SMauro Carvalho Chehab MODULE_LICENSE("GPL"); 267ccf988b6SMauro Carvalho Chehab 268ccf988b6SMauro Carvalho Chehab 269ccf988b6SMauro Carvalho ChehabPower Management 270ccf988b6SMauro Carvalho Chehab================ 271ccf988b6SMauro Carvalho Chehab 272ccf988b6SMauro Carvalho ChehabIf your I2C device needs special handling when entering a system low 273ccf988b6SMauro Carvalho Chehabpower state -- like putting a transceiver into a low power mode, or 274ccf988b6SMauro Carvalho Chehabactivating a system wakeup mechanism -- do that by implementing the 275ccf988b6SMauro Carvalho Chehabappropriate callbacks for the dev_pm_ops of the driver (like suspend 276ccf988b6SMauro Carvalho Chehaband resume). 277ccf988b6SMauro Carvalho Chehab 278ccf988b6SMauro Carvalho ChehabThese are standard driver model calls, and they work just like they 279ccf988b6SMauro Carvalho Chehabwould for any other driver stack. The calls can sleep, and can use 280ccf988b6SMauro Carvalho ChehabI2C messaging to the device being suspended or resumed (since their 281ccf988b6SMauro Carvalho Chehabparent I2C adapter is active when these calls are issued, and IRQs 282ccf988b6SMauro Carvalho Chehabare still enabled). 283ccf988b6SMauro Carvalho Chehab 284ccf988b6SMauro Carvalho Chehab 285ccf988b6SMauro Carvalho ChehabSystem Shutdown 286ccf988b6SMauro Carvalho Chehab=============== 287ccf988b6SMauro Carvalho Chehab 288ccf988b6SMauro Carvalho ChehabIf your I2C device needs special handling when the system shuts down 289ccf988b6SMauro Carvalho Chehabor reboots (including kexec) -- like turning something off -- use a 290ccf988b6SMauro Carvalho Chehabshutdown() method. 291ccf988b6SMauro Carvalho Chehab 292ccf988b6SMauro Carvalho ChehabAgain, this is a standard driver model call, working just like it 293ccf988b6SMauro Carvalho Chehabwould for any other driver stack: the calls can sleep, and can use 294ccf988b6SMauro Carvalho ChehabI2C messaging. 295ccf988b6SMauro Carvalho Chehab 296ccf988b6SMauro Carvalho Chehab 297ccf988b6SMauro Carvalho ChehabCommand function 298ccf988b6SMauro Carvalho Chehab================ 299ccf988b6SMauro Carvalho Chehab 300ccf988b6SMauro Carvalho ChehabA generic ioctl-like function call back is supported. You will seldom 301ccf988b6SMauro Carvalho Chehabneed this, and its use is deprecated anyway, so newer design should not 302ccf988b6SMauro Carvalho Chehabuse it. 303ccf988b6SMauro Carvalho Chehab 304ccf988b6SMauro Carvalho Chehab 305ccf988b6SMauro Carvalho ChehabSending and receiving 306ccf988b6SMauro Carvalho Chehab===================== 307ccf988b6SMauro Carvalho Chehab 308ccf988b6SMauro Carvalho ChehabIf you want to communicate with your device, there are several functions 309ccf988b6SMauro Carvalho Chehabto do this. You can find all of them in <linux/i2c.h>. 310ccf988b6SMauro Carvalho Chehab 311ccf988b6SMauro Carvalho ChehabIf you can choose between plain I2C communication and SMBus level 312ccf988b6SMauro Carvalho Chehabcommunication, please use the latter. All adapters understand SMBus level 313ccf988b6SMauro Carvalho Chehabcommands, but only some of them understand plain I2C! 314ccf988b6SMauro Carvalho Chehab 315ccf988b6SMauro Carvalho Chehab 316ccf988b6SMauro Carvalho ChehabPlain I2C communication 317ccf988b6SMauro Carvalho Chehab----------------------- 318ccf988b6SMauro Carvalho Chehab 319ccf988b6SMauro Carvalho Chehab:: 320ccf988b6SMauro Carvalho Chehab 321ccf988b6SMauro Carvalho Chehab int i2c_master_send(struct i2c_client *client, const char *buf, 322ccf988b6SMauro Carvalho Chehab int count); 323ccf988b6SMauro Carvalho Chehab int i2c_master_recv(struct i2c_client *client, char *buf, int count); 324ccf988b6SMauro Carvalho Chehab 325ccf988b6SMauro Carvalho ChehabThese routines read and write some bytes from/to a client. The client 3262f07c05fSLuca Ceresolicontains the I2C address, so you do not have to include it. The second 327ccf988b6SMauro Carvalho Chehabparameter contains the bytes to read/write, the third the number of bytes 328ccf988b6SMauro Carvalho Chehabto read/write (must be less than the length of the buffer, also should be 329ccf988b6SMauro Carvalho Chehabless than 64k since msg.len is u16.) Returned is the actual number of bytes 330ccf988b6SMauro Carvalho Chehabread/written. 331ccf988b6SMauro Carvalho Chehab 332ccf988b6SMauro Carvalho Chehab:: 333ccf988b6SMauro Carvalho Chehab 334ccf988b6SMauro Carvalho Chehab int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, 335ccf988b6SMauro Carvalho Chehab int num); 336ccf988b6SMauro Carvalho Chehab 337ccf988b6SMauro Carvalho ChehabThis sends a series of messages. Each message can be a read or write, 338ccf988b6SMauro Carvalho Chehaband they can be mixed in any way. The transactions are combined: no 3394fcb445eSLuca Ceresolistop condition is issued between transaction. The i2c_msg structure 3404fcb445eSLuca Ceresolicontains for each message the client address, the number of bytes of the 3414fcb445eSLuca Ceresolimessage and the message data itself. 342ccf988b6SMauro Carvalho Chehab 3439d55e7b0SWolfram SangYou can read the file i2c-protocol.rst for more information about the 344ccf988b6SMauro Carvalho Chehabactual I2C protocol. 345ccf988b6SMauro Carvalho Chehab 346ccf988b6SMauro Carvalho Chehab 347ccf988b6SMauro Carvalho ChehabSMBus communication 348ccf988b6SMauro Carvalho Chehab------------------- 349ccf988b6SMauro Carvalho Chehab 350ccf988b6SMauro Carvalho Chehab:: 351ccf988b6SMauro Carvalho Chehab 352ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, 353ccf988b6SMauro Carvalho Chehab unsigned short flags, char read_write, u8 command, 354ccf988b6SMauro Carvalho Chehab int size, union i2c_smbus_data *data); 355ccf988b6SMauro Carvalho Chehab 356ccf988b6SMauro Carvalho ChehabThis is the generic SMBus function. All functions below are implemented 357ccf988b6SMauro Carvalho Chehabin terms of it. Never use this function directly! 358ccf988b6SMauro Carvalho Chehab 359ccf988b6SMauro Carvalho Chehab:: 360ccf988b6SMauro Carvalho Chehab 361ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_read_byte(struct i2c_client *client); 362ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value); 363ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command); 364ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_write_byte_data(struct i2c_client *client, 365ccf988b6SMauro Carvalho Chehab u8 command, u8 value); 366ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command); 367ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_write_word_data(struct i2c_client *client, 368ccf988b6SMauro Carvalho Chehab u8 command, u16 value); 369ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_read_block_data(struct i2c_client *client, 370ccf988b6SMauro Carvalho Chehab u8 command, u8 *values); 371ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_write_block_data(struct i2c_client *client, 372ccf988b6SMauro Carvalho Chehab u8 command, u8 length, const u8 *values); 373ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client, 374ccf988b6SMauro Carvalho Chehab u8 command, u8 length, u8 *values); 375ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client, 376ccf988b6SMauro Carvalho Chehab u8 command, u8 length, 377ccf988b6SMauro Carvalho Chehab const u8 *values); 378ccf988b6SMauro Carvalho Chehab 379ccf988b6SMauro Carvalho ChehabThese ones were removed from i2c-core because they had no users, but could 380ccf988b6SMauro Carvalho Chehabbe added back later if needed:: 381ccf988b6SMauro Carvalho Chehab 382ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); 383ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_process_call(struct i2c_client *client, 384ccf988b6SMauro Carvalho Chehab u8 command, u16 value); 385ccf988b6SMauro Carvalho Chehab s32 i2c_smbus_block_process_call(struct i2c_client *client, 386ccf988b6SMauro Carvalho Chehab u8 command, u8 length, u8 *values); 387ccf988b6SMauro Carvalho Chehab 388ccf988b6SMauro Carvalho ChehabAll these transactions return a negative errno value on failure. The 'write' 389ccf988b6SMauro Carvalho Chehabtransactions return 0 on success; the 'read' transactions return the read 390ccf988b6SMauro Carvalho Chehabvalue, except for block transactions, which return the number of values 391ccf988b6SMauro Carvalho Chehabread. The block buffers need not be longer than 32 bytes. 392ccf988b6SMauro Carvalho Chehab 3939d55e7b0SWolfram SangYou can read the file smbus-protocol.rst for more information about the 394ccf988b6SMauro Carvalho Chehabactual SMBus protocol. 395ccf988b6SMauro Carvalho Chehab 396ccf988b6SMauro Carvalho Chehab 397ccf988b6SMauro Carvalho ChehabGeneral purpose routines 398ccf988b6SMauro Carvalho Chehab======================== 399ccf988b6SMauro Carvalho Chehab 400ccf988b6SMauro Carvalho ChehabBelow all general purpose routines are listed, that were not mentioned 401ccf988b6SMauro Carvalho Chehabbefore:: 402ccf988b6SMauro Carvalho Chehab 403ccf988b6SMauro Carvalho Chehab /* Return the adapter number for a specific adapter */ 404ccf988b6SMauro Carvalho Chehab int i2c_adapter_id(struct i2c_adapter *adap); 405