Skip to contentSkip to conversation

spi: documentation improvements

PATCH Superseded Baruch Siach 3 participants 11 messages Jan 24, 2014 – Jan 25, 2014 6 messages not in the archive SPI

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Baruch Siach

author
#0 lore raw

cover spi: documentation improvements

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

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 | 12 +++++++++++-
 include/linux/spi/spi.h       |  6 ++++--
 2 files changed, 15 insertions(+), 3 deletions(-)
Signature · 6 lines
1.8.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): cover.1390544495.git.baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org

author
#2 lore raw

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

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 <[email protected]>
---
 include/linux/spi/spi.h | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
include/linux/spi/spi.h +3 -1
index 8c62ba74dd91..060b21e82e73 100644
@@ -285,7 +285,9 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv)
  * @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
+ *                the next transfer. Note: transfer_one and
+ *                transfer_one_message are mutually exclusive; when both are
+ *                set, transfer_one takes precedence.
  * @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
Signature · 6 lines
1.8.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 39ffc897bd2e5fd48a3141ed4cd122a80c5bbb20.1390544495.git.baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org

#4 lore raw

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

include/linux/spi/spi.h static inline void spi_unregister_driver(struct spi_driver *sdrv) · line 290

Quoted 10 lines · Baruch Siach
include/linux/spi/spi.h +3 -1
@@ -285,7 +285,9 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv)
  * @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
+ *                the next transfer. Note: transfer_one and
+ *                transfer_one_message are mutually exclusive; when both are
+ *                set, transfer_one takes precedence.

I find this a bit difficult to grasp. What does "take precedence" mean in this context?

The default spi_transfer_one_message() uses .transfer_one(). But if .transfer_one_message() is set, it depends on your own driver if .transfer_one() is used or not.

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): CAMuHMdW05ANcRJW8dPwLuvONoXD+Fny=Txd-wuwXVJHCqmva1A-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

author
#6 lore raw

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

Hi Gerrt,

Quoted 15 lines · Geert Uytterhoeven

include/linux/spi/spi.h static inline void spi_unregister_driver(struct spi_driver *sdrv) · line 290

Quoted 10 lines · Baruch Siach
include/linux/spi/spi.h +3 -1
@@ -285,7 +285,9 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv)
  * @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
+ *                the next transfer. Note: transfer_one and
+ *                transfer_one_message are mutually exclusive; when both are
+ *                set, transfer_one takes precedence.

I find this a bit difficult to grasp. What does "take precedence" mean in this context?

Quoted 3 lines

The default spi_transfer_one_message() uses .transfer_one(). But if .transfer_one_message() is set, it depends on your own driver if .transfer_one() is used or not.

Of course. I misread the code. How about this:

Note: transfer_one and transfer_one_message are mutually exclusive; when both are set, the transfer_one callback is not called by the generic subsystem.

Thanks again,
baruch

Signature · 7 lines
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - [email protected] - tel: +972.2.679.5364, http://www.tkos.co.il -
--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
#7 lore raw

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

Quoted 12 lines · Baruch Siach
Quoted 12 lines

include/linux/spi/spi.h static inline void spi_unregister_driver(struct spi_driver *sdrv) · line 290

Quoted 8 lines
include/linux/spi/spi.h +3 -1
@@ -285,7 +285,9 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv)
  * @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
+ *                the next transfer. Note: transfer_one and
+ *                transfer_one_message are mutually exclusive; when both are
+ *                set, transfer_one takes precedence.

I find this a bit difficult to grasp. What does "take precedence" mean in this context?

Quoted 8 lines
Quoted 3 lines

The default spi_transfer_one_message() uses .transfer_one(). But if .transfer_one_message() is set, it depends on your own driver if .transfer_one() is used or not.

Of course. I misread the code. How about this:

Note: transfer_one and transfer_one_message are mutually exclusive; when both are set, the transfer_one callback is not called by the generic subsystem.

Sounds fine to me, thanks!

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

author
#8 lore raw

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

In reply to a message not in the archive
Signed-off-by Baruch Siach <[email protected]>
---
 Documentation/spi/spi-summary | 10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/spi/spi-summary +10 -0
index f21edb983413..6bd55b9473ca 100644
@@ -545,6 +545,16 @@ 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 message, 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, transfer_one takes
+	precedence.
+
     DEPRECATED METHODS
 
     master->transfer(struct spi_device *spi, struct spi_message *message)
Signature · 6 lines
1.8.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 8b6ee8b5a08cd9fa9a94d16d2621e28b4f087098.1390544495.git.baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org

#10 lore raw

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

Quoted 5 lines · Baruch Siach

+++ b/Documentation/spi/spi-summary

Documentation/spi/spi-summary +0 -0
@@ -545,6 +545,16 @@ SPI MASTER METHODS
        spi_finalize_current_message() so the subsystem can issue the next
        transfer. This may sleep.

Documentation/spi/spi-summary SPI MASTER METHODS · line 557

Quoted 10 lines
Documentation/spi/spi-summary +10 -0
+    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 message, 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, transfer_one takes
+       precedence.
+

Can you please take into account
http://lkml.indiana.edu/hypermail/linux/kernel/1401.2/02465.html?

Thanks!

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): CAMuHMdU=7knbuRQEpeCvkaE808i2GviTYqDX_vnEQm26aOvXTQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

author
#12 lore raw

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

Hi Geert,

Quoted 6 lines · Geert Uytterhoeven
Quoted 5 lines · Baruch Siach

+++ b/Documentation/spi/spi-summary

Documentation/spi/spi-summary +0 -0
@@ -545,6 +545,16 @@ SPI MASTER METHODS
        spi_finalize_current_message() so the subsystem can issue the next
        transfer. This may sleep.
Quoted 13 lines

Documentation/spi/spi-summary SPI MASTER METHODS · line 557

Quoted 10 lines
Documentation/spi/spi-summary +10 -0
+    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 message, 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, transfer_one takes
+       precedence.
+

Can you please take into account
http://lkml.indiana.edu/hypermail/linux/kernel/1401.2/02465.html?

Thanks for reviewing. I'll rebase on Mark's fix/core branch.

baruch

Signature · 7 lines
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - [email protected] - tel: +972.2.679.5364, http://www.tkos.co.il -
--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
#13 lore raw

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

In reply to a message not in the archive

Documentation/spi/spi-summary SPI MASTER METHODS · line 552

Quoted 12 lines · Baruch Siach
Documentation/spi/spi-summary +5 -0
@@ -545,6 +545,16 @@ 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 message, it must call

                           ^^^^^^^ transfer?

Documentation/spi/spi-summary SPI MASTER METHODS · line 558

Quoted 6 lines
Documentation/spi/spi-summary +5 -0
+	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, transfer_one takes
+	precedence.
+
     DEPRECATED METHODS

virtually yours
Gerhard Sittig

Signature · 7 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr. 5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-0 Fax: +49-8142-66989-80  Email: [email protected]
--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 20140124134517.GY20094-kDjWylLy9wD0K7fsECOQyeGNnDKD8DIp@public.gmane.org

author
#15 lore raw

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

Hi Gerhard,

Quoted 8 lines · Gerhard Sittig
Quoted 7 lines · Baruch Siach
Documentation/spi/spi-summary +0 -0
@@ -545,6 +545,16 @@ SPI MASTER METHODS
 	spi_finalize_current_message() so the subsystem can issue the next
 	transfer. This may sleep.
Quoted 6 lines

Documentation/spi/spi-summary SPI MASTER METHODS · line 552

Quoted 5 lines
Documentation/spi/spi-summary +5 -0
+    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 message, it must call

                           ^^^^^^^ transfer?

Right. Will fix.

Thanks,
baruch

Quoted 6 lines
Quoted 6 lines
Documentation/spi/spi-summary +5 -0
+	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, transfer_one takes
+	precedence.
+
     DEPRECATED METHODS
Signature · 7 lines
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - [email protected] - tel: +972.2.679.5364, http://www.tkos.co.il -
--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
author
#16 lore raw

PATCH 3/3 spi: correct the transfer_one_message documentation wording

In reply to a message not in the archive

The transfer_one_message callback handles messages, not transfers.

Signed-off-by Baruch Siach <[email protected]>
---
 Documentation/spi/spi-summary | 2 +-
 include/linux/spi/spi.h       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
Documentation/spi/spi-summary +1 -1
index 6bd55b9473ca..b8b559bb4709 100644
@@ -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)
include/linux/spi/spi.h +1 -1
index 060b21e82e73..286370d6bd23 100644
@@ -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
Signature · 6 lines
1.8.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html