From afbeac3e60d391b8f550aec8bf213c1a7b8a40dc Mon Sep 17 00:00:00 2001
From: Marius Strobl <marius@FreeBSD.org>
Date: Sun, 16 Nov 2008 18:30:16 +0000
Subject: [PATCH] - For maximum flexibility, sparc64 supports BUS_DMA_COHERENT
 also   with bus_dmamap_create() and not only bus_dmamem_alloc() so move   the
 description of this flag up accordingly in order to document   this fact.
 While at, it refine this description with an application   example. - Reword
 the description of BUS_DMA_NOCACHE as this flag is also   implemented on
 sparc64.

MFC after:	1 week
---
 share/man/man9/bus_dma.9 | 47 ++++++++++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9
index 8b554578f3e6..5850db6bf191 100644
--- a/share/man/man9/bus_dma.9
+++ b/share/man/man9/bus_dma.9
@@ -60,7 +60,7 @@
 .\" $FreeBSD$
 .\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $
 .\"
-.Dd March 6, 2007
+.Dd November 16, 2008
 .Dt BUS_DMA 9
 .Os
 .Sh NAME
@@ -483,9 +483,23 @@ Arguments are as follows:
 .It Fa dmat
 DMA tag.
 .It Fa flags
-The value of this argument is currently undefined and should be
-specified as
-.Ql 0 .
+Are as follows:
+.Bl -tag -width ".Dv BUS_DMA_COHERENT"
+.It Dv BUS_DMA_COHERENT
+Attempt to map the memory loaded with this map such that cache sync
+operations are as cheap as possible.
+This flag is typically set on maps when the memory loaded with these will
+be accessed by both a CPU and a DMA engine, frequently such as control data
+and as opposed to streamable data such as receive and transmit buffers.
+Use of this flag does not remove the requirement of using
+.Fn bus_dmamap_sync ,
+but it may reduce the cost of performing these operations.
+For
+.Fn bus_dmamap_create ,
+the
+.Dv BUS_DMA_COHERENT
+flag is currently implemented on sparc64.
+.El
 .It Fa mapp
 Pointer to a
 .Vt bus_dmamap_t
@@ -551,9 +565,11 @@ and instead should return immediately with an appropriate error.
 The allocated memory will not be cached in the processor caches.
 All memory accesses appear on the bus and are executed
 without reordering.
-Currently the flag is implemented for i386 and amd64 architectures
-only, where it results in the Strong Uncacheable
-PAT to be set for the allocated virtual address range.
+On the amd64 and i386 architectures this flag results in the
+Strong Uncacheable PAT to be set for the allocated virtual address range.
+The
+.Dv BUS_DMA_NOCACHE
+flag is currently implemented on amd64, i386 and sparc64.
 .El
 .El
 .Pp
@@ -758,16 +774,15 @@ If resources are not available,
 .Dv ENOMEM
 is returned.
 .It Dv BUS_DMA_COHERENT
-Attempt to map this memory such that cache sync operations are
-as cheap as possible.
-This flag is typically set on memory that will be accessed by both
-a CPU and a DMA engine, frequently.
-Use of this flag does not remove the requirement of using
-bus_dmamap_sync, but it may reduce the cost of performing
-these operations.
-The
+Attempt to map this memory in a coherent fashion.
+See
+.Fn bus_dmamap_create
+above for a description of this flag.
+For
+.Fn bus_dmamem_alloc ,
+the
 .Dv BUS_DMA_COHERENT
-flag is currently implemented on sparc64 and arm.
+flag is currently implemented on arm and sparc64.
 .It Dv BUS_DMA_ZERO
 Causes the allocated memory to be set to all zeros.
 .El