1*ccf988b6SMauro Carvalho Chehab======================= 2*ccf988b6SMauro Carvalho ChehabI2C/SMBus Functionality 3*ccf988b6SMauro Carvalho Chehab======================= 4*ccf988b6SMauro Carvalho Chehab 5*ccf988b6SMauro Carvalho ChehabINTRODUCTION 6*ccf988b6SMauro Carvalho Chehab------------ 7*ccf988b6SMauro Carvalho Chehab 8*ccf988b6SMauro Carvalho ChehabBecause not every I2C or SMBus adapter implements everything in the 9*ccf988b6SMauro Carvalho ChehabI2C specifications, a client can not trust that everything it needs 10*ccf988b6SMauro Carvalho Chehabis implemented when it is given the option to attach to an adapter: 11*ccf988b6SMauro Carvalho Chehabthe client needs some way to check whether an adapter has the needed 12*ccf988b6SMauro Carvalho Chehabfunctionality. 13*ccf988b6SMauro Carvalho Chehab 14*ccf988b6SMauro Carvalho Chehab 15*ccf988b6SMauro Carvalho ChehabFUNCTIONALITY CONSTANTS 16*ccf988b6SMauro Carvalho Chehab----------------------- 17*ccf988b6SMauro Carvalho Chehab 18*ccf988b6SMauro Carvalho ChehabFor the most up-to-date list of functionality constants, please check 19*ccf988b6SMauro Carvalho Chehab<uapi/linux/i2c.h>! 20*ccf988b6SMauro Carvalho Chehab 21*ccf988b6SMauro Carvalho Chehab =============================== ============================================== 22*ccf988b6SMauro Carvalho Chehab I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus 23*ccf988b6SMauro Carvalho Chehab adapters typically can not do these) 24*ccf988b6SMauro Carvalho Chehab I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions 25*ccf988b6SMauro Carvalho Chehab I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_IGNORE_NAK, 26*ccf988b6SMauro Carvalho Chehab I2C_M_REV_DIR_ADDR and I2C_M_NO_RD_ACK 27*ccf988b6SMauro Carvalho Chehab flags (which modify the I2C protocol!) 28*ccf988b6SMauro Carvalho Chehab I2C_FUNC_NOSTART Can skip repeated start sequence 29*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_QUICK Handles the SMBus write_quick command 30*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_READ_BYTE Handles the SMBus read_byte command 31*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_WRITE_BYTE Handles the SMBus write_byte command 32*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_READ_BYTE_DATA Handles the SMBus read_byte_data command 33*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_WRITE_BYTE_DATA Handles the SMBus write_byte_data command 34*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_READ_WORD_DATA Handles the SMBus read_word_data command 35*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_WRITE_WORD_DATA Handles the SMBus write_byte_data command 36*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_PROC_CALL Handles the SMBus process_call command 37*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_READ_BLOCK_DATA Handles the SMBus read_block_data command 38*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command 39*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command 40*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command 41*ccf988b6SMauro Carvalho Chehab =============================== ============================================== 42*ccf988b6SMauro Carvalho Chehab 43*ccf988b6SMauro Carvalho ChehabA few combinations of the above flags are also defined for your convenience: 44*ccf988b6SMauro Carvalho Chehab 45*ccf988b6SMauro Carvalho Chehab ========================= ====================================== 46*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte 47*ccf988b6SMauro Carvalho Chehab and write_byte commands 48*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data 49*ccf988b6SMauro Carvalho Chehab and write_byte_data commands 50*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_WORD_DATA Handles the SMBus read_word_data 51*ccf988b6SMauro Carvalho Chehab and write_word_data commands 52*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_BLOCK_DATA Handles the SMBus read_block_data 53*ccf988b6SMauro Carvalho Chehab and write_block_data commands 54*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_I2C_BLOCK Handles the SMBus read_i2c_block_data 55*ccf988b6SMauro Carvalho Chehab and write_i2c_block_data commands 56*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be 57*ccf988b6SMauro Carvalho Chehab emulated by a real I2C adapter (using 58*ccf988b6SMauro Carvalho Chehab the transparent emulation layer) 59*ccf988b6SMauro Carvalho Chehab ========================= ====================================== 60*ccf988b6SMauro Carvalho Chehab 61*ccf988b6SMauro Carvalho ChehabIn kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as 62*ccf988b6SMauro Carvalho Chehabpart of I2C_FUNC_PROTOCOL_MANGLING. 63*ccf988b6SMauro Carvalho Chehab 64*ccf988b6SMauro Carvalho Chehab 65*ccf988b6SMauro Carvalho ChehabADAPTER IMPLEMENTATION 66*ccf988b6SMauro Carvalho Chehab---------------------- 67*ccf988b6SMauro Carvalho Chehab 68*ccf988b6SMauro Carvalho ChehabWhen you write a new adapter driver, you will have to implement a 69*ccf988b6SMauro Carvalho Chehabfunction callback ``functionality``. Typical implementations are given 70*ccf988b6SMauro Carvalho Chehabbelow. 71*ccf988b6SMauro Carvalho Chehab 72*ccf988b6SMauro Carvalho ChehabA typical SMBus-only adapter would list all the SMBus transactions it 73*ccf988b6SMauro Carvalho Chehabsupports. This example comes from the i2c-piix4 driver:: 74*ccf988b6SMauro Carvalho Chehab 75*ccf988b6SMauro Carvalho Chehab static u32 piix4_func(struct i2c_adapter *adapter) 76*ccf988b6SMauro Carvalho Chehab { 77*ccf988b6SMauro Carvalho Chehab return I2C_FUNC_SMBUS_QUICK | I2C_FUNC_SMBUS_BYTE | 78*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA | 79*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_BLOCK_DATA; 80*ccf988b6SMauro Carvalho Chehab } 81*ccf988b6SMauro Carvalho Chehab 82*ccf988b6SMauro Carvalho ChehabA typical full-I2C adapter would use the following (from the i2c-pxa 83*ccf988b6SMauro Carvalho Chehabdriver):: 84*ccf988b6SMauro Carvalho Chehab 85*ccf988b6SMauro Carvalho Chehab static u32 i2c_pxa_functionality(struct i2c_adapter *adap) 86*ccf988b6SMauro Carvalho Chehab { 87*ccf988b6SMauro Carvalho Chehab return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL; 88*ccf988b6SMauro Carvalho Chehab } 89*ccf988b6SMauro Carvalho Chehab 90*ccf988b6SMauro Carvalho ChehabI2C_FUNC_SMBUS_EMUL includes all the SMBus transactions (with the 91*ccf988b6SMauro Carvalho Chehabaddition of I2C block transactions) which i2c-core can emulate using 92*ccf988b6SMauro Carvalho ChehabI2C_FUNC_I2C without any help from the adapter driver. The idea is 93*ccf988b6SMauro Carvalho Chehabto let the client drivers check for the support of SMBus functions 94*ccf988b6SMauro Carvalho Chehabwithout having to care whether the said functions are implemented in 95*ccf988b6SMauro Carvalho Chehabhardware by the adapter, or emulated in software by i2c-core on top 96*ccf988b6SMauro Carvalho Chehabof an I2C adapter. 97*ccf988b6SMauro Carvalho Chehab 98*ccf988b6SMauro Carvalho Chehab 99*ccf988b6SMauro Carvalho ChehabCLIENT CHECKING 100*ccf988b6SMauro Carvalho Chehab--------------- 101*ccf988b6SMauro Carvalho Chehab 102*ccf988b6SMauro Carvalho ChehabBefore a client tries to attach to an adapter, or even do tests to check 103*ccf988b6SMauro Carvalho Chehabwhether one of the devices it supports is present on an adapter, it should 104*ccf988b6SMauro Carvalho Chehabcheck whether the needed functionality is present. The typical way to do 105*ccf988b6SMauro Carvalho Chehabthis is (from the lm75 driver):: 106*ccf988b6SMauro Carvalho Chehab 107*ccf988b6SMauro Carvalho Chehab static int lm75_detect(...) 108*ccf988b6SMauro Carvalho Chehab { 109*ccf988b6SMauro Carvalho Chehab (...) 110*ccf988b6SMauro Carvalho Chehab if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA | 111*ccf988b6SMauro Carvalho Chehab I2C_FUNC_SMBUS_WORD_DATA)) 112*ccf988b6SMauro Carvalho Chehab goto exit; 113*ccf988b6SMauro Carvalho Chehab (...) 114*ccf988b6SMauro Carvalho Chehab } 115*ccf988b6SMauro Carvalho Chehab 116*ccf988b6SMauro Carvalho ChehabHere, the lm75 driver checks if the adapter can do both SMBus byte data 117*ccf988b6SMauro Carvalho Chehaband SMBus word data transactions. If not, then the driver won't work on 118*ccf988b6SMauro Carvalho Chehabthis adapter and there's no point in going on. If the check above is 119*ccf988b6SMauro Carvalho Chehabsuccessful, then the driver knows that it can call the following 120*ccf988b6SMauro Carvalho Chehabfunctions: i2c_smbus_read_byte_data(), i2c_smbus_write_byte_data(), 121*ccf988b6SMauro Carvalho Chehabi2c_smbus_read_word_data() and i2c_smbus_write_word_data(). As a rule of 122*ccf988b6SMauro Carvalho Chehabthumb, the functionality constants you test for with 123*ccf988b6SMauro Carvalho Chehabi2c_check_functionality() should match exactly the i2c_smbus_* functions 124*ccf988b6SMauro Carvalho Chehabwhich you driver is calling. 125*ccf988b6SMauro Carvalho Chehab 126*ccf988b6SMauro Carvalho ChehabNote that the check above doesn't tell whether the functionalities are 127*ccf988b6SMauro Carvalho Chehabimplemented in hardware by the underlying adapter or emulated in 128*ccf988b6SMauro Carvalho Chehabsoftware by i2c-core. Client drivers don't have to care about this, as 129*ccf988b6SMauro Carvalho Chehabi2c-core will transparently implement SMBus transactions on top of I2C 130*ccf988b6SMauro Carvalho Chehabadapters. 131*ccf988b6SMauro Carvalho Chehab 132*ccf988b6SMauro Carvalho Chehab 133*ccf988b6SMauro Carvalho ChehabCHECKING THROUGH /DEV 134*ccf988b6SMauro Carvalho Chehab--------------------- 135*ccf988b6SMauro Carvalho Chehab 136*ccf988b6SMauro Carvalho ChehabIf you try to access an adapter from a userspace program, you will have 137*ccf988b6SMauro Carvalho Chehabto use the /dev interface. You will still have to check whether the 138*ccf988b6SMauro Carvalho Chehabfunctionality you need is supported, of course. This is done using 139*ccf988b6SMauro Carvalho Chehabthe I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is 140*ccf988b6SMauro Carvalho Chehabbelow:: 141*ccf988b6SMauro Carvalho Chehab 142*ccf988b6SMauro Carvalho Chehab int file; 143*ccf988b6SMauro Carvalho Chehab if (file = open("/dev/i2c-0", O_RDWR) < 0) { 144*ccf988b6SMauro Carvalho Chehab /* Some kind of error handling */ 145*ccf988b6SMauro Carvalho Chehab exit(1); 146*ccf988b6SMauro Carvalho Chehab } 147*ccf988b6SMauro Carvalho Chehab if (ioctl(file, I2C_FUNCS, &funcs) < 0) { 148*ccf988b6SMauro Carvalho Chehab /* Some kind of error handling */ 149*ccf988b6SMauro Carvalho Chehab exit(1); 150*ccf988b6SMauro Carvalho Chehab } 151*ccf988b6SMauro Carvalho Chehab if (!(funcs & I2C_FUNC_SMBUS_QUICK)) { 152*ccf988b6SMauro Carvalho Chehab /* Oops, the needed functionality (SMBus write_quick function) is 153*ccf988b6SMauro Carvalho Chehab not available! */ 154*ccf988b6SMauro Carvalho Chehab exit(1); 155*ccf988b6SMauro Carvalho Chehab } 156*ccf988b6SMauro Carvalho Chehab /* Now it is safe to use the SMBus write_quick command */ 157