[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Message-ID: <20071003024752.GH26752@sgi.com>
Date: Tue, 2 Oct 2007 19:47:52 -0700
From: akepner@....com
To: Grant Grundler <grundler@...isc-linux.org>,
Jesse Barnes <jbarnes@...tuousgeek.org>,
Jes Sorensen <jes@....com>,
Randy Dunlap <randy.dunlap@...cle.com>,
RolandDreier <rdreier@...co.com>,
James Bottomley <James.Bottomley@...eleye.com>,
David Miller <davem@...emloft.net>
Cc: linux-kernel@...r.kernel.org
Subject: [PATCH 3/5] dma: document dma_flags_set_attr()
Document dma_flags_set_attr().
Signed-off-by: Arthur Kepner <akepner@....com>
---
DMA-API.txt | 27 +++++++++++++++++++++++++++
1 files changed, 27 insertions(+)
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index cc7a8c3..16e15c0 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -544,3 +544,30 @@ size is the size (and should be a page-sized multiple).
The return value will be either a pointer to the processor virtual
address of the memory, or an error (via PTR_ERR()) if any part of the
region is occupied.
+
+int
+dma_flags_set_attr(u32 attr, enum dma_data_direction dir)
+
+Amend dir with a platform-specific "dma attribute".
+
+The only attribute currently defined is DMA_BARRIER_ATTR, which causes
+in-flight DMA to be flushed when the associated memory region is written
+to (see example below). Setting DMA_BARRIER_ATTR provides a mechanism
+to enforce ordering of DMA on platforms that permit DMA to be reordered
+between device and host memory (within a NUMA interconnect). On other
+platforms this is a nop.
+
+DMA_BARRIER_ATTR would be set when the memory region is mapped for DMA,
+e.g.:
+
+ int count;
+ int flags = dma_flags_set_attr(DMA_BARRIER_ATTR, DMA_BIDIRECTIONAL);
+ ....
+ count = dma_map_sg(dev, sglist, nents, flags);
+
+As an example of a situation where this would be useful, suppose that
+the device does a DMA write to indicate that data is ready and
+available in memory. The DMA of the "completion indication" could
+race with data DMA. Using DMA_BARRIER_ATTR on the memory used for
+completion indications would prevent the race.
+
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Powered by blists - more mailing lists