[PATCH v3 0/3] spi: documentation improvements

[PATCH v3 0/3] spi: documentation improvements

[Baruch Siach]

This series improves spi documentation as follows:

   * Add explicit note that transfer_one and transfer_one_message are mtually 
     exclusive

   * Add transfer_one documentation to spi-summary

   * s/transfer/message/ in the transfer_one_message description

v3:
   * Add transfer_one return values to spi-summary (Geert Uytterhoe)

   * s/message/transfer/ in transfer_one description (Gerhard Sittig)

v2:
   * Rebase over Mark's fix/core branch (Geert Uytterhoe)

   * Correct the description of code behaviour when transfer_one and 
	 transfer_one_message are both implemented (Geert Uytterhoe)

Baruch Siach (3):
  spi: spi.h: clarify the documentation of transfer_one
  Doc: spi: document the transfer_one spi_master callback
  spi: correct the transfer_one_message documentation wording

 Documentation/spi/spi-summary | 17 ++++++++++++++++-
 include/linux/spi/spi.h       |  7 +++++--
 2 files changed, 21 insertions(+), 3 deletions(-)

-- 
1.8.5.2

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

[PATCH v3 1/3] spi: spi.h: clarify the documentation of transfer_one

[Baruch Siach]

Explicitly note the transfer_one and transfer_one_message are mutually
exclusive, to make the text a little more newcomers friendly.

Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
---
 include/linux/spi/spi.h | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index 9f5242df9311..f5a08c3f3e60 100644
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -287,7 +287,10 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv)
  *                  - return 1 if the transfer is still in progress. When
  *                    the driver is finished with this transfer it must
  *                    call spi_finalize_current_transfer() so the subsystem
- *                    can issue the next transfer
+ *                    can issue the next transfer. Note: transfer_one and
+ *                    transfer_one_message are mutually exclusive; when both
+ *                    are set, the generic subsystem does not call your
+ *                    transfer_one callback.
  * @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.8.5.2

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

[PATCH v3 2/3] Doc: spi: document the transfer_one spi_master callback

[Baruch Siach]

Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
---
 Documentation/spi/spi-summary | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index f21edb983413..7192c0b6dd54 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -545,6 +545,21 @@ SPI MASTER METHODS
 	spi_finalize_current_message() so the subsystem can issue the next
 	transfer. This may sleep.
 
+    master->transfer_one(struct spi_master *master, struct spi_device *spi,
+			 struct spi_transfer *transfer)
+	The subsystem calls the driver to transfer a single transfer while
+	queuing transfers that arrive in the meantime. When the driver is
+	finished with this transfer, it must call
+	spi_finalize_current_transfer() so the subsystem can issue the next
+	transfer. This may sleep. Note: transfer_one and transfer_one_message
+	are mutually exclusive; when both are set, the generic subsystem does
+	not call your transfer_one callback.
+
+	Return values:
+	negative errno: error
+	0: transfer is finished
+	1: transfer is still in progress
+
     DEPRECATED METHODS
 
     master->transfer(struct spi_device *spi, struct spi_message *message)
-- 
1.8.5.2

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

[PATCH v3 3/3] spi: correct the transfer_one_message documentation wording

[Baruch Siach]

The transfer_one_message callback handles messages, not transfers.

Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>
---
 Documentation/spi/spi-summary | 2 +-
 include/linux/spi/spi.h       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index 7192c0b6dd54..cb00a6cc0cf1 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -543,7 +543,7 @@ SPI MASTER METHODS
 	queuing transfers that arrive in the meantime. When the driver is
 	finished with this message, it must call
 	spi_finalize_current_message() so the subsystem can issue the next
-	transfer. This may sleep.
+	message. This may sleep.
 
     master->transfer_one(struct spi_master *master, struct spi_device *spi,
 			 struct spi_transfer *transfer)
diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index f5a08c3f3e60..60b787ad4ed1 100644
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -273,7 +273,7 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv)
  *	message while queuing transfers that arrive in the meantime. When the
  *	driver is finished with this message, it must call
  *	spi_finalize_current_message() so the subsystem can issue the next
- *	transfer
+ *	message
  * @unprepare_transfer_hardware: there are currently no more messages on the
  *	queue so the subsystem notifies the driver that it may relax the
  *	hardware by issuing this call
-- 
1.8.5.2

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

Re: [PATCH v3 1/3] spi: spi.h: clarify the documentation of transfer_one

[Mark Brown]

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

On Sat, Jan 25, 2014 at 10:36:13PM +0200, Baruch Siach wrote:
> Explicitly note the transfer_one and transfer_one_message are mutually
> exclusive, to make the text a little more newcomers friendly.

Applied, thanks.  Still surprised this is confusing but hey ho.

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

Re: [PATCH v3 2/3] Doc: spi: document the transfer_one spi_master callback

[Mark Brown]

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

On Sat, Jan 25, 2014 at 10:36:14PM +0200, Baruch Siach wrote:
> Signed-off-by: Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org>

Applied, thanks.

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

Re: [PATCH v3 3/3] spi: correct the transfer_one_message documentation wording

[Mark Brown]

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

On Sat, Jan 25, 2014 at 10:36:15PM +0200, Baruch Siach wrote:
> The transfer_one_message callback handles messages, not transfers.

Applied, thanks.

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