r167274, r179694, r182816, r182962, r185004

- Some minor tweaks and updates to bus_dma(9) including some additional notes
  on the address filter and locking callback.
- Mark "highaddr" and "lowaddr" appropriately. Change "dma" to "DMA".
- Fix spelling mistage found by rodrigc@.
- Document BUS_DMA_NOCACHE.
- Remove unneeded comma.
- 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.

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 August 31, 2006
+.Dd November 16, 2008
 .Dt BUS_DMA 9
 .Os
 .Sh NAME
@@ -153,7 +153,7 @@ for devices whose DMA address restrictions cannot be specified
 by a single window.
 The
 .Fa filtarg
-is client specified during tag creation to be passed to all
+argument is specified by the client during tag creation to be passed to all
 invocations of the callback.
 The
 .Fa testaddr
@@ -163,11 +163,12 @@ The filter function operates on the set of addresses from
 to
 .Ql trunc_page(testaddr) + PAGE_SIZE - 1 ,
 inclusive.
-The filter function should return zero for any mapping in this range
-that can be accommodated by the device and non-zero otherwise.
+The filter function should return zero if any mapping in this range
+can be accommodated by the device and non-zero otherwise.
 .It Vt bus_dma_segment_t
 A machine-dependent type that describes individual
 DMA segments.
+It contains the following fields:
 .Bd -literal
 	bus_addr_t	ds_addr;
 	bus_size_t	ds_len;
@@ -213,13 +214,13 @@ The
 .Fa segs
 and
 .Fa nseg
-parameters describe an array of
+arguments describe an array of
 .Vt bus_dma_segment_t
 structures that represent the mapping.
 This array is only valid within the scope of the callback function.
 The success or failure of the mapping is indicated by the
 .Fa error
-parameter.
+argument.
 More information on the use of callbacks can be found in the
 description of the individual dmamap load functions.
 .It Vt bus_dmamap_callback2_t
@@ -275,14 +276,14 @@ and prior to device access to host memory.
 Perform any synchronization required after an update of host memory by the
 device and prior to CPU access to host memory.
 .It Dv BUS_DMASYNC_POSTWRITE
-Perform any synchronization required after the device access to host memory.
+Perform any synchronization required after device access to host memory.
 .El
 .It Vt bus_dma_lock_t
 Client specified lock/mutex manipulation method.
 This will be called from
 within busdma whenever a client lock needs to be manipulated.
 In its current form, the function will be called immediately before
-the callback for a dma load operation that has been deferred with
+the callback for a DMA load operation that has been deferred with
 .Dv BUS_DMA_LOCK
 and immediately after with
 .Dv BUS_DMA_UNLOCK .
@@ -295,14 +296,20 @@ This method is of the format:
 .Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op"
 .El
 .Pp
+The
+.Fa lockfuncarg
+argument is specified by the client during tag creation to be passed to all
+invocations of the callback.
+The
+.Fa op
+argument specifies the lock operation to perform.
+.Pp
 Two
 .Vt lockfunc
 implementations are provided for convenience.
 .Fn busdma_lock_mutex
-performs standard mutex operations on the sleep mutex provided via the
+performs standard mutex operations on the sleep mutex provided via
 .Fa lockfuncarg .
-passed into
-.Fn bus_dma_tag_create .
 .Fn dflt_lock
 will generate a system panic if it is called.
 It is substituted into the tag when
@@ -310,7 +317,8 @@ It is substituted into the tag when
 is passed as
 .Dv NULL
 to
-.Fn bus_dma_tag_create .
+.Fn bus_dma_tag_create
+and is useful for tags that should not be used with deferred load operations.
 .It Vt bus_dma_lock_op_t
 Operations to be performed by the client-specified
 .Fn lockfunc .
@@ -355,17 +363,26 @@ indicates that there are no boundary restrictions.
 Bounds of the window of bus address space that
 .Em cannot
 be directly accessed by the device.
-The window contains all addresses greater than lowaddr and
-less than or equal to highaddr.
-For example, a device incapable of DMA above 4GB, would specify
-a highaddr of
+The window contains all addresses greater than
+.Fa lowaddr
+and less than or equal to
+.Fa highaddr .
+For example, a device incapable of DMA above 4GB, would specify a
+.Fa highaddr
+of
 .Dv BUS_SPACE_MAXADDR
-and a lowaddr of
+and a
+.Fa lowaddr
+of
 .Dv BUS_SPACE_MAXADDR_32BIT .
-Similarly a device that can only dma to addresses bellow 16MB would
-specify a highaddr of
+Similarly a device that can only perform DMA to addresses below
+16MB would specify a
+.Fa highaddr
+of
 .Dv BUS_SPACE_MAXADDR
-and a lowaddr of
+and a
+.Fa lowaddr
+of
 .Dv BUS_SPACE_MAXADDR_24BIT .
 Some implementations requires that some region of device visible
 address space, overlapping available host memory, be outside the
@@ -465,9 +482,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
@@ -529,6 +560,15 @@ Are as follows:
 .It Dv BUS_DMA_NOWAIT
 The load should not be deferred in case of insufficient mapping resources,
 and instead should return immediately with an appropriate error.
+.It Dv BUS_DMA_NOCACHE
+The allocated memory will not be cached in the processor caches.
+All memory accesses appear on the bus and are executed
+without reordering.
+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
@@ -690,15 +730,16 @@ that is to be made available to a device.
 To ensure that the data are visible via the device's mapping of that
 memory, the buffer must be loaded and a DMA sync operation of
 .Dv BUS_DMASYNC_PREWRITE
-must be performed.
-If later CPU modifies this buffer again, another
+must be performed after the CPU has updated the buffer and before the device
+access is initiated.
+If the CPU modifies this buffer again later, another
 .Dv BUS_DMASYNC_PREWRITE
-sync operation must be performed before an additional
-access to this memory by a device.
-Conversely, a device updates the memory that is to be read by a CPU.
+sync operation must be performed before an additional device
+access.
+Conversely, suppose a device updates memory that is to be read by a CPU.
 In this case, the buffer must be loaded, and a DMA sync operation of
 .Dv BUS_DMASYNC_PREREAD
-must be performed.
+must be performed before the device access is initiated.
 The CPU will only be able to see the results of this memory update
 once the DMA operation has completed and a
 .Dv BUS_DMASYNC_POSTREAD
@@ -710,7 +751,7 @@ appropriate synchronization operations, behavior is undefined.
 Allocates memory that is mapped into KVA at the address returned
 in
 .Fa vaddr
-that is permanently loaded into the newly created
+and that is permanently loaded into the newly created
 .Vt bus_dmamap_t
 returned via
 .Fa mapp .
@@ -732,16 +773,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
@@ -753,7 +793,9 @@ where the resulting DMA map will be stored.
 .Pp
 The size of memory to be allocated is
 .Fa maxsize
-as specified in
+as specified in the call to
+.Fn bus_dma_tag_create
+for
 .Fa dmat .
 .Pp
 The current implementation of
@@ -801,10 +843,10 @@ transaction,
 .Er ENOMEM
 is returned.
 All
-routines that are not of type,
-.Vt void ,
+routines that are not of type
+.Vt void
 will return 0 on success or an error
-code, as discussed above.
+code on failure as discussed above.
 .Pp
 All
 .Vt void
@@ -878,7 +920,7 @@ called with any non-sleepable locks held:
 .El
 .Pp
 All other functions do not have a locking protocol and can thus be
-called with or without and system or driver locks held.
+called with or without any system or driver locks held.
 .Sh SEE ALSO
 .Xr devclass 9 ,
 .Xr device 9 ,