Document dma_flags_set_dmabarrier().
Signed-off-by: Arthur Kepner <[email protected]>
---
DMA-API.txt | 26 ++++++++++++++++++++++++++
1 files changed, 26 insertions(+)
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index cc7a8c3..5fc0bba 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -544,3 +544,29 @@ 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_dmabarrier(int dir)
+
+Amend dir (one of the enum dma_data_direction values), with a
+platform-specific "dmabarrier" attribute. The dmabarrier attribute
+forces a flush of all in-flight DMA when the associated memory
+region is written to (see example below.)
+
+This 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.
+
+The dmabarrier would be set when the memory region is mapped for DMA,
+e.g.:
+
+ int count, flags = dma_flags_set_dmabarrier(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 a dmabarrier on the memory used for
+completion indications would prevent the race.
+
On Thu, Sep 27, 2007 at 06:13:02PM -0700, [email protected] wrote:
>
> Document dma_flags_set_dmabarrier().
>
> Signed-off-by: Arthur Kepner <[email protected]>
This looks really good!
thanks,
grant
Acked-by: Grant Grundler <[email protected]>
>
> ---
> DMA-API.txt | 26 ++++++++++++++++++++++++++
> 1 files changed, 26 insertions(+)
>
> diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
> index cc7a8c3..5fc0bba 100644
> --- a/Documentation/DMA-API.txt
> +++ b/Documentation/DMA-API.txt
> @@ -544,3 +544,29 @@ 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_dmabarrier(int dir)
> +
> +Amend dir (one of the enum dma_data_direction values), with a
> +platform-specific "dmabarrier" attribute. The dmabarrier attribute
> +forces a flush of all in-flight DMA when the associated memory
> +region is written to (see example below.)
> +
> +This 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.
> +
> +The dmabarrier would be set when the memory region is mapped for DMA,
> +e.g.:
> +
> + int count, flags = dma_flags_set_dmabarrier(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 a dmabarrier on the memory used for
> +completion indications would prevent the race.
> +