diff mbox

spi: Clarify (a)synchronous transfer_one()

Message ID 1389699296-28994-1-git-send-email-geert@linux-m68k.org (mailing list archive)
State Changes Requested
Headers show

Commit Message

Geert Uytterhoeven Jan. 14, 2014, 11:34 a.m. UTC 
From: Geert Uytterhoeven <geert+renesas@linux-m68k.org>

Signed-off-by: Geert Uytterhoeven <geert+renesas@linux-m68k.org>
---
 include/linux/spi/spi.h |   10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

Comments

Mark Brown Jan. 14, 2014, 2:36 p.m. UTC | #1 
On Tue, Jan 14, 2014 at 12:34:56PM +0100, Geert Uytterhoeven wrote:

> + * @transfer_one: transfer a single spi_transfer.
> + *                Synchronous transfer methods must return 0 on success.
> + *                Asynchronous transfer methods must return a strict-positive
> + *                value on successful submission, and must call
> + *                spi_finalize_current_transfer() when the driver is finished
> + *                so the subsystem can issue the next transfer

This is hard to understand, I'd not expect people not comfortable with
English to readily follow what it means.  Things like "strict-positive"
aren't common outside of mathematics and I myself had to think what an
asynchronous transfer_one() meant.  Something along the lines of "return
0 if the trasfer is finished or a positive number if the transfer is in
progress and finalize will be called later" would be more readily
comprehensible.  If you're concerned about positive just specify 1.
diff mbox

Patch

diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index 21a7251d85ee..5319a8510921 100644
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -282,10 +282,12 @@  static inline void spi_unregister_driver(struct spi_driver *sdrv)
  * @prepare_message: set up the controller to transfer a single message,
  *                   for example doing DMA mapping.  Called from threaded
  *                   context.
- * @transfer_one: transfer a single spi_transfer. When the
- *	          driver is finished with this transfer it must call
- *	          spi_finalize_current_transfer() so the subsystem can issue
- *                the next transfer
+ * @transfer_one: transfer a single spi_transfer.
+ *                Synchronous transfer methods must return 0 on success.
+ *                Asynchronous transfer methods must return a strict-positive
+ *                value on successful submission, and must call
+ *                spi_finalize_current_transfer() when the driver is finished
+ *                so the subsystem can issue the next transfer
  * @unprepare_message: undo any work done by prepare_message().
  * @cs_gpios: Array of GPIOs to use as chip select lines; one per CS
  *	number. Any individual value may be -ENOENT for CS lines that