[PATCH] spi: Clarify (a)synchronous transfer_one()

[PATCH] spi: Clarify (a)synchronous transfer_one()

[Geert Uytterhoeven]

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(-)

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
-- 
1.7.9.5

Re: [PATCH] spi: Clarify (a)synchronous transfer_one()

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 987 bytes --]

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.

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]