Change-Id: I4ef1e31c326dbb4f741bf65d9212ff10fc3c98c3
---
docs/specs/index.rst | 1 +
docs/specs/remote-i2c.rst | 51 +++++++++++++++++++++++++++++++++++++++
2 files changed, 52 insertions(+)
create mode 100644 docs/specs/remote-i2c.rst
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index b7b08ea30d..ac496fb8b8 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -13,3 +13,4 @@ guest hardware that is specific to QEMU.
acpi_hw_reduced_hotplug
tpm
acpi_hest_ghes
+ remote-i2c
diff --git a/docs/specs/remote-i2c.rst b/docs/specs/remote-i2c.rst
new file mode 100644
index 0000000000..7f3b1e46bb
--- /dev/null
+++ b/docs/specs/remote-i2c.rst
@@ -0,0 +1,51 @@
+=================
+Remote I2C Device
+=================
+
+The remote I2C device is connected directly to the I2C controller inside QEMU,
+and the external I2C device is outside of QEMU. The communication between the
+external and remote I2C devices is done through the character device provided
+by QEMU and follows the remote I2C protocol.
+
+Remote I2C Protocol
+===================
+The remote I2C device implements three functions of the struct I2CSlaveClass:
+
+* event
+* recv
+* send
+
+Exactly one byte is written or read from the character device at a time,
+so these functions may read/write to the character device multiple times.
+Each byte may be a command or a data byte. The command are outlined
+in enum RemoteI2CCommand. The protocol describes the expected behavior
+of the external I2C device in response to the the commands.
+
+event
+=====
+A subset of the RemoteI2CCommand corresponds exactly to the enum i2c_event.
+They are:
+
+* REMOTE_I2C_START_RECV
+* REMOTE_I2C_START_SEND
+* REMOTE_I2C_FINISH
+* REMOTE_I2C_NACK
+
+The event function of remote I2C writes the command to the external I2C device.
+The external device should call its event function to process the command as
+an event and write back the return value to remote I2C. This value is then
+returned by the event function of remote I2C.
+
+recv
+====
+The recv function of remote I2C writes the RemoteI2CCommand REMOTE_I2C_RECV to
+the external I2C device. The external device should call its recv function
+and write back the return value to remote I2C. This value is then returned by
+the recv function of remote I2C.
+
+send
+====
+The send function of remote I2C writes the RemoteI2CCommand REMOTE_I2C_SEND
+followed by the data to the external I2C device. The external device should
+call its send function to process the data and write the return value back to
+remote I2C. This value is then returned by the send function of remote I2C.
--
2.32.0.605.g8dce9f2422-goog
