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