Commit | Line | Data |
---|---|---|
ccf988b6 MCC |
1 | ======================= |
2 | I2C/SMBus Functionality | |
3 | ======================= | |
4 | ||
1da177e4 LT |
5 | INTRODUCTION |
6 | ------------ | |
7 | ||
ccf988b6 | 8 | Because not every I2C or SMBus adapter implements everything in the |
1da177e4 LT |
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 | |
ccf988b6 | 12 | functionality. |
1da177e4 LT |
13 | |
14 | ||
15 | FUNCTIONALITY CONSTANTS | |
16 | ----------------------- | |
17 | ||
18 | For the most up-to-date list of functionality constants, please check | |
8421d4fe | 19 | <uapi/linux/i2c.h>! |
1da177e4 | 20 | |
ccf988b6 | 21 | =============================== ============================================== |
1da177e4 LT |
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 | |
d057c96c | 25 | I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_IGNORE_NAK, |
14674e70 MB |
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 | |
1da177e4 LT |
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 | |
ccf988b6 | 41 | =============================== ============================================== |
1da177e4 LT |
42 | |
43 | A few combinations of the above flags are also defined for your convenience: | |
44 | ||
ccf988b6 | 45 | ========================= ====================================== |
1da177e4 LT |
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 | |
6808b002 | 56 | I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be |
1da177e4 LT |
57 | emulated by a real I2C adapter (using |
58 | the transparent emulation layer) | |
ccf988b6 | 59 | ========================= ====================================== |
1da177e4 | 60 | |
14674e70 MB |
61 | In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as |
62 | part of I2C_FUNC_PROTOCOL_MANGLING. | |
63 | ||
1da177e4 | 64 | |
88b28328 JD |
65 | ADAPTER IMPLEMENTATION |
66 | ---------------------- | |
1da177e4 | 67 | |
88b28328 | 68 | When you write a new adapter driver, you will have to implement a |
ccf988b6 | 69 | function callback ``functionality``. Typical implementations are given |
88b28328 | 70 | below. |
1da177e4 | 71 | |
88b28328 | 72 | A typical SMBus-only adapter would list all the SMBus transactions it |
ccf988b6 | 73 | supports. This example comes from the i2c-piix4 driver:: |
88b28328 JD |
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; | |
1da177e4 LT |
80 | } |
81 | ||
88b28328 | 82 | A typical full-I2C adapter would use the following (from the i2c-pxa |
ccf988b6 | 83 | driver):: |
1da177e4 | 84 | |
88b28328 | 85 | static u32 i2c_pxa_functionality(struct i2c_adapter *adap) |
1da177e4 | 86 | { |
88b28328 | 87 | return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL; |
1da177e4 LT |
88 | } |
89 | ||
88b28328 JD |
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. | |
1da177e4 LT |
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 | |
88b28328 | 104 | check whether the needed functionality is present. The typical way to do |
ccf988b6 | 105 | this is (from the lm75 driver):: |
1da177e4 | 106 | |
88b28328 | 107 | static int lm75_detect(...) |
1da177e4 | 108 | { |
88b28328 JD |
109 | (...) |
110 | if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA | | |
111 | I2C_FUNC_SMBUS_WORD_DATA)) | |
112 | goto exit; | |
113 | (...) | |
1da177e4 LT |
114 | } |
115 | ||
88b28328 JD |
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. | |
1da177e4 LT |
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 | |
88b28328 | 139 | the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is |
ccf988b6 | 140 | below:: |
1da177e4 LT |
141 | |
142 | int file; | |
88b28328 | 143 | if (file = open("/dev/i2c-0", O_RDWR) < 0) { |
1da177e4 LT |
144 | /* Some kind of error handling */ |
145 | exit(1); | |
146 | } | |
88b28328 | 147 | if (ioctl(file, I2C_FUNCS, &funcs) < 0) { |
1da177e4 LT |
148 | /* Some kind of error handling */ |
149 | exit(1); | |
150 | } | |
88b28328 | 151 | if (!(funcs & I2C_FUNC_SMBUS_QUICK)) { |
1da177e4 LT |
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 */ |