Document the dma_flags_set/get_*() interfaces.
Signed-off-by: Arthur Kepner <[email protected]>
---
DMA-API.txt | 38 ++++++++++++++++++++++++++++++++++++++
1 files changed, 38 insertions(+)
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index b939ebb..00919b0 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -547,3 +547,41 @@ 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.
+
+int
+dma_flags_get_dir(int flags)
+
+Retrieve the original DMA direction, where flags was returned from
+dma_flags_set_attr().
+
+int
+dma_flags_get_attr(int flags)
+
+Retrieve the "dma attributes", where flags was returned from
+dma_flags_set_attr().
On Tue, 16 Oct 2007 18:44:17 -0700 [email protected] wrote:
> @@ -547,3 +547,41 @@ 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);
> +
Isn't this rather a kludge?
What would be the cost of doing this cleanly and either redefining
dma_data_direction to be a field-of-bits or just leave dma_data_direction
alone (it is quite unrelated to this work, isn't it?) and adding new
fields/arguments to manage this new functionality?