summaryrefslogtreecommitdiffstats
path: root/Documentation/i2c/i2c-protocol.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 18:49:45 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 18:49:45 +0000
commit2c3c1048746a4622d8c89a29670120dc8fab93c4 (patch)
tree848558de17fb3008cdf4d861b01ac7781903ce39 /Documentation/i2c/i2c-protocol.rst
parentInitial commit. (diff)
downloadlinux-2c3c1048746a4622d8c89a29670120dc8fab93c4.tar.xz
linux-2c3c1048746a4622d8c89a29670120dc8fab93c4.zip
Adding upstream version 6.1.76.upstream/6.1.76upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--Documentation/i2c/i2c-protocol.rst96
1 files changed, 96 insertions, 0 deletions
diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst
new file mode 100644
index 000000000..df0febfe6
--- /dev/null
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -0,0 +1,96 @@
+================
+The I2C Protocol
+================
+
+This document is an overview of the basic I2C transactions and the kernel
+APIs to perform them.
+
+Key to symbols
+==============
+
+=============== =============================================================
+S Start condition
+P Stop condition
+Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0.
+A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) bit
+Addr (7 bits) I2C 7 bit address. Note that this can be expanded to
+ get a 10 bit I2C address.
+Data (8 bits) A plain data byte.
+
+[..] Data sent by I2C device, as opposed to data sent by the
+ host adapter.
+=============== =============================================================
+
+
+Simple send transaction
+=======================
+
+Implemented by i2c_master_send()::
+
+ S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
+
+
+Simple receive transaction
+==========================
+
+Implemented by i2c_master_recv()::
+
+ S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
+
+
+Combined transactions
+=====================
+
+Implemented by i2c_transfer().
+
+They are just like the above transactions, but instead of a stop
+condition P a start condition S is sent and the transaction continues.
+An example of a byte read, followed by a byte write::
+
+ S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
+
+
+Modified transactions
+=====================
+
+The following modifications to the I2C protocol can also be generated by
+setting these flags for I2C messages. With the exception of I2C_M_NOSTART, they
+are usually only needed to work around device issues:
+
+I2C_M_IGNORE_NAK:
+ Normally message is interrupted immediately if there is [NA] from the
+ client. Setting this flag treats any [NA] as [A], and all of
+ message is sent.
+ These messages may still fail to SCL lo->hi timeout.
+
+I2C_M_NO_RD_ACK:
+ In a read message, master A/NA bit is skipped.
+
+I2C_M_NOSTART:
+ In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
+ point. For example, setting I2C_M_NOSTART on the second partial message
+ generates something like::
+
+ S Addr Rd [A] [Data] NA Data [A] P
+
+ If you set the I2C_M_NOSTART variable for the first partial message,
+ we do not generate Addr, but we do generate the start condition S.
+ This will probably confuse all other clients on your bus, so don't
+ try this.
+
+ This is often used to gather transmits from multiple data buffers in
+ system memory into something that appears as a single transfer to the
+ I2C device but may also be used between direction changes by some
+ rare devices.
+
+I2C_M_REV_DIR_ADDR:
+ This toggles the Rd/Wr flag. That is, if you want to do a write, but
+ need to emit an Rd instead of a Wr, or vice versa, you set this
+ flag. For example::
+
+ S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
+
+I2C_M_STOP:
+ Force a stop condition (P) after the message. Some I2C related protocols
+ like SCCB require that. Normally, you really don't want to get interrupted
+ between the messages of one transfer.