Commit | Line | Data |
---|---|---|
f6fcefa1 LC |
1 | ================== |
2 | The SMBus Protocol | |
3 | ================== | |
1a31a88f | 4 | |
1da177e4 LT |
5 | The following is a summary of the SMBus protocol. It applies to |
6 | all revisions of the protocol (1.0, 1.1, and 2.0). | |
7 | Certain protocol features which are not supported by | |
8 | this package are briefly described at the end of this document. | |
9 | ||
10 | Some adapters understand only the SMBus (System Management Bus) protocol, | |
11 | which is a subset from the I2C protocol. Fortunately, many devices use | |
12 | only the same subset, which makes it possible to put them on an SMBus. | |
1a31a88f | 13 | |
1da177e4 LT |
14 | If you write a driver for some I2C device, please try to use the SMBus |
15 | commands if at all possible (if the device uses only that subset of the | |
16 | I2C protocol). This makes it possible to use the device driver on both | |
17 | SMBus adapters and I2C adapters (the SMBus command set is automatically | |
18 | translated to I2C on I2C adapters, but plain I2C commands can not be | |
19 | handled at all on most pure SMBus adapters). | |
20 | ||
1a31a88f DB |
21 | Below is a list of SMBus protocol operations, and the functions executing |
22 | them. Note that the names used in the SMBus protocol specifications usually | |
23 | don't match these function names. For some of the operations which pass a | |
24 | single data byte, the functions using SMBus protocol operation names execute | |
25 | a different protocol operation entirely. | |
26 | ||
a1681781 JD |
27 | Each transaction type corresponds to a functionality flag. Before calling a |
28 | transaction function, a device driver should always check (just once) for | |
29 | the corresponding functionality flag to ensure that the underlying I2C | |
25edd3a1 MCC |
30 | adapter supports the transaction in question. See |
31 | Documentation/i2c/functionality.rst for the details. | |
a1681781 | 32 | |
1da177e4 LT |
33 | |
34 | Key to symbols | |
35 | ============== | |
36 | ||
ccf988b6 | 37 | =============== ============================================================= |
026c0fe6 | 38 | S Start condition |
bed68f4f MR |
39 | Sr Repeated start condition, used to switch from write to |
40 | read mode. | |
026c0fe6 LC |
41 | P Stop condition |
42 | Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0. | |
9e89d618 | 43 | A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) bit |
24d129d4 | 44 | Addr (7 bits) I2C 7 bit address. Note that this can be expanded to |
1da177e4 | 45 | get a 10 bit I2C address. |
026c0fe6 | 46 | Comm (8 bits) Command byte, a data byte which often selects a register on |
1da177e4 | 47 | the device. |
6c12ec27 LC |
48 | Data (8 bits) A plain data byte. DataLow and DataHigh represent the low and |
49 | high byte of a 16 bit word. | |
026c0fe6 | 50 | Count (8 bits) A data byte containing the length of a block operation. |
1da177e4 | 51 | |
026c0fe6 | 52 | [..] Data sent by I2C device, as opposed to data sent by the host |
ccf988b6 MCC |
53 | adapter. |
54 | =============== ============================================================= | |
1da177e4 LT |
55 | |
56 | ||
67c2e665 JD |
57 | SMBus Quick Command |
58 | =================== | |
1da177e4 | 59 | |
ccf988b6 | 60 | This sends a single bit to the device, at the place of the Rd/Wr bit:: |
1da177e4 | 61 | |
a5765124 | 62 | S Addr Rd/Wr [A] P |
1da177e4 | 63 | |
a1681781 JD |
64 | Functionality flag: I2C_FUNC_SMBUS_QUICK |
65 | ||
1da177e4 | 66 | |
3c13f1fb LC |
67 | SMBus Receive Byte |
68 | ================== | |
69 | ||
70 | Implemented by i2c_smbus_read_byte() | |
1da177e4 LT |
71 | |
72 | This reads a single byte from a device, without specifying a device | |
73 | register. Some devices are so simple that this interface is enough; for | |
74 | others, it is a shorthand if you want to read the same register as in | |
ccf988b6 | 75 | the previous SMBus command:: |
1da177e4 | 76 | |
ccf988b6 | 77 | S Addr Rd [A] [Data] NA P |
1da177e4 | 78 | |
a1681781 JD |
79 | Functionality flag: I2C_FUNC_SMBUS_READ_BYTE |
80 | ||
1da177e4 | 81 | |
3c13f1fb LC |
82 | SMBus Send Byte |
83 | =============== | |
84 | ||
85 | Implemented by i2c_smbus_write_byte() | |
1da177e4 | 86 | |
1a31a88f DB |
87 | This operation is the reverse of Receive Byte: it sends a single byte |
88 | to a device. See Receive Byte for more information. | |
1da177e4 | 89 | |
ccf988b6 MCC |
90 | :: |
91 | ||
92 | S Addr Wr [A] Data [A] P | |
1da177e4 | 93 | |
a1681781 JD |
94 | Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE |
95 | ||
1da177e4 | 96 | |
3c13f1fb LC |
97 | SMBus Read Byte |
98 | =============== | |
99 | ||
100 | Implemented by i2c_smbus_read_byte_data() | |
1da177e4 LT |
101 | |
102 | This reads a single byte from a device, from a designated register. | |
ccf988b6 | 103 | The register is specified through the Comm byte:: |
1da177e4 | 104 | |
bed68f4f | 105 | S Addr Wr [A] Comm [A] Sr Addr Rd [A] [Data] NA P |
1da177e4 | 106 | |
a1681781 JD |
107 | Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA |
108 | ||
1da177e4 | 109 | |
3c13f1fb LC |
110 | SMBus Read Word |
111 | =============== | |
112 | ||
113 | Implemented by i2c_smbus_read_word_data() | |
1da177e4 | 114 | |
1a31a88f | 115 | This operation is very like Read Byte; again, data is read from a |
1da177e4 | 116 | device, from a designated register that is specified through the Comm |
ccf988b6 | 117 | byte. But this time, the data is a complete word (16 bits):: |
1da177e4 | 118 | |
bed68f4f | 119 | S Addr Wr [A] Comm [A] Sr Addr Rd [A] [DataLow] A [DataHigh] NA P |
1da177e4 | 120 | |
a1681781 JD |
121 | Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA |
122 | ||
b36cbb70 | 123 | Note the convenience function i2c_smbus_read_word_swapped() is |
06a67848 JC |
124 | available for reads where the two data bytes are the other way |
125 | around (not SMBus compliant, but very popular.) | |
126 | ||
1da177e4 | 127 | |
3c13f1fb LC |
128 | SMBus Write Byte |
129 | ================ | |
130 | ||
131 | Implemented by i2c_smbus_write_byte_data() | |
1da177e4 LT |
132 | |
133 | This writes a single byte to a device, to a designated register. The | |
134 | register is specified through the Comm byte. This is the opposite of | |
1a31a88f | 135 | the Read Byte operation. |
1da177e4 | 136 | |
ccf988b6 MCC |
137 | :: |
138 | ||
139 | S Addr Wr [A] Comm [A] Data [A] P | |
1da177e4 | 140 | |
a1681781 JD |
141 | Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA |
142 | ||
1da177e4 | 143 | |
3c13f1fb LC |
144 | SMBus Write Word |
145 | ================ | |
146 | ||
147 | Implemented by i2c_smbus_write_word_data() | |
1da177e4 | 148 | |
1a31a88f | 149 | This is the opposite of the Read Word operation. 16 bits |
414a5964 | 150 | of data are written to a device, to the designated register that is |
c7148b05 | 151 | specified through the Comm byte:: |
1da177e4 | 152 | |
ccf988b6 | 153 | S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P |
1da177e4 | 154 | |
a1681781 JD |
155 | Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA |
156 | ||
b36cbb70 | 157 | Note the convenience function i2c_smbus_write_word_swapped() is |
06a67848 JC |
158 | available for writes where the two data bytes are the other way |
159 | around (not SMBus compliant, but very popular.) | |
160 | ||
1da177e4 | 161 | |
3c13f1fb LC |
162 | SMBus Process Call |
163 | ================== | |
1da177e4 LT |
164 | |
165 | This command selects a device register (through the Comm byte), sends | |
ccf988b6 | 166 | 16 bits of data to it, and reads 16 bits of data in return:: |
1da177e4 | 167 | |
ccf988b6 | 168 | S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] |
bed68f4f | 169 | Sr Addr Rd [A] [DataLow] A [DataHigh] NA P |
1da177e4 | 170 | |
a1681781 JD |
171 | Functionality flag: I2C_FUNC_SMBUS_PROC_CALL |
172 | ||
1da177e4 | 173 | |
3c13f1fb LC |
174 | SMBus Block Read |
175 | ================ | |
176 | ||
177 | Implemented by i2c_smbus_read_block_data() | |
1da177e4 | 178 | |
ccf988b6 | 179 | This command reads a block of up to 32 bytes from a device, from a |
1da177e4 LT |
180 | designated register that is specified through the Comm byte. The amount |
181 | of data is specified by the device in the Count byte. | |
182 | ||
ccf988b6 MCC |
183 | :: |
184 | ||
185 | S Addr Wr [A] Comm [A] | |
bed68f4f | 186 | Sr Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P |
1da177e4 | 187 | |
a1681781 JD |
188 | Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA |
189 | ||
1da177e4 | 190 | |
3c13f1fb LC |
191 | SMBus Block Write |
192 | ================= | |
193 | ||
194 | Implemented by i2c_smbus_write_block_data() | |
1da177e4 | 195 | |
ccf988b6 | 196 | The opposite of the Block Read command, this writes up to 32 bytes to |
1da177e4 LT |
197 | a device, to a designated register that is specified through the |
198 | Comm byte. The amount of data is specified in the Count byte. | |
199 | ||
ccf988b6 MCC |
200 | :: |
201 | ||
202 | S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P | |
1da177e4 | 203 | |
a1681781 JD |
204 | Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA |
205 | ||
1da177e4 | 206 | |
1a31a88f DB |
207 | SMBus Block Write - Block Read Process Call |
208 | =========================================== | |
1da177e4 | 209 | |
1a31a88f DB |
210 | SMBus Block Write - Block Read Process Call was introduced in |
211 | Revision 2.0 of the specification. | |
1da177e4 LT |
212 | |
213 | This command selects a device register (through the Comm byte), sends | |
ccf988b6 | 214 | 1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return:: |
1da177e4 | 215 | |
ccf988b6 | 216 | S Addr Wr [A] Comm [A] Count [A] Data [A] ... |
bed68f4f | 217 | Sr Addr Rd [A] [Count] A [Data] ... A P |
1da177e4 | 218 | |
a1681781 JD |
219 | Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL |
220 | ||
1da177e4 LT |
221 | |
222 | SMBus Host Notify | |
223 | ================= | |
224 | ||
225 | This command is sent from a SMBus device acting as a master to the | |
226 | SMBus host acting as a slave. | |
227 | It is the same form as Write Word, with the command code replaced by the | |
228 | alerting device's address. | |
229 | ||
ccf988b6 MCC |
230 | :: |
231 | ||
232 | [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] | |
1da177e4 | 233 | |
e456cd37 | 234 | This is implemented in the following way in the Linux kernel: |
ccf988b6 | 235 | |
4d5538f5 BT |
236 | * I2C bus drivers which support SMBus Host Notify should report |
237 | I2C_FUNC_SMBUS_HOST_NOTIFY. | |
238 | * I2C bus drivers trigger SMBus Host Notify by a call to | |
239 | i2c_handle_smbus_host_notify(). | |
240 | * I2C drivers for devices which can trigger SMBus Host Notify will have | |
38bd4136 | 241 | client->irq assigned to a Host Notify IRQ if no one else specified another. |
4d5538f5 BT |
242 | |
243 | There is currently no way to retrieve the data parameter from the client. | |
e456cd37 | 244 | |
1da177e4 LT |
245 | |
246 | Packet Error Checking (PEC) | |
247 | =========================== | |
1a31a88f | 248 | |
1da177e4 LT |
249 | Packet Error Checking was introduced in Revision 1.1 of the specification. |
250 | ||
1a31a88f DB |
251 | PEC adds a CRC-8 error-checking byte to transfers using it, immediately |
252 | before the terminating STOP. | |
1da177e4 LT |
253 | |
254 | ||
255 | Address Resolution Protocol (ARP) | |
256 | ================================= | |
1a31a88f | 257 | |
1da177e4 LT |
258 | The Address Resolution Protocol was introduced in Revision 2.0 of |
259 | the specification. It is a higher-layer protocol which uses the | |
260 | messages above. | |
261 | ||
262 | ARP adds device enumeration and dynamic address assignment to | |
263 | the protocol. All ARP communications use slave address 0x61 and | |
264 | require PEC checksums. | |
265 | ||
266 | ||
b5527a77 JD |
267 | SMBus Alert |
268 | =========== | |
269 | ||
270 | SMBus Alert was introduced in Revision 1.0 of the specification. | |
271 | ||
272 | The SMBus alert protocol allows several SMBus slave devices to share a | |
273 | single interrupt pin on the SMBus master, while still allowing the master | |
274 | to know which slave triggered the interrupt. | |
275 | ||
276 | This is implemented the following way in the Linux kernel: | |
ccf988b6 | 277 | |
b5527a77 | 278 | * I2C bus drivers which support SMBus alert should call |
ed680522 | 279 | i2c_new_smbus_alert_device() to install SMBus alert support. |
b5527a77 JD |
280 | * I2C drivers for devices which can trigger SMBus alerts should implement |
281 | the optional alert() callback. | |
282 | ||
283 | ||
1da177e4 LT |
284 | I2C Block Transactions |
285 | ====================== | |
1a31a88f | 286 | |
95b83774 LC |
287 | The following I2C block transactions are similar to the SMBus Block Read |
288 | and Write operations, except these do not have a Count byte. They are | |
289 | supported by the SMBus layer and are described here for completeness, but | |
290 | they are *NOT* defined by the SMBus specification. | |
1a31a88f | 291 | |
1da177e4 LT |
292 | I2C block transactions do not limit the number of bytes transferred |
293 | but the SMBus layer places a limit of 32 bytes. | |
294 | ||
295 | ||
3c13f1fb LC |
296 | I2C Block Read |
297 | ============== | |
298 | ||
299 | Implemented by i2c_smbus_read_i2c_block_data() | |
1da177e4 | 300 | |
ccf988b6 MCC |
301 | This command reads a block of bytes from a device, from a |
302 | designated register that is specified through the Comm byte:: | |
1da177e4 | 303 | |
ccf988b6 | 304 | S Addr Wr [A] Comm [A] |
bed68f4f | 305 | Sr Addr Rd [A] [Data] A [Data] A ... A [Data] NA P |
1da177e4 | 306 | |
a1681781 | 307 | Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK |
1da177e4 LT |
308 | |
309 | ||
3c13f1fb LC |
310 | I2C Block Write |
311 | =============== | |
312 | ||
313 | Implemented by i2c_smbus_write_i2c_block_data() | |
1da177e4 | 314 | |
ccf988b6 | 315 | The opposite of the Block Read command, this writes bytes to |
1da177e4 LT |
316 | a device, to a designated register that is specified through the |
317 | Comm byte. Note that command lengths of 0, 2, or more bytes are | |
318 | supported as they are indistinguishable from data. | |
319 | ||
ccf988b6 MCC |
320 | :: |
321 | ||
322 | S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P | |
a1681781 JD |
323 | |
324 | Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK |