1f6fcefa1SLuca Ceresoli============================================ 2f6fcefa1SLuca CeresoliImplementing I2C device drivers in userspace 3f6fcefa1SLuca Ceresoli============================================ 4ccf988b6SMauro Carvalho Chehab 52f07c05fSLuca CeresoliUsually, I2C devices are controlled by a kernel driver. But it is also 6ccf988b6SMauro Carvalho Chehabpossible to access all devices on an adapter from userspace, through 7ccf988b6SMauro Carvalho Chehabthe /dev interface. You need to load module i2c-dev for this. 8ccf988b6SMauro Carvalho Chehab 92f07c05fSLuca CeresoliEach registered I2C adapter gets a number, counting from 0. You can 10ccf988b6SMauro Carvalho Chehabexamine /sys/class/i2c-dev/ to see what number corresponds to which adapter. 11ccf988b6SMauro Carvalho ChehabAlternatively, you can run "i2cdetect -l" to obtain a formatted list of all 122f07c05fSLuca CeresoliI2C adapters present on your system at a given time. i2cdetect is part of 13ccf988b6SMauro Carvalho Chehabthe i2c-tools package. 14ccf988b6SMauro Carvalho Chehab 15ccf988b6SMauro Carvalho ChehabI2C device files are character device files with major device number 89 16ccf988b6SMauro Carvalho Chehaband a minor device number corresponding to the number assigned as 17ccf988b6SMauro Carvalho Chehabexplained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., 182f07c05fSLuca Ceresolii2c-10, ...). All 256 minor device numbers are reserved for I2C. 19ccf988b6SMauro Carvalho Chehab 20ccf988b6SMauro Carvalho Chehab 21ccf988b6SMauro Carvalho ChehabC example 22ccf988b6SMauro Carvalho Chehab========= 23ccf988b6SMauro Carvalho Chehab 242f07c05fSLuca CeresoliSo let's say you want to access an I2C adapter from a C program. 25ccf988b6SMauro Carvalho ChehabFirst, you need to include these two headers:: 26ccf988b6SMauro Carvalho Chehab 27ccf988b6SMauro Carvalho Chehab #include <linux/i2c-dev.h> 28ccf988b6SMauro Carvalho Chehab #include <i2c/smbus.h> 29ccf988b6SMauro Carvalho Chehab 30ccf988b6SMauro Carvalho ChehabNow, you have to decide which adapter you want to access. You should 31ccf988b6SMauro Carvalho Chehabinspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. 32ccf988b6SMauro Carvalho ChehabAdapter numbers are assigned somewhat dynamically, so you can not 33ccf988b6SMauro Carvalho Chehabassume much about them. They can even change from one boot to the next. 34ccf988b6SMauro Carvalho Chehab 35ccf988b6SMauro Carvalho ChehabNext thing, open the device file, as follows:: 36ccf988b6SMauro Carvalho Chehab 37ccf988b6SMauro Carvalho Chehab int file; 38ccf988b6SMauro Carvalho Chehab int adapter_nr = 2; /* probably dynamically determined */ 39ccf988b6SMauro Carvalho Chehab char filename[20]; 40ccf988b6SMauro Carvalho Chehab 41ccf988b6SMauro Carvalho Chehab snprintf(filename, 19, "/dev/i2c-%d", adapter_nr); 42ccf988b6SMauro Carvalho Chehab file = open(filename, O_RDWR); 43ccf988b6SMauro Carvalho Chehab if (file < 0) { 44ccf988b6SMauro Carvalho Chehab /* ERROR HANDLING; you can check errno to see what went wrong */ 45ccf988b6SMauro Carvalho Chehab exit(1); 46ccf988b6SMauro Carvalho Chehab } 47ccf988b6SMauro Carvalho Chehab 48ccf988b6SMauro Carvalho ChehabWhen you have opened the device, you must specify with what device 49ccf988b6SMauro Carvalho Chehabaddress you want to communicate:: 50ccf988b6SMauro Carvalho Chehab 51ccf988b6SMauro Carvalho Chehab int addr = 0x40; /* The I2C address */ 52ccf988b6SMauro Carvalho Chehab 53ccf988b6SMauro Carvalho Chehab if (ioctl(file, I2C_SLAVE, addr) < 0) { 54ccf988b6SMauro Carvalho Chehab /* ERROR HANDLING; you can check errno to see what went wrong */ 55ccf988b6SMauro Carvalho Chehab exit(1); 56ccf988b6SMauro Carvalho Chehab } 57ccf988b6SMauro Carvalho Chehab 58ccf988b6SMauro Carvalho ChehabWell, you are all set up now. You can now use SMBus commands or plain 59ccf988b6SMauro Carvalho ChehabI2C to communicate with your device. SMBus commands are preferred if 60ccf988b6SMauro Carvalho Chehabthe device supports them. Both are illustrated below:: 61ccf988b6SMauro Carvalho Chehab 62ccf988b6SMauro Carvalho Chehab __u8 reg = 0x10; /* Device register to access */ 63ccf988b6SMauro Carvalho Chehab __s32 res; 64ccf988b6SMauro Carvalho Chehab char buf[10]; 65ccf988b6SMauro Carvalho Chehab 66ccf988b6SMauro Carvalho Chehab /* Using SMBus commands */ 67ccf988b6SMauro Carvalho Chehab res = i2c_smbus_read_word_data(file, reg); 68ccf988b6SMauro Carvalho Chehab if (res < 0) { 692f07c05fSLuca Ceresoli /* ERROR HANDLING: I2C transaction failed */ 70ccf988b6SMauro Carvalho Chehab } else { 71ccf988b6SMauro Carvalho Chehab /* res contains the read word */ 72ccf988b6SMauro Carvalho Chehab } 73ccf988b6SMauro Carvalho Chehab 74ccf988b6SMauro Carvalho Chehab /* 75ccf988b6SMauro Carvalho Chehab * Using I2C Write, equivalent of 76ccf988b6SMauro Carvalho Chehab * i2c_smbus_write_word_data(file, reg, 0x6543) 77ccf988b6SMauro Carvalho Chehab */ 78ccf988b6SMauro Carvalho Chehab buf[0] = reg; 79ccf988b6SMauro Carvalho Chehab buf[1] = 0x43; 80ccf988b6SMauro Carvalho Chehab buf[2] = 0x65; 81ccf988b6SMauro Carvalho Chehab if (write(file, buf, 3) != 3) { 822f07c05fSLuca Ceresoli /* ERROR HANDLING: I2C transaction failed */ 83ccf988b6SMauro Carvalho Chehab } 84ccf988b6SMauro Carvalho Chehab 85ccf988b6SMauro Carvalho Chehab /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ 86ccf988b6SMauro Carvalho Chehab if (read(file, buf, 1) != 1) { 872f07c05fSLuca Ceresoli /* ERROR HANDLING: I2C transaction failed */ 88ccf988b6SMauro Carvalho Chehab } else { 89ccf988b6SMauro Carvalho Chehab /* buf[0] contains the read byte */ 90ccf988b6SMauro Carvalho Chehab } 91ccf988b6SMauro Carvalho Chehab 92ccf988b6SMauro Carvalho ChehabNote that only a subset of the I2C and SMBus protocols can be achieved by 93ccf988b6SMauro Carvalho Chehabthe means of read() and write() calls. In particular, so-called combined 94ccf988b6SMauro Carvalho Chehabtransactions (mixing read and write messages in the same transaction) 95ccf988b6SMauro Carvalho Chehabaren't supported. For this reason, this interface is almost never used by 96ccf988b6SMauro Carvalho Chehabuser-space programs. 97ccf988b6SMauro Carvalho Chehab 98ccf988b6SMauro Carvalho ChehabIMPORTANT: because of the use of inline functions, you *have* to use 99ccf988b6SMauro Carvalho Chehab'-O' or some variation when you compile your program! 100ccf988b6SMauro Carvalho Chehab 101ccf988b6SMauro Carvalho Chehab 102ccf988b6SMauro Carvalho ChehabFull interface description 103ccf988b6SMauro Carvalho Chehab========================== 104ccf988b6SMauro Carvalho Chehab 105ccf988b6SMauro Carvalho ChehabThe following IOCTLs are defined: 106ccf988b6SMauro Carvalho Chehab 107ccf988b6SMauro Carvalho Chehab``ioctl(file, I2C_SLAVE, long addr)`` 108ccf988b6SMauro Carvalho Chehab Change slave address. The address is passed in the 7 lower bits of the 109ccf988b6SMauro Carvalho Chehab argument (except for 10 bit addresses, passed in the 10 lower bits in this 110ccf988b6SMauro Carvalho Chehab case). 111ccf988b6SMauro Carvalho Chehab 112ccf988b6SMauro Carvalho Chehab``ioctl(file, I2C_TENBIT, long select)`` 113ccf988b6SMauro Carvalho Chehab Selects ten bit addresses if select not equals 0, selects normal 7 bit 114ccf988b6SMauro Carvalho Chehab addresses if select equals 0. Default 0. This request is only valid 115ccf988b6SMauro Carvalho Chehab if the adapter has I2C_FUNC_10BIT_ADDR. 116ccf988b6SMauro Carvalho Chehab 117ccf988b6SMauro Carvalho Chehab``ioctl(file, I2C_PEC, long select)`` 118ccf988b6SMauro Carvalho Chehab Selects SMBus PEC (packet error checking) generation and verification 119ccf988b6SMauro Carvalho Chehab if select not equals 0, disables if select equals 0. Default 0. 120ccf988b6SMauro Carvalho Chehab Used only for SMBus transactions. This request only has an effect if the 121ccf988b6SMauro Carvalho Chehab the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just 122ccf988b6SMauro Carvalho Chehab doesn't have any effect. 123ccf988b6SMauro Carvalho Chehab 124ccf988b6SMauro Carvalho Chehab``ioctl(file, I2C_FUNCS, unsigned long *funcs)`` 125ccf988b6SMauro Carvalho Chehab Gets the adapter functionality and puts it in ``*funcs``. 126ccf988b6SMauro Carvalho Chehab 127ccf988b6SMauro Carvalho Chehab``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)`` 128ccf988b6SMauro Carvalho Chehab Do combined read/write transaction without stop in between. 129ccf988b6SMauro Carvalho Chehab Only valid if the adapter has I2C_FUNC_I2C. The argument is 130ccf988b6SMauro Carvalho Chehab a pointer to a:: 131ccf988b6SMauro Carvalho Chehab 132ccf988b6SMauro Carvalho Chehab struct i2c_rdwr_ioctl_data { 133ccf988b6SMauro Carvalho Chehab struct i2c_msg *msgs; /* ptr to array of simple messages */ 134ccf988b6SMauro Carvalho Chehab int nmsgs; /* number of messages to exchange */ 135ccf988b6SMauro Carvalho Chehab } 136ccf988b6SMauro Carvalho Chehab 137ccf988b6SMauro Carvalho Chehab The msgs[] themselves contain further pointers into data buffers. 138ccf988b6SMauro Carvalho Chehab The function will write or read data to or from that buffers depending 139ccf988b6SMauro Carvalho Chehab on whether the I2C_M_RD flag is set in a particular message or not. 140ccf988b6SMauro Carvalho Chehab The slave address and whether to use ten bit address mode has to be 141ccf988b6SMauro Carvalho Chehab set in each message, overriding the values set with the above ioctl's. 142ccf988b6SMauro Carvalho Chehab 143ccf988b6SMauro Carvalho Chehab``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)`` 144ccf988b6SMauro Carvalho Chehab If possible, use the provided ``i2c_smbus_*`` methods described below instead 145ccf988b6SMauro Carvalho Chehab of issuing direct ioctls. 146ccf988b6SMauro Carvalho Chehab 1472f07c05fSLuca CeresoliYou can do plain I2C transactions by using read(2) and write(2) calls. 148ccf988b6SMauro Carvalho ChehabYou do not need to pass the address byte; instead, set it through 149ccf988b6SMauro Carvalho Chehabioctl I2C_SLAVE before you try to access the device. 150ccf988b6SMauro Carvalho Chehab 151*9d55e7b0SWolfram SangYou can do SMBus level transactions (see documentation file smbus-protocol.rst 152ccf988b6SMauro Carvalho Chehabfor details) through the following functions:: 153ccf988b6SMauro Carvalho Chehab 154ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_write_quick(int file, __u8 value); 155ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_read_byte(int file); 156ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_write_byte(int file, __u8 value); 157ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_read_byte_data(int file, __u8 command); 158ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value); 159ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_read_word_data(int file, __u8 command); 160ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value); 161ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value); 162cee807cfSWolfram Sang __s32 i2c_smbus_block_process_call(int file, __u8 command, __u8 length, 163cee807cfSWolfram Sang __u8 *values); 164ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); 165ccf988b6SMauro Carvalho Chehab __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, 166ccf988b6SMauro Carvalho Chehab __u8 *values); 167ccf988b6SMauro Carvalho Chehab 168ccf988b6SMauro Carvalho ChehabAll these transactions return -1 on failure; you can read errno to see 169ccf988b6SMauro Carvalho Chehabwhat happened. The 'write' transactions return 0 on success; the 170ccf988b6SMauro Carvalho Chehab'read' transactions return the read value, except for read_block, which 171ccf988b6SMauro Carvalho Chehabreturns the number of values read. The block buffers need not be longer 172ccf988b6SMauro Carvalho Chehabthan 32 bytes. 173ccf988b6SMauro Carvalho Chehab 174ccf988b6SMauro Carvalho ChehabThe above functions are made available by linking against the libi2c library, 175ccf988b6SMauro Carvalho Chehabwhich is provided by the i2c-tools project. See: 176ccf988b6SMauro Carvalho Chehabhttps://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/. 177ccf988b6SMauro Carvalho Chehab 178ccf988b6SMauro Carvalho Chehab 179ccf988b6SMauro Carvalho ChehabImplementation details 180ccf988b6SMauro Carvalho Chehab====================== 181ccf988b6SMauro Carvalho Chehab 182ccf988b6SMauro Carvalho ChehabFor the interested, here's the code flow which happens inside the kernel 183ccf988b6SMauro Carvalho Chehabwhen you use the /dev interface to I2C: 184ccf988b6SMauro Carvalho Chehab 185ccf988b6SMauro Carvalho Chehab1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in 186ccf988b6SMauro Carvalho Chehab section "C example" above. 187ccf988b6SMauro Carvalho Chehab 188ccf988b6SMauro Carvalho Chehab2) These open() and ioctl() calls are handled by the i2c-dev kernel 189ccf988b6SMauro Carvalho Chehab driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), 190ccf988b6SMauro Carvalho Chehab respectively. You can think of i2c-dev as a generic I2C chip driver 191ccf988b6SMauro Carvalho Chehab that can be programmed from user-space. 192ccf988b6SMauro Carvalho Chehab 193ccf988b6SMauro Carvalho Chehab3) Some ioctl() calls are for administrative tasks and are handled by 194ccf988b6SMauro Carvalho Chehab i2c-dev directly. Examples include I2C_SLAVE (set the address of the 195ccf988b6SMauro Carvalho Chehab device you want to access) and I2C_PEC (enable or disable SMBus error 196ccf988b6SMauro Carvalho Chehab checking on future transactions.) 197ccf988b6SMauro Carvalho Chehab 198ccf988b6SMauro Carvalho Chehab4) Other ioctl() calls are converted to in-kernel function calls by 199ccf988b6SMauro Carvalho Chehab i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter 200ccf988b6SMauro Carvalho Chehab functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which 201ccf988b6SMauro Carvalho Chehab performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). 202ccf988b6SMauro Carvalho Chehab 203ccf988b6SMauro Carvalho Chehab The i2c-dev driver is responsible for checking all the parameters that 204ccf988b6SMauro Carvalho Chehab come from user-space for validity. After this point, there is no 205ccf988b6SMauro Carvalho Chehab difference between these calls that came from user-space through i2c-dev 206ccf988b6SMauro Carvalho Chehab and calls that would have been performed by kernel I2C chip drivers 207ccf988b6SMauro Carvalho Chehab directly. This means that I2C bus drivers don't need to implement 208ccf988b6SMauro Carvalho Chehab anything special to support access from user-space. 209ccf988b6SMauro Carvalho Chehab 210ccf988b6SMauro Carvalho Chehab5) These i2c.h functions are wrappers to the actual implementation of 211ccf988b6SMauro Carvalho Chehab your I2C bus driver. Each adapter must declare callback functions 212ccf988b6SMauro Carvalho Chehab implementing these standard calls. i2c.h:i2c_get_functionality() calls 213ccf988b6SMauro Carvalho Chehab i2c_adapter.algo->functionality(), while 214ccf988b6SMauro Carvalho Chehab i2c-core-smbus.c:i2c_smbus_xfer() calls either 215ccf988b6SMauro Carvalho Chehab adapter.algo->smbus_xfer() if it is implemented, or if not, 216ccf988b6SMauro Carvalho Chehab i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls 217ccf988b6SMauro Carvalho Chehab i2c_adapter.algo->master_xfer(). 218ccf988b6SMauro Carvalho Chehab 219ccf988b6SMauro Carvalho ChehabAfter your I2C bus driver has processed these requests, execution runs 220ccf988b6SMauro Carvalho Chehabup the call chain, with almost no processing done, except by i2c-dev to 221ccf988b6SMauro Carvalho Chehabpackage the returned data, if any, in suitable format for the ioctl. 222