[PATCH 0/3] spi: documentation improvements

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

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

-- 
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 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 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index 8c62ba74dd91..060b21e82e73 100644
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -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
-- 
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 1/3] spi: spi.h: clarify the documentation of transfer_one

[Geert Uytterhoeven]

On Fri, Jan 24, 2014 at 7:28 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> --- a/include/linux/spi/spi.h
> +++ b/include/linux/spi/spi.h
> @@ -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 -- geert-Td1EMuHUCqxL1ZNQvxDV9g@public.gmane.org

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Baruch Siach]

Hi Gerrt,

On Fri, Jan 24, 2014 at 08:44:32AM +0100, Geert Uytterhoeven wrote:
> On Fri, Jan 24, 2014 at 7:28 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> > --- a/include/linux/spi/spi.h
> > +++ b/include/linux/spi/spi.h
> > @@ -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.

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

-- 
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org - 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Geert Uytterhoeven]

On Fri, Jan 24, 2014 at 9:12 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
>> > @@ -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.
>
> 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 -- geert-Td1EMuHUCqxL1ZNQvxDV9g@public.gmane.org

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 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 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index f21edb983413..6bd55b9473ca 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -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)
-- 
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 2/3] Doc: spi: document the transfer_one spi_master callback

[Geert Uytterhoeven]

On Fri, Jan 24, 2014 at 7:28 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> +++ b/Documentation/spi/spi-summary
> @@ -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.
> +

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 -- geert-Td1EMuHUCqxL1ZNQvxDV9g@public.gmane.org

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Baruch Siach]

Hi Geert,

On Fri, Jan 24, 2014 at 08:49:02AM +0100, Geert Uytterhoeven wrote:
> On Fri, Jan 24, 2014 at 7:28 AM, Baruch Siach <baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org> wrote:
> > +++ b/Documentation/spi/spi-summary
> > @@ -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.
> > +
> 
> 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

-- 
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org - 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Gerhard Sittig]

On Fri, Jan 24, 2014 at 08:28 +0200, Baruch Siach wrote:
> 
> --- a/Documentation/spi/spi-summary
> +++ b/Documentation/spi/spi-summary
> @@ -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?
> +	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
-- 
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: office-ynQEQJNshbs@public.gmane.org
--
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 2/3] Doc: spi: document the transfer_one spi_master callback

[Baruch Siach]

Hi Gerhard,

On Fri, Jan 24, 2014 at 02:45:17PM +0100, Gerhard Sittig wrote:
> On Fri, Jan 24, 2014 at 08:28 +0200, Baruch Siach wrote:
> > 
> > --- a/Documentation/spi/spi-summary
> > +++ b/Documentation/spi/spi-summary
> > @@ -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?

Right. Will fix.

Thanks,
baruch

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

-- 
     http://baruch.siach.name/blog/                  ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - baruch-NswTu9S1W3P6gbPvEgmw2w@public.gmane.org - 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 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 6bd55b9473ca..b8b559bb4709 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 060b21e82e73..286370d6bd23 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