* [PATCH] spi: Clarify (a)synchronous transfer_one()
@ 2014-01-14 11:34 ` Geert Uytterhoeven
0 siblings, 0 replies; 4+ messages in thread
From: Geert Uytterhoeven @ 2014-01-14 11:34 UTC (permalink / raw)
To: Mark Brown; +Cc: linux-spi, linux-kernel, 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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [PATCH] spi: Clarify (a)synchronous transfer_one()
@ 2014-01-14 11:34 ` Geert Uytterhoeven
0 siblings, 0 replies; 4+ messages in thread
From: Geert Uytterhoeven @ 2014-01-14 11:34 UTC (permalink / raw)
To: Mark Brown
Cc: linux-spi-u79uwXL29TY76Z2rM5mHXA,
linux-kernel-u79uwXL29TY76Z2rM5mHXA, Geert Uytterhoeven
From: Geert Uytterhoeven <geert+renesas-Td1EMuHUCqxL1ZNQvxDV9g@public.gmane.org>
Signed-off-by: Geert Uytterhoeven <geert+renesas-Td1EMuHUCqxL1ZNQvxDV9g@public.gmane.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
--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] spi: Clarify (a)synchronous transfer_one()
@ 2014-01-14 14:36 ` Mark Brown
0 siblings, 0 replies; 4+ messages in thread
From: Mark Brown @ 2014-01-14 14:36 UTC (permalink / raw)
To: Geert Uytterhoeven; +Cc: linux-spi, linux-kernel, Geert Uytterhoeven
[-- 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 --]
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] spi: Clarify (a)synchronous transfer_one()
@ 2014-01-14 14:36 ` Mark Brown
0 siblings, 0 replies; 4+ messages in thread
From: Mark Brown @ 2014-01-14 14:36 UTC (permalink / raw)
To: Geert Uytterhoeven
Cc: linux-spi-u79uwXL29TY76Z2rM5mHXA,
linux-kernel-u79uwXL29TY76Z2rM5mHXA, Geert Uytterhoeven
[-- 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 --]
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2014-01-14 14:36 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-01-14 11:34 [PATCH] spi: Clarify (a)synchronous transfer_one() Geert Uytterhoeven
2014-01-14 11:34 ` Geert Uytterhoeven
2014-01-14 14:36 ` Mark Brown
2014-01-14 14:36 ` Mark Brown
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.