[src/trunk]: src/share/man/man9 Make it absolutely clear that bus_dmamap_sync...

[fvdl <fvdl%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/de3d718dbd66
branches:  trunk
changeset: 532669:de3d718dbd66
user:      fvdl <fvdl%NetBSD.org@localhost>
date:      Wed Jun 12 15:23:34 2002 +0000

description:
Make it absolutely clear that bus_dmamap_sync is explicitly needed
for correct operation on all platforms.

diffstat:

 share/man/man9/bus_dma.9 |  29 +++++++++++++++++++++--------
 1 files changed, 21 insertions(+), 8 deletions(-)

diffs (58 lines):

diff -r 3a43d4e5ba6c -r de3d718dbd66 share/man/man9/bus_dma.9
--- a/share/man/man9/bus_dma.9  Wed Jun 12 12:19:53 2002 +0000
+++ b/share/man/man9/bus_dma.9  Wed Jun 12 15:23:34 2002 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: bus_dma.9,v 1.22 2002/02/13 08:18:36 ross Exp $
+.\" $NetBSD: bus_dma.9,v 1.23 2002/06/12 15:23:34 fvdl Exp $
 .\"
 .\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -366,6 +366,11 @@
 on resources if the handle was created with
 .Dv BUS_DMA_ALLOCNOW .
 .Pp
+.Fn bus_dmamap_unload
+will not perform any implicit synchronization of DMA buffers. This
+must be done explicitly by
+.Fn bus_dmamap_sync .
+.Pp
 Behavior is not defined if invalid arguments are passed to
 .Fn bus_dmamap_unload .
 .Pp
@@ -432,14 +437,14 @@
 .Fn bus_dmamap_sync
 will always cause the store buffer to be flushed.
 .Pp
-This function exists so that multiple read and write transfers can be
-performed with the same buffer, and so that drivers can explicitly
-inform the
-.Nm
-code when their data is 'ready' in its DMA buffer.
+This function exists to ensure that the host and the device have
+a consistent view of a range of DMA memory, before and after
+a DMA operation.
 .Pp
-An example of multiple read-write use of a single mapping
-might look like:
+An example of using
+.Fn bus_dmamamp_sync
+, involving multiple read-write use of a single mapping
+might look like this:
 .Bd -literal
 bus_dmamap_load(...);
 
@@ -470,6 +475,14 @@
 bus_dmamap_unload(...);
 .Ed
 .Pp
+This function
+.Em must
+be called to synchronize DMA buffers before and after a DMA operation.
+Other
+.Nm
+functions can
+.Em not
+be relied on to do this synchronization implicitly.
 If DMA read and write operations are not preceded and followed by the
 appropriate synchronization operations, behavior is undefined.
 .Pp