LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
* [PATCH 1/4] dma: document dma_{un}map_{single|sg}_attrs() interface
@ 2008-01-30  5:50 akepner
  2008-01-31 22:38 ` Grant Grundler
  0 siblings, 1 reply; 3+ messages in thread
From: akepner @ 2008-01-30  5:50 UTC (permalink / raw)
  To: Tony Luck, Grant Grundler, Jesse Barnes, Jes Sorensen,
	Randy Dunlap, Roland Dreier, James Bottomley, David Miller,
	Muli Ben-Yehuda
  Cc: linux-kernel


Document the new dma_{un}map_{single|sg}_attrs() functions. 

Signed-off-by: Arthur Kepner <akepner@sgi.com>

--

 DMA-API.txt |   63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 63 insertions(+)

diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index b939ebb..fad05e0 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -395,6 +395,69 @@ Notes:  You must do this:
 
 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, 
+		     struct dma_attrs* attrs)
+
+void 
+dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
+		       size_t size, enum dma_data_direction dir,
+		       struct dma_attrs* attrs)
+
+int 
+dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
+		 int nents, enum dma_data_direction dir, 
+		 struct dma_attrs *attrs)
+
+void 
+dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl, 
+		   int nents, enum dma_data_direction dir,
+		   struct dma_attrs *attrs)
+
+The four functions above are just like the counterpart functions 
+without the _attrs suffixes, except that they pass an optional 
+struct dma_attrs*. 
+
+struct dma_attrs encapsulates a set of "dma attributes". For the 
+definition of struct dma_attrs see linux/dma-attrs.h. 
+
+The interpretation of dma attributes is architecture-specific. 
+
+If struct dma_attrs* is NULL, the semantics of each of these 
+functions is identical to those of the corresponding function 
+without the _attrs suffix. As a result dma_map_single_attrs() 
+can generally replace dma_map_single(), etc.
+
+As an example of the use of the *_attrs functions, here's how 
+you could pass an attribute DMA_ATTR_FOO when mapping memory 
+for DMA:
+
+#include <linux/dma-attrs.h>
+/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h */
+...
+
+	DECLARE_DMA_ATTRS(attrs);
+	dma_set_attr(&attrs, DMA_ATTR_FOO);
+	....
+	n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr);
+	....
+
+Architectures that care about DMA_ATTR_FOO would check for its 
+presence in their implementations of the mapping and unmapping 
+routines, e.g.:
+
+void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr, 
+			     size_t size, enum dma_data_direction dir, 
+			     struct dma_attrs* attrs)
+{
+	....
+	int foo =  dma_get_attr(attrs, DMA_ATTR_FOO);
+	....
+	if (foo) 
+		/* twizzle the frobnozzle */
+	....
+
 
 Part II - Advanced dma_ usage
 -----------------------------

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH 1/4] dma: document dma_{un}map_{single|sg}_attrs() interface
  2008-01-30  5:50 [PATCH 1/4] dma: document dma_{un}map_{single|sg}_attrs() interface akepner
@ 2008-01-31 22:38 ` Grant Grundler
  2008-02-01  3:07   ` akepner
  0 siblings, 1 reply; 3+ messages in thread
From: Grant Grundler @ 2008-01-31 22:38 UTC (permalink / raw)
  To: akepner
  Cc: Tony Luck, Grant Grundler, Jesse Barnes, Jes Sorensen,
	Randy Dunlap, Roland Dreier, James Bottomley, David Miller,
	Muli Ben-Yehuda, linux-kernel

On Tue, Jan 29, 2008 at 09:50:40PM -0800, akepner@sgi.com wrote:
> 
> Document the new dma_{un}map_{single|sg}_attrs() functions. 

Thank you!

Looks good to me...so far I've only found one nit.

...
> +struct dma_attrs encapsulates a set of "dma attributes". For the 
> +definition of struct dma_attrs see linux/dma-attrs.h. 

Because all architectures will share the set of attrs definitions,
would it be reasonable to document the intent of each attr?

Two reasons for doing this:
1) people reading the driver code should understand WHY the dma attr was added.
2) other arch maintainers need to know in order to implement the same attr
   for their shiny new toys.


> +The interpretation of dma attributes is architecture-specific. 

This statement is really important....but:
Could we add a reference to arch documentation for each attr?

ie something public (doesn't have to be in linux source tree)
which explains the subtlies of how that DMA attr actually works.

Having worked on HP chipsets for 10+ years, I know releasing
original HW docs is often not possible. I'm not asking for the
impossible. Please don't flame me for that. But if the company
is willing to publish the existance of a feature, a paragraph or
two would be good marketing too. Maybe just include comments in
the arch/ code that implements the feature and reference those
comments in DMA-API.txt.


> +If struct dma_attrs* is NULL, the semantics of each of these 
> +functions is identical to those of the corresponding function 
> +without the _attrs suffix. As a result dma_map_single_attrs() 
> +can generally replace dma_map_single(), etc.
> +
> +As an example of the use of the *_attrs functions, here's how 
> +you could pass an attribute DMA_ATTR_FOO when mapping memory 
> +for DMA:
> +
> +#include <linux/dma-attrs.h>
> +/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h */
> +...
> +
> +	DECLARE_DMA_ATTRS(attrs);
> +	dma_set_attr(&attrs, DMA_ATTR_FOO);
> +	....
> +	n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr);
> +	....
> +
> +Architectures that care about DMA_ATTR_FOO would check for its 
> +presence in their implementations of the mapping and unmapping 
> +routines, e.g.:
> +
> +void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr, 
> +			     size_t size, enum dma_data_direction dir, 
> +			     struct dma_attrs* attrs)
> +{
> +	....
> +	int foo =  dma_get_attr(attrs, DMA_ATTR_FOO);
> +	....
> +	if (foo) 
> +		/* twizzle the frobnozzle */
> +	....
> +

Excellent example.

thanks again for remembering DMA-API.txt.

cheers,
grant

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH 1/4] dma: document dma_{un}map_{single|sg}_attrs() interface
  2008-01-31 22:38 ` Grant Grundler
@ 2008-02-01  3:07   ` akepner
  0 siblings, 0 replies; 3+ messages in thread
From: akepner @ 2008-02-01  3:07 UTC (permalink / raw)
  To: Grant Grundler
  Cc: Tony Luck, Jesse Barnes, Jes Sorensen, Randy Dunlap,
	Roland Dreier, James Bottomley, David Miller, Muli Ben-Yehuda,
	linux-kernel

On Thu, Jan 31, 2008 at 03:38:48PM -0700, Grant Grundler wrote:

Thanks for looking through this.

I'll send an updated patchset that addresses your comments 
as soon as I can - probably around Monday.

> ...
> > +struct dma_attrs encapsulates a set of "dma attributes". For the 
> > +definition of struct dma_attrs see linux/dma-attrs.h. 
> 
> Because all architectures will share the set of attrs definitions,
> would it be reasonable to document the intent of each attr?
> 
> Two reasons for doing this:
> 1) people reading the driver code should understand WHY the dma attr was added.
> 2) other arch maintainers need to know in order to implement the same attr
>    for their shiny new toys.
> 
> 
> > +The interpretation of dma attributes is architecture-specific. 
> 
> This statement is really important....but:
> Could we add a reference to arch documentation for each attr?
> 
> ie something public (doesn't have to be in linux source tree)
> which explains the subtlies of how that DMA attr actually works.
> 
> Having worked on HP chipsets for 10+ years, I know releasing
> original HW docs is often not possible. I'm not asking for the
> impossible. Please don't flame me for that. But if the company
> is willing to publish the existance of a feature, a paragraph or
> two would be good marketing too. Maybe just include comments in
> the arch/ code that implements the feature and reference those
> comments in DMA-API.txt.
> ....

OK, I can certainly add an explanation of the attribute that
I'm worried about. 

I think there's a reference to this behavior in our driver 
porting guide - I can add a pointer to that, too. 

This might also address your point above about documenting 
each attribute - let me know once the next patch is out.

-- 
Arthur


^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2008-02-01  3:09 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2008-01-30  5:50 [PATCH 1/4] dma: document dma_{un}map_{single|sg}_attrs() interface akepner
2008-01-31 22:38 ` Grant Grundler
2008-02-01  3:07   ` akepner

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).