aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorArthur Kepner <akepner@sgi.com>2008-04-29 04:00:31 -0400
committerLinus Torvalds <torvalds@linux-foundation.org>2008-04-29 11:06:11 -0400
commita75b0a2f68d3937f96ed39525e4750601483e3b4 (patch)
tree1a84f2ef16515880f00e2db9a931299f22a07071 /Documentation
parent74bc7ceebfa1c84ddd3a843ebfb56df013bf7ef5 (diff)
dma: document dma_*map*_attrs() interfaces
Document the new dma_*map*_attrs() functions. [markn@au1.ibm.com: fix up for dma-add-dma_map_attrs-interfaces and update docs] Signed-off-by: Arthur Kepner <akepner@sgi.com> Acked-by: David S. Miller <davem@davemloft.net> Cc: Tony Luck <tony.luck@intel.com> Cc: Jesse Barnes <jbarnes@virtuousgeek.org> Cc: Jes Sorensen <jes@sgi.com> Cc: Randy Dunlap <randy.dunlap@oracle.com> Cc: Roland Dreier <rdreier@cisco.com> Cc: James Bottomley <James.Bottomley@HansenPartnership.com> Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org> Cc: Grant Grundler <grundler@parisc-linux.org> Cc: Michael Ellerman <michael@ellerman.id.au> Signed-off-by: Mark Nelson <markn@au1.ibm.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DMA-API.txt65
-rw-r--r--Documentation/DMA-attributes.txt24
2 files changed, 89 insertions, 0 deletions
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index b939ebb62871..5f9f9df4d957 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -395,6 +395,71 @@ Notes: You must do this:
395 395
396See also dma_map_single(). 396See also dma_map_single().
397 397
398dma_addr_t
399dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
400 enum dma_data_direction dir,
401 struct dma_attrs *attrs)
402
403void
404dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
405 size_t size, enum dma_data_direction dir,
406 struct dma_attrs *attrs)
407
408int
409dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
410 int nents, enum dma_data_direction dir,
411 struct dma_attrs *attrs)
412
413void
414dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
415 int nents, enum dma_data_direction dir,
416 struct dma_attrs *attrs)
417
418The four functions above are just like the counterpart functions
419without the _attrs suffixes, except that they pass an optional
420struct dma_attrs*.
421
422struct dma_attrs encapsulates a set of "dma attributes". For the
423definition of struct dma_attrs see linux/dma-attrs.h.
424
425The interpretation of dma attributes is architecture-specific, and
426each attribute should be documented in Documentation/DMA-attributes.txt.
427
428If struct dma_attrs* is NULL, the semantics of each of these
429functions is identical to those of the corresponding function
430without the _attrs suffix. As a result dma_map_single_attrs()
431can generally replace dma_map_single(), etc.
432
433As an example of the use of the *_attrs functions, here's how
434you could pass an attribute DMA_ATTR_FOO when mapping memory
435for DMA:
436
437#include <linux/dma-attrs.h>
438/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h and
439 * documented in Documentation/DMA-attributes.txt */
440...
441
442 DEFINE_DMA_ATTRS(attrs);
443 dma_set_attr(DMA_ATTR_FOO, &attrs);
444 ....
445 n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr);
446 ....
447
448Architectures that care about DMA_ATTR_FOO would check for its
449presence in their implementations of the mapping and unmapping
450routines, e.g.:
451
452void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
453 size_t size, enum dma_data_direction dir,
454 struct dma_attrs *attrs)
455{
456 ....
457 int foo = dma_get_attr(DMA_ATTR_FOO, attrs);
458 ....
459 if (foo)
460 /* twizzle the frobnozzle */
461 ....
462
398 463
399Part II - Advanced dma_ usage 464Part II - Advanced dma_ usage
400----------------------------- 465-----------------------------
diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt
new file mode 100644
index 000000000000..6d772f84b477
--- /dev/null
+++ b/Documentation/DMA-attributes.txt
@@ -0,0 +1,24 @@
1 DMA attributes
2 ==============
3
4This document describes the semantics of the DMA attributes that are
5defined in linux/dma-attrs.h.
6
7DMA_ATTR_WRITE_BARRIER
8----------------------
9
10DMA_ATTR_WRITE_BARRIER is a (write) barrier attribute for DMA. DMA
11to a memory region with the DMA_ATTR_WRITE_BARRIER attribute forces
12all pending DMA writes to complete, and thus provides a mechanism to
13strictly order DMA from a device across all intervening busses and
14bridges. This barrier is not specific to a particular type of
15interconnect, it applies to the system as a whole, and so its
16implementation must account for the idiosyncracies of the system all
17the way from the DMA device to memory.
18
19As an example of a situation where DMA_ATTR_WRITE_BARRIER would be
20useful, suppose that a device does a DMA write to indicate that data is
21ready and available in memory. The DMA of the "completion indication"
22could race with data DMA. Mapping the memory used for completion
23indications with DMA_ATTR_WRITE_BARRIER would prevent the race.
24