hw/ssi: Document ssi_transfer() method

A SPI transaction consists of shifting bit in sync with the CLK
line, writing on the MOSI (output) line / and reading MISO (input)
line.

Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Gustavo Romero <gustavo.romero@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

1 files changed, 14 insertions, 0 deletions

diff --git a/include/hw/ssi/ssi.h b/include/hw/ssi/ssi.h
index 3cdcbd5..2ad8033 100644
--- a/include/hw/ssi/ssi.h
+++ b/include/hw/ssi/ssi.h
@@ -38,6 +38,7 @@ struct SSIPeripheralClass {
 
     /* if you have standard or no CS behaviour, just override transfer.
      * This is called when the device cs is active (true by default).
+     * See ssi_transfer().
      */
     uint32_t (*transfer)(SSIPeripheral *dev, uint32_t val);
     /* called when the CS line changes. Optional, devices only need to implement
@@ -52,6 +53,7 @@ struct SSIPeripheralClass {
      * of the CS behaviour at the device level. transfer, set_cs, and
      * cs_polarity are unused if this is overwritten. Transfer_raw will
      * always be called for the device for every txrx access to the parent bus
+     * See ssi_transfer().
      */
     uint32_t (*transfer_raw)(SSIPeripheral *dev, uint32_t val);
 };
@@ -110,6 +112,18 @@ bool ssi_realize_and_unref(DeviceState *dev, SSIBus *bus, Error **errp);
 /* Master interface.  */
 SSIBus *ssi_create_bus(DeviceState *parent, const char *name);
 
+/**
+ * Transfer a word on a SSI bus
+ * @bus: SSI bus
+ * @val: word to transmit
+ *
+ * At the same time, read a word and write the @val one on the SSI bus.
+ *
+ * SSI words might vary between 8 and 32 bits. The same number of bits
+ * written is received.
+ *
+ * Return: word value received
+ */
 uint32_t ssi_transfer(SSIBus *bus, uint32_t val);
 
 DeviceState *ssi_get_cs(SSIBus *bus, uint8_t cs_index);