Document the new dma_{un}map_{single|sg}_attrs() functions.
Signed-off-by: Arthur Kepner <[email protected]>
---
DMA-API.txt | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++
DMA-attributes.txt | 29 +++++++++++++++++++++++
2 files changed, 94 insertions(+)
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index b939ebb..4c471fc 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -395,6 +395,71 @@ 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, and
+each attribute should be documented in Documentation/DMA-attributes.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 and
+ * documented in Documentation/DMA-attributes.txt */
+...
+
+ 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
-----------------------------
diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt
index e69de29..36baea5 100644
--- a/Documentation/DMA-attributes.txt
+++ b/Documentation/DMA-attributes.txt
@@ -0,0 +1,29 @@
+ DMA attributes
+ ==============
+
+This document describes the semantics of the DMA attributes that are
+defined in linux/dma-attrs.h.
+
+
+DMA_ATTR_SYNC_ON_WRITE
+----------------------
+
+DMA_ATTR_SYNC_ON_WRITE is used on the IA64_SGI_SN2 architecture.
+It provides a mechanism for devices to explicitly order their DMA
+writes.
+
+On IA64_SGI_SN2 machines, DMA may be reordered within the NUMA
+interconnect. Allowing reordering improves performance, but in some
+situations it may be necessary to ensure that one DMA write is
+complete before another is visible. For example, if the device does
+a DMA write to indicate that data is available in memory, DMA of the
+"completion indication" can race with DMA of data.
+
+When a memory region is mapped with the DMA_ATTR_SYNC_ON_WRITE attribute,
+a write to that region causes all in-flight DMA to be flushed to memory.
+Any pending DMA will complete and be visible in memory before the write
+to the region with the DMA_ATTR_SYNC_ON_WRITE attribute becomes visible.
+
+(For more information, see the document titled "SGI Altix Architecture
+Considerations for Linux Device Drivers" at http://techpubs.sgi.com/.)
+
Hi !
For some reason I only got some of your patches... care to resend the
whole serie with me on CC ?
We need to add similar attributes for PowerPC to support relaxed
ordering on some mappings. We started internally adding flags to the
direction, like you initially did, but it looks like that's not the
direction the wind is blowing so ..
Cheers,
Ben.
On Wed, Feb 27, 2008 at 11:03:10AM +1100, Benjamin Herrenschmidt wrote:
> Hi !
>
> For some reason I only got some of your patches... care to resend the
> whole serie with me on CC ?
> ....
Sure. I'm going to send another revision in the next day or so.
(Only comsmetic changes wrt the previous version.)
I'll cc you.
--
Arthur