cros_ec: Add documentation for cros_ec driver operations

Add comments to these methods so it is documented in this central place,
not just in each driver.

Signed-off-by: Simon Glass <sjg@chromium.org>

diff --git a/include/cros_ec.h b/include/cros_ec.h
index 338878c3bede81f86e082120f8740880be3ff83e..26e3f3ba0cb015c63692fdeae5f31d7daa0cc424 100644 (file)
--- a/include/cros_ec.h
+++ b/include/cros_ec.h
@@ -234,10 +234,50 @@ int cros_ec_flash_update_rw(struct udevice *dev, const uint8_t  *image,
 struct udevice *board_get_cros_ec_dev(void);
 
 struct dm_cros_ec_ops {
+       /**
+        * check_version() - Check the protocol version being used (optional)
+        *
+        * If provided, this function should check that the EC can be supported
+        * by the driver. If not provided, HELLO messages will be sent to try
+        * to determine the protocol version.
+        *
+        * @dev: Device to check
+        * @return 0 if the protocol is valid, -ve if not supported
+        */
        int (*check_version)(struct udevice *dev);
+
+       /**
+        * command() - Old-style command interface
+        *
+        * This sends a command and receives a response (deprecated, use
+        * packet())
+        *
+        * @dev: Device to use
+        * @cmd: Command to send (only supports 0-0xff)
+        * @cmd_version: Version of command to send (often 0)
+        * @dout: Output data (may be NULL If dout_len=0)
+        * @dout_len: Length of output data excluding 4-byte header
+        * @dinp: On input, set to point to input data, often struct
+        *      cros_ec_dev->din - typically this is left alone but may be
+        *      updated by the driver
+        * @din_len: Maximum length of response
+        * @return number of bytes in response, or -ve on error
+        */
        int (*command)(struct udevice *dev, uint8_t cmd, int cmd_version,
                       const uint8_t *dout, int dout_len,
                       uint8_t **dinp, int din_len);
+
+       /**
+        * packet() - New-style command interface
+        *
+        * This interface is preferred over command(), since it is typically
+        * easier to implement.
+        *
+        * @dev: Device to use
+        * @out_bytes: Number of bytes to send (from struct cros_ec_dev->dout)
+        * @in_bytes: Maximum number of bytes to expect in response
+        * @return number of bytes in response, or -ve on error
+        */
        int (*packet)(struct udevice *dev, int out_bytes, int in_bytes);
 };