blob: df0febfe64104f219634eaaee21174b6d7d74ffd [file] [log] [blame]
Luca Ceresolif6fcefa2020-01-29 16:19:51 +01001================
2The I2C Protocol
3================
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -03004
Luca Ceresoli9bbebdf72022-08-08 16:17:00 +02005This document is an overview of the basic I2C transactions and the kernel
6APIs to perform them.
Linus Torvalds1da177e2005-04-16 15:20:36 -07007
8Key to symbols
9==============
10
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -030011=============== =============================================================
Luca Ceresoli02622c82020-01-29 16:19:34 +010012S Start condition
13P Stop condition
14Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0.
Luca Ceresolidb0d7422020-01-29 16:19:35 +010015A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) bit
Luca Ceresoli24d129d2022-08-08 16:17:01 +020016Addr (7 bits) I2C 7 bit address. Note that this can be expanded to
Linus Torvalds1da177e2005-04-16 15:20:36 -070017 get a 10 bit I2C address.
Luca Ceresoli0721cee2022-08-08 16:17:02 +020018Data (8 bits) A plain data byte.
Linus Torvalds1da177e2005-04-16 15:20:36 -070019
Luca Ceresoli02622c82020-01-29 16:19:34 +010020[..] Data sent by I2C device, as opposed to data sent by the
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -030021 host adapter.
22=============== =============================================================
Linus Torvalds1da177e2005-04-16 15:20:36 -070023
24
25Simple send transaction
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -030026=======================
Linus Torvalds1da177e2005-04-16 15:20:36 -070027
Luca Ceresolica5dbb02020-01-29 16:19:52 +010028Implemented by i2c_master_send()::
Linus Torvalds1da177e2005-04-16 15:20:36 -070029
30 S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
31
32
33Simple receive transaction
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -030034==========================
Linus Torvalds1da177e2005-04-16 15:20:36 -070035
Luca Ceresolica5dbb02020-01-29 16:19:52 +010036Implemented by i2c_master_recv()::
Linus Torvalds1da177e2005-04-16 15:20:36 -070037
38 S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
39
40
41Combined transactions
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -030042=====================
Linus Torvalds1da177e2005-04-16 15:20:36 -070043
Luca Ceresolica5dbb02020-01-29 16:19:52 +010044Implemented by i2c_transfer().
Linus Torvalds1da177e2005-04-16 15:20:36 -070045
Luca Ceresolif9547312020-01-29 16:19:33 +010046They are just like the above transactions, but instead of a stop
47condition P a start condition S is sent and the transaction continues.
48An example of a byte read, followed by a byte write::
Linus Torvalds1da177e2005-04-16 15:20:36 -070049
50 S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
51
52
53Modified transactions
54=====================
55
Wolfram Sang9f02fba2014-04-06 13:37:38 +020056The following modifications to the I2C protocol can also be generated by
Luca Ceresoli2f07c052020-01-29 16:19:29 +010057setting these flags for I2C messages. With the exception of I2C_M_NOSTART, they
Wolfram Sang9f02fba2014-04-06 13:37:38 +020058are usually only needed to work around device issues:
Linus Torvalds1da177e2005-04-16 15:20:36 -070059
Wolfram Sang9f02fba2014-04-06 13:37:38 +020060I2C_M_IGNORE_NAK:
61 Normally message is interrupted immediately if there is [NA] from the
62 client. Setting this flag treats any [NA] as [A], and all of
63 message is sent.
64 These messages may still fail to SCL lo->hi timeout.
65
66I2C_M_NO_RD_ACK:
67 In a read message, master A/NA bit is skipped.
68
69I2C_M_NOSTART:
Linus Torvalds1da177e2005-04-16 15:20:36 -070070 In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
71 point. For example, setting I2C_M_NOSTART on the second partial message
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -030072 generates something like::
73
Linus Torvalds1da177e2005-04-16 15:20:36 -070074 S Addr Rd [A] [Data] NA Data [A] P
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -030075
Linus Torvalds1da177e2005-04-16 15:20:36 -070076 If you set the I2C_M_NOSTART variable for the first partial message,
Luca Ceresolif9547312020-01-29 16:19:33 +010077 we do not generate Addr, but we do generate the start condition S.
78 This will probably confuse all other clients on your bus, so don't
79 try this.
Linus Torvalds1da177e2005-04-16 15:20:36 -070080
Mark Brown14674e72012-05-30 10:55:34 +020081 This is often used to gather transmits from multiple data buffers in
82 system memory into something that appears as a single transfer to the
83 I2C device but may also be used between direction changes by some
84 rare devices.
85
Wolfram Sang9f02fba2014-04-06 13:37:38 +020086I2C_M_REV_DIR_ADDR:
Linus Torvalds1da177e2005-04-16 15:20:36 -070087 This toggles the Rd/Wr flag. That is, if you want to do a write, but
88 need to emit an Rd instead of a Wr, or vice versa, you set this
Mauro Carvalho Chehabccf988b2019-07-26 09:51:16 -030089 flag. For example::
90
Linus Torvalds1da177e2005-04-16 15:20:36 -070091 S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
92
Wolfram Sang9f02fba2014-04-06 13:37:38 +020093I2C_M_STOP:
94 Force a stop condition (P) after the message. Some I2C related protocols
95 like SCCB require that. Normally, you really don't want to get interrupted
96 between the messages of one transfer.