[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,39 @@
+# OpenTitan I2C Transport
+
+The `ot-i2c-transport` device provides a way to carry out 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 OpenTitan Earlgrey I2C buses: `ot-i2c0`, `ot-i2c1`, or `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 issuing commands is as follows:
+
+* A write command begins with `W`, followed by an address byte to select the target device. All subsequent bytes are payload bytes to be sent to the device.
+
+* A read command begins with `R`, followed by an address byte to select the target device. A byte is read and written back for every subsequent `B` byte.
+
+* All bytes values are encoded as a pair of case-insensitive ASCII hex digits. For example, decimal 161 is encoded as either `A1` or `a1`.
+
+* End of a command is indicated with an `S`, this ends the transaction.
+
+* For both commands, the address byte chosen will be echoed back if a device with that address is found, otherwise `!!` will be sent.
+
+* For write commands, a written byte will be echoed back on ACK, otherwise `!!` will be sent back on NACK.
+
+* Spaces and newlines in a sent command may appear anywhere except between the pair of hex digits making up a byte, and are ignored. Unexpected characters anywhere in a command will cause the current command to end and command parser restarted.
+
+### Examples
+
+Writing bytes hex AB, hex CD, hex EF, to a device with address hex 51 is done with ```W 51 ab cd ef S```, with expected output `51abcdef` if the device exists and acknowledged all bytes.
+
+Reading 4 bytes from the device with address hex 51 is done with ```R 51 B B B B S```. This will output the address byte `51` if the device exists, followed by 4 data bytes - for example `aabbccdd`.