[ot] docs: opentitan: document I2C transport in i2c_transport.md

Signed-off-by: Alice Ziuziakowska <[email protected]>

Author: ziuziakowska

docs/opentitan/i2c_transport.md

@@ -0,0 +1,68 @@
+# OpenTitan I2C Transport
+
+The `ot-i2c-transport` device provides a way to execute I2C transactions with QEMU I2C bus devices
+through an externally driven socket `chardev` interface.
+
+The device can issue read or write transactions with devices and is intended to be used to drive
+the Opentitan I2C device Target mode functionality through OpenTitanTool, but the protocol is
+simple enough that it can be used manually using `netcat` to type out issued commands.
+
+## Configuration
+
+A socket and transport device can be created in QEMU with the following arguments:
+
+`-chardev socket,id=i2ctp,file=<name>,server=on,wait=off`
+`-device ot-i2c-transport,bus=<bus>,chardev=i2ctp`
+
+Where `bus` is any of the system's I2C buses. On earlgrey, these are `ot-i2c0`, `ot-i2c1`,
+and `ot-i2c2`.
+
+## Protocol
+
+- There are no timing restrictions on the protocol, and the I2C bus is held while a command is
+active. Received command bytes are processed immediately by the QEMU I2C subsystem, therefore it is
+recommended to buffer commands to the OpenTitan I2C target device to allow OT software to fill its
+FIFO with response data. Readiness of response should be indicated via another mechanism or an
+expected value can be attempted to be read after a timeout. There is no requirement to do this
+for other devices on the QEMU I2C bus.
+
+The protocol for executing transactions is as follows:
+
+* All bytes values are encoded as a pair of case-insensitive ASCII hex digits. For example, decimal
+value 161 is encoded as `A1` or `a1`.
+
+* Whitespace sent may appear anywhere except between the pair of hex digits making up a byte, and
+is ignored. Unexpected characters will cause the current transaction to end and the parser to enter
+an error state.
+
+* A transaction begins with an address byte to select the target device.
+
+* This is followed by `R` or `W` to indicate a read or write transaction. After this point a
+transaction is active. If the transaction is started successfully, the address byte provided will
+be sent back, otherwise `!!` will be sent on failure.
+
+* During a read transaction, a `B` byte can be written to read a byte from the device.
+
+* During a write transaction, written bytes are sent to the device. These will be written back on
+success, or `!!` will be sent back on NACK.
+
+* During a transaction, the direction may be changed by writing another `R` or `W` to change the
+transaction direction without releasing the bus (a 'repeated start' condition). This will also send
+the original address byte on success or `!!` on failure.
+
+* End of a transaction is indicated with an `S`. A transaction should be ended immediately if it
+failed to start.
+
+### Examples
+
+Writing bytes hex AB, hex CD, hex EF, to a device with address hex 51 is done with
+```51 W AB CD EF S```. The expected output is the address byte `51` if the transaction started
+successfully, followed by `ABCDEF` if the device acknowledged all bytes.
+
+Reading 4 bytes from the device with address hex 51 is done with ```51 R B B B B S```. The
+expected output is address byte `51` if the transaction started successfully, followed by the 4 read
+data bytes - for example `AABBCCDD`.
+
+To perform both the write and read within a single transaction, this can be done with
+```51 W AB CD EF R B B B B S```. On success this will return `51ABCDEF51AABBCCDD`, using the
+example values above.