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