Commit 2d13969e authored by Johan Hovold's avatar Johan Hovold Committed by Greg Kroah-Hartman
Browse files

serdev: document the write functions using kernel-doc



Document the asynchronous serdev_device_write_buf() and synchronous
serdev_device_write() functions using kernel-doc.

Specifically, mention that writing data only means that data has been
buffered by the controller, and that the synchronous helper depends on
serdev_device_write_wakeup() being called in the driver write_wakeup()
callback.

Signed-off-by: default avatarJohan Hovold <johan@kernel.org>
Reviewed-by: default avatarRob Herring <robh@kernel.org>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 70d18804
Loading
Loading
Loading
Loading
+37 −0
Original line number Diff line number Diff line
@@ -217,6 +217,21 @@ void serdev_device_write_wakeup(struct serdev_device *serdev)
}
EXPORT_SYMBOL_GPL(serdev_device_write_wakeup);

/**
 * serdev_device_write_buf() - write data asynchronously
 * @serdev:	serdev device
 * @buf:	data to be written
 * @count:	number of bytes to write
 *
 * Write data to the device asynchronously.
 *
 * Note that any accepted data has only been buffered by the controller; use
 * serdev_device_wait_until_sent() to make sure the controller write buffer
 * has actually been emptied.
 *
 * Return: The number of bytes written (less than count if not enough room in
 * the write buffer), or a negative errno on errors.
 */
int serdev_device_write_buf(struct serdev_device *serdev,
			    const unsigned char *buf, size_t count)
{
@@ -229,6 +244,28 @@ int serdev_device_write_buf(struct serdev_device *serdev,
}
EXPORT_SYMBOL_GPL(serdev_device_write_buf);

/**
 * serdev_device_write() - write data synchronously
 * @serdev:	serdev device
 * @buf:	data to be written
 * @count:	number of bytes to write
 * @timeout:	timeout in jiffies, or 0 to wait indefinitely
 *
 * Write data to the device synchronously by repeatedly calling
 * serdev_device_write() until the controller has accepted all data (unless
 * interrupted by a timeout or a signal).
 *
 * Note that any accepted data has only been buffered by the controller; use
 * serdev_device_wait_until_sent() to make sure the controller write buffer
 * has actually been emptied.
 *
 * Note that this function depends on serdev_device_write_wakeup() being
 * called in the serdev driver write_wakeup() callback.
 *
 * Return: The number of bytes written (less than count if interrupted),
 * -ETIMEDOUT or -ERESTARTSYS if interrupted before any bytes were written, or
 * a negative errno on errors.
 */
int serdev_device_write(struct serdev_device *serdev,
			const unsigned char *buf, size_t count,
			long timeout)