serdev: document driver callbacks

Amend the driver-callback kerneldoc with calling context and expected
return values.

Note that this is based on the requirements and characteristics of the
tty-port controller implementation which receives data in workqueue
context and whose write_wakeup callback must not sleep.

Also note that while the receive_buf callback returns an integer, the
returned value is still expected to be non-negative (and no greater than
the buffer-size argument).

Signed-off-by: Johan Hovold <johan@kernel.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/include/linux/serdev.h b/include/linux/serdev.h
index 9929063bd45db29ec00f1919cab0b27c0db9fe9b..d7a9713e98832e1d943188dab5f32591ada3b837 100644 (file)
--- a/include/linux/serdev.h
+++ b/include/linux/serdev.h
@@ -27,8 +27,10 @@ struct serdev_device;
 
 /**
  * struct serdev_device_ops - Callback operations for a serdev device
- * @receive_buf:       Function called with data received from device.
- * @write_wakeup:      Function called when ready to transmit more data.
+ * @receive_buf:       Function called with data received from device;
+ *                     returns number of bytes accepted; may sleep.
+ * @write_wakeup:      Function called when ready to transmit more data; must
+ *                     not sleep.
  */
 struct serdev_device_ops {
        int (*receive_buf)(struct serdev_device *, const unsigned char *, size_t);