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