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