[PATCH -mm 1/4] DMA-API.txt: add dma_sync_single/sg API description

[PATCH -mm 1/4] DMA-API.txt: add dma_sync_single/sg API description

[FUJITA Tomonori]

This adds the description of the following eight function:

dma_sync_single_for_cpu
pci_dma_sync_single_for_cpuvoid
dma_sync_single_for_device
pci_dma_sync_single_for_device
dma_sync_sg_for_cpu
pci_dma_sync_sg_for_cpu
dma_sync_sg_for_device
pci_dma_sync_sg_for_device

It was unclear that the API permits a partial sync (some network
drivers already do though). I made it clear that the sync_single API
can do a partial sync but the sync_sg API can't.

We could do a partial sync with the sync_sg too, however, it's
difficult for driver writers to correctly use the sync_sg API for a
partial sync since the scatterlists passed in to the mapping API can
be modified. It's unlikely that driver writers want to do a partial
sync with the sync_sg API (because the sync_sg API are usually used
for block drivers). So I think that it's better to forbid a partial
sync with the sync_sg API.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Cc: David Miller <davem@davemloft.net>
Cc: James Bottomley <James.Bottomley@suse.de>
---
 Documentation/DMA-API.txt |   42 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 42 insertions(+), 0 deletions(-)

diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index bb0e75e..c8db3d0 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -364,6 +364,48 @@ API.
 Note: <nents> must be the number you passed in, *not* the number of
 physical entries returned.
 
+void
+dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size,
+			enum dma_data_direction direction)
+void
+pci_dma_sync_single_for_cpu(struct pci_dev *hwdev, dma_addr_t dma_handle,
+			    size_t size, int direction)
+void
+dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size,
+			   enum dma_data_direction direction)
+void
+pci_dma_sync_single_for_device(struct pci_dev *hwdev, dma_addr_t dma_handle,
+			       size_t size, int direction)
+void
+dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nelems,
+		    enum dma_data_direction direction)
+void
+pci_dma_sync_sg_for_cpu(struct pci_dev *hwdev, struct scatterlist *sg,
+		        int nelems, int direction)
+void
+dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nelems,
+		       enum dma_data_direction direction)
+void
+pci_dma_sync_sg_for_device(struct pci_dev *hwdev, struct scatterlist *sg,
+		           int nelems, int direction)
+
+Synchronise a single contiguous or scatter/gather mapping for the cpu
+and device. With the sync_sg API, all the parameters must be the same
+as those passed into the single mapping API. With the sync_single API,
+you can use dma_handle and size parameters that aren't identical to
+those passed into the single mapping API to do a partial sync.
+
+Notes:  You must do this:
+
+- Before reading values that have been written by DMA from the device
+  (use the DMA_FROM_DEVICE direction)
+- After writing values that will be written to the device using DMA
+  (use the DMA_TO_DEVICE) direction
+- before *and* after handing memory to the device if the memory is
+  DMA_BIDIRECTIONAL
+
+See also dma_map_single().
+
 dma_addr_t
 dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
 		     enum dma_data_direction dir,
-- 
1.5.6.5

[PATCH -mm 2/4] DMA-API.txt: remove dma_sync_single_range description

[FUJITA Tomonori]

dma_sync_single_for_cpu/for_device supports a partial sync so there is
no point to have dma_sync_single_range (also dma_sync_single was
obsoleted long ago, replaced with dma_sync_single_for_cpu/for_device).

There is no user of dma_sync_single_range() in mainline and only Alpha
architecture supports dma_sync_single_range(). So it's unlikely that
someone out of the tree uses it.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Cc: David Miller <davem@davemloft.net>
Cc: James Bottomley <James.Bottomley@suse.de>
---
 Documentation/DMA-API.txt |   10 ----------
 1 files changed, 0 insertions(+), 10 deletions(-)

diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index c8db3d0..364a6cb 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -528,16 +528,6 @@ into the width returned by this call.  It will also always be a power
 of two for easy alignment.
 
 void
-dma_sync_single_range(struct device *dev, dma_addr_t dma_handle,
-		      unsigned long offset, size_t size,
-		      enum dma_data_direction direction)
-
-Does a partial sync, starting at offset and continuing for size.  You
-must be careful to observe the cache alignment and width when doing
-anything like this.  You must also be extra careful about accessing
-memory you intend to sync partially.
-
-void
 dma_cache_sync(struct device *dev, void *vaddr, size_t size,
 	       enum dma_data_direction direction)
 
-- 
1.5.6.5

[PATCH -mm 3/4] alpha: remove dma_sync_single_range

[FUJITA Tomonori]

dma_sync_single_for_cpu/for_device supports a partial sync so there is
no point to have dma_sync_single_range (also dma_sync_single was
obsoleted long ago, replaced with dma_sync_single_for_cpu/for_device).

There is no user of dma_sync_single_range() in mainline and only Alpha
architecture supports dma_sync_single_range(). So it's unlikely that
someone out of the tree uses it.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Cc: Richard Henderson <rth@twiddle.net>
Cc: Ivan Kokshaysky <ink@jurassic.park.msu.ru>
Cc: Matt Turner <mattst88@gmail.com>
---
 arch/alpha/include/asm/dma-mapping.h |    1 -
 1 files changed, 0 insertions(+), 1 deletions(-)

diff --git a/arch/alpha/include/asm/dma-mapping.h b/arch/alpha/include/asm/dma-mapping.h
index 04eb568..f514ede 100644
--- a/arch/alpha/include/asm/dma-mapping.h
+++ b/arch/alpha/include/asm/dma-mapping.h
@@ -59,7 +59,6 @@ int dma_set_mask(struct device *dev, u64 mask);
 
 #define dma_sync_single_for_cpu(dev, addr, size, dir)	  ((void)0)
 #define dma_sync_single_for_device(dev, addr, size, dir)  ((void)0)
-#define dma_sync_single_range(dev, addr, off, size, dir)  ((void)0)
 #define dma_sync_sg_for_cpu(dev, sg, nents, dir)	  ((void)0)
 #define dma_sync_sg_for_device(dev, sg, nents, dir)	  ((void)0)
 #define dma_cache_sync(dev, va, size, dir)		  ((void)0)
-- 
1.5.6.5

[PATCH -mm 4/4] um: remove dma_sync_single_range

[FUJITA Tomonori]

dma_sync_single_for_cpu/for_device supports a partial sync so there is
no point to have dma_sync_single_range (also dma_sync_single was
obsoleted long ago, replaced with dma_sync_single_for_cpu/for_device).

There is no user of dma_sync_single_range() in mainline and only Alpha
architecture supports dma_sync_single_range(). So it's unlikely that
someone out of the tree uses it.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Cc: Jeff Dike <jdike@addtoit.com>
---
 arch/um/include/asm/dma-mapping.h |    8 --------
 1 files changed, 0 insertions(+), 8 deletions(-)

diff --git a/arch/um/include/asm/dma-mapping.h b/arch/um/include/asm/dma-mapping.h
index 378de4b..b948c14 100644
--- a/arch/um/include/asm/dma-mapping.h
+++ b/arch/um/include/asm/dma-mapping.h
@@ -104,14 +104,6 @@ dma_get_cache_alignment(void)
 }
 
 static inline void
-dma_sync_single_range(struct device *dev, dma_addr_t dma_handle,
-		      unsigned long offset, size_t size,
-		      enum dma_data_direction direction)
-{
-	BUG();
-}
-
-static inline void
 dma_cache_sync(struct device *dev, void *vaddr, size_t size,
 	       enum dma_data_direction direction)
 {
-- 
1.5.6.5

Re: [PATCH -mm 1/4] DMA-API.txt: add dma_sync_single/sg API description

[David Miller]

From: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Date: Thu,  4 Feb 2010 12:13:22 +0900

> This adds the description of the following eight function:
> 
> dma_sync_single_for_cpu
> pci_dma_sync_single_for_cpuvoid
                             ^^^^

That "void" is probably some cut and paste error :-)

> dma_sync_single_for_device
> pci_dma_sync_single_for_device
> dma_sync_sg_for_cpu
> pci_dma_sync_sg_for_cpu
> dma_sync_sg_for_device
> pci_dma_sync_sg_for_device
> 
> It was unclear that the API permits a partial sync (some network
> drivers already do though). I made it clear that the sync_single API
> can do a partial sync but the sync_sg API can't.
> 
> We could do a partial sync with the sync_sg too, however, it's
> difficult for driver writers to correctly use the sync_sg API for a
> partial sync since the scatterlists passed in to the mapping API can
> be modified. It's unlikely that driver writers want to do a partial
> sync with the sync_sg API (because the sync_sg API are usually used
> for block drivers). So I think that it's better to forbid a partial
> sync with the sync_sg API.
> 
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

Acked-by: David S. Miller <davem@davemloft.net>

Re: [PATCH -mm 2/4] DMA-API.txt: remove dma_sync_single_range description

[David Miller]

From: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Date: Thu,  4 Feb 2010 12:13:23 +0900

> dma_sync_single_for_cpu/for_device supports a partial sync so there is
> no point to have dma_sync_single_range (also dma_sync_single was
> obsoleted long ago, replaced with dma_sync_single_for_cpu/for_device).
> 
> There is no user of dma_sync_single_range() in mainline and only Alpha
> architecture supports dma_sync_single_range(). So it's unlikely that
> someone out of the tree uses it.
> 
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

Acked-by: David S. Miller <davem@davemloft.net>

Re: [PATCH -mm 3/4] alpha: remove dma_sync_single_range

[David Miller]

From: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Date: Thu,  4 Feb 2010 12:13:24 +0900

> dma_sync_single_for_cpu/for_device supports a partial sync so there is
> no point to have dma_sync_single_range (also dma_sync_single was
> obsoleted long ago, replaced with dma_sync_single_for_cpu/for_device).
> 
> There is no user of dma_sync_single_range() in mainline and only Alpha
> architecture supports dma_sync_single_range(). So it's unlikely that
> someone out of the tree uses it.
> 
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

Acked-by: David S. Miller <davem@davemloft.net>

Re: [PATCH -mm 4/4] um: remove dma_sync_single_range

[David Miller]

From: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Date: Thu,  4 Feb 2010 12:13:25 +0900

> dma_sync_single_for_cpu/for_device supports a partial sync so there is
> no point to have dma_sync_single_range (also dma_sync_single was
> obsoleted long ago, replaced with dma_sync_single_for_cpu/for_device).
> 
> There is no user of dma_sync_single_range() in mainline and only Alpha
> architecture supports dma_sync_single_range(). So it's unlikely that
> someone out of the tree uses it.
> 
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

Acked-by: David S. Miller <davem@davemloft.net>

Re: [PATCH -mm 1/4] DMA-API.txt: add dma_sync_single/sg API description

[FUJITA Tomonori]

On Wed, 03 Feb 2010 19:21:23 -0800 (PST)
David Miller <davem@davemloft.net> wrote:

> From: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
> Date: Thu,  4 Feb 2010 12:13:22 +0900
> 
> > This adds the description of the following eight function:
> > 
> > dma_sync_single_for_cpu
> > pci_dma_sync_single_for_cpuvoid
>                              ^^^^
> 
> That "void" is probably some cut and paste error :-)

Oops.


> > dma_sync_single_for_device
> > pci_dma_sync_single_for_device
> > dma_sync_sg_for_cpu
> > pci_dma_sync_sg_for_cpu
> > dma_sync_sg_for_device
> > pci_dma_sync_sg_for_device
> > 
> > It was unclear that the API permits a partial sync (some network
> > drivers already do though). I made it clear that the sync_single API
> > can do a partial sync but the sync_sg API can't.
> > 
> > We could do a partial sync with the sync_sg too, however, it's
> > difficult for driver writers to correctly use the sync_sg API for a
> > partial sync since the scatterlists passed in to the mapping API can
> > be modified. It's unlikely that driver writers want to do a partial
> > sync with the sync_sg API (because the sync_sg API are usually used
> > for block drivers). So I think that it's better to forbid a partial
> > sync with the sync_sg API.
> > 
> > Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
> 
> Acked-by: David S. Miller <davem@davemloft.net>

Thanks,

I found other two typos in the commit log so here's the update.

=
From: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Subject: [PATCH -mm 1/4] DMA-API.txt: add dma_sync_single/sg API description

This adds the description of the following eight function:

dma_sync_single_for_cpu
pci_dma_sync_single_for_cpu
dma_sync_single_for_device
pci_dma_sync_single_for_device
dma_sync_sg_for_cpu
pci_dma_sync_sg_for_cpu
dma_sync_sg_for_device
pci_dma_sync_sg_for_device

It was unclear that the API permits a partial sync (some network
drivers already do though). I made it clear that the sync_single API
can do a partial sync but the sync_sg API can't.

We could do a partial sync with the sync_sg API too, however, it's
difficult for driver writers to correctly use the sync_sg API for a
partial sync since the scatterlists passed in to the mapping API can't
be modified. It's unlikely that driver writers want to do a partial
sync with the sync_sg API (because the sync_sg API are usually used
for block drivers). So I think that it's better to forbid a partial
sync with the sync_sg API.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Acked-by: David S. Miller <davem@davemloft.net>
Cc: James Bottomley <James.Bottomley@suse.de>

Re: [PATCH -mm 1/4] DMA-API.txt: add dma_sync_single/sg API description

[James Bottomley]

On Thu, 2010-02-04 at 12:31 +0900, FUJITA Tomonori wrote:
> On Wed, 03 Feb 2010 19:21:23 -0800 (PST)
> David Miller <davem@davemloft.net> wrote:
> 
> > From: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
> > Date: Thu,  4 Feb 2010 12:13:22 +0900
> > 
> > > This adds the description of the following eight function:
> > > 
> > > dma_sync_single_for_cpu
> > > pci_dma_sync_single_for_cpuvoid
> >                              ^^^^
> > 
> > That "void" is probably some cut and paste error :-)
> 
> Oops.
> 
> 
> > > dma_sync_single_for_device
> > > pci_dma_sync_single_for_device
> > > dma_sync_sg_for_cpu
> > > pci_dma_sync_sg_for_cpu
> > > dma_sync_sg_for_device
> > > pci_dma_sync_sg_for_device
> > > 
> > > It was unclear that the API permits a partial sync (some network
> > > drivers already do though). I made it clear that the sync_single API
> > > can do a partial sync but the sync_sg API can't.
> > > 
> > > We could do a partial sync with the sync_sg too, however, it's
> > > difficult for driver writers to correctly use the sync_sg API for a
> > > partial sync since the scatterlists passed in to the mapping API can
> > > be modified. It's unlikely that driver writers want to do a partial
> > > sync with the sync_sg API (because the sync_sg API are usually used
> > > for block drivers). So I think that it's better to forbid a partial
> > > sync with the sync_sg API.
> > > 
> > > Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
> > 
> > Acked-by: David S. Miller <davem@davemloft.net>
> 
> Thanks,
> 
> I found other two typos in the commit log so here's the update.
> 
> =
> From: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
> Subject: [PATCH -mm 1/4] DMA-API.txt: add dma_sync_single/sg API description
> 
> This adds the description of the following eight function:
> 
> dma_sync_single_for_cpu
> pci_dma_sync_single_for_cpu
> dma_sync_single_for_device
> pci_dma_sync_single_for_device
> dma_sync_sg_for_cpu
> pci_dma_sync_sg_for_cpu
> dma_sync_sg_for_device
> pci_dma_sync_sg_for_device
> 
> It was unclear that the API permits a partial sync (some network
> drivers already do though). I made it clear that the sync_single API
> can do a partial sync but the sync_sg API can't.
> 
> We could do a partial sync with the sync_sg API too, however, it's
> difficult for driver writers to correctly use the sync_sg API for a
> partial sync since the scatterlists passed in to the mapping API can't
> be modified. It's unlikely that driver writers want to do a partial
> sync with the sync_sg API (because the sync_sg API are usually used
> for block drivers). So I think that it's better to forbid a partial
> sync with the sync_sg API.
> 
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
> Acked-by: David S. Miller <davem@davemloft.net>
> Cc: James Bottomley <James.Bottomley@suse.de>

For what it's worth, you can add my acked by to both patches too.

James

Re: [PATCH -mm 3/4] alpha: remove dma_sync_single_range

[Matt Turner]

On Wed, Feb 3, 2010 at 10:13 PM, FUJITA Tomonori
<fujita.tomonori@lab.ntt.co.jp> wrote:
> dma_sync_single_for_cpu/for_device supports a partial sync so there is
> no point to have dma_sync_single_range (also dma_sync_single was
> obsoleted long ago, replaced with dma_sync_single_for_cpu/for_device).
>
> There is no user of dma_sync_single_range() in mainline and only Alpha
> architecture supports dma_sync_single_range(). So it's unlikely that
> someone out of the tree uses it.
>
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
> Cc: Richard Henderson <rth@twiddle.net>
> Cc: Ivan Kokshaysky <ink@jurassic.park.msu.ru>
> Cc: Matt Turner <mattst88@gmail.com>
> ---
>  arch/alpha/include/asm/dma-mapping.h |    1 -
>  1 files changed, 0 insertions(+), 1 deletions(-)
>
> diff --git a/arch/alpha/include/asm/dma-mapping.h b/arch/alpha/include/asm/dma-mapping.h
> index 04eb568..f514ede 100644
> --- a/arch/alpha/include/asm/dma-mapping.h
> +++ b/arch/alpha/include/asm/dma-mapping.h
> @@ -59,7 +59,6 @@ int dma_set_mask(struct device *dev, u64 mask);
>
>  #define dma_sync_single_for_cpu(dev, addr, size, dir)    ((void)0)
>  #define dma_sync_single_for_device(dev, addr, size, dir)  ((void)0)
> -#define dma_sync_single_range(dev, addr, off, size, dir)  ((void)0)
>  #define dma_sync_sg_for_cpu(dev, sg, nents, dir)         ((void)0)
>  #define dma_sync_sg_for_device(dev, sg, nents, dir)      ((void)0)
>  #define dma_cache_sync(dev, va, size, dir)               ((void)0)
> --
> 1.5.6.5

Acked-by: Matt Turner <mattst88@gmail.com>

Should I vacuum this one up, or should it go in the -mm tree? I don't
guess there's much point in sending Linus pull requests for single
patches.

Matt

Re: [PATCH -mm 3/4] alpha: remove dma_sync_single_range

[Andrew Morton]

On Wed, 3 Feb 2010 23:06:37 -0500 Matt Turner <mattst88@gmail.com> wrote:

> On Wed, Feb 3, 2010 at 10:13 PM, FUJITA Tomonori
> <fujita.tomonori@lab.ntt.co.jp> wrote:
> > dma_sync_single_for_cpu/for_device supports a partial sync so there is
> > no point to have dma_sync_single_range (also dma_sync_single was
> > obsoleted long ago, replaced with dma_sync_single_for_cpu/for_device).
> >
> > There is no user of dma_sync_single_range() in mainline and only Alpha
> > architecture supports dma_sync_single_range(). So it's unlikely that
> > someone out of the tree uses it.
> >
> > Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
> > Cc: Richard Henderson <rth@twiddle.net>
> > Cc: Ivan Kokshaysky <ink@jurassic.park.msu.ru>
> > Cc: Matt Turner <mattst88@gmail.com>
> > ---
> >  arch/alpha/include/asm/dma-mapping.h |    1 -
> >  1 files changed, 0 insertions(+), 1 deletions(-)
> >
> > diff --git a/arch/alpha/include/asm/dma-mapping.h b/arch/alpha/include/asm/dma-mapping.h
> > index 04eb568..f514ede 100644
> > --- a/arch/alpha/include/asm/dma-mapping.h
> > +++ b/arch/alpha/include/asm/dma-mapping.h
> > @@ -59,7 +59,6 @@ int dma_set_mask(struct device *dev, u64 mask);
> >
> >  #define dma_sync_single_for_cpu(dev, addr, size, dir)    ((void)0)
> >  #define dma_sync_single_for_device(dev, addr, size, dir)  ((void)0)
> > -#define dma_sync_single_range(dev, addr, off, size, dir)  ((void)0)
> >  #define dma_sync_sg_for_cpu(dev, sg, nents, dir)         ((void)0)
> >  #define dma_sync_sg_for_device(dev, sg, nents, dir)      ((void)0)
> >  #define dma_cache_sync(dev, va, size, dir)               ((void)0)
> > --
> > 1.5.6.5
> 
> Acked-by: Matt Turner <mattst88@gmail.com>
> 
> Should I vacuum this one up, or should it go in the -mm tree? I don't
> guess there's much point in sending Linus pull requests for single
> patches.
> 

I'll grab it.