Aren/NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document the forthcoming BUS_DMA_STREAMING flag, per the

Browse Source 
discussion about it on tech-kern.
This commit is contained in:
thorpej 2001-03-07 22:23:45 +00:00
parent 3812bc3f00
commit bef1dcbc81
1 changed files with 52 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
share/man/man9/bus_dma.9
View File

@ -1,6 +1,6 @@
.\" $NetBSD: bus_dma.9,v 1.14 2000/06/14 06:49:19 cgd Exp $
.\" $NetBSD: bus_dma.9,v 1.15 2001/03/07 22:23:45 thorpej Exp $
.\"
.\" Copyright (c) 1996, 1997, 1998 The NetBSD Foundation, Inc.
.\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
@ -252,11 +252,31 @@ buffer is assumed to be in process
address space.
.It Fa flags
are defined as follows:
.Bl -tag -width "BUS_DMA_BUS[1-4]" -compact
.Bl -tag -width "BUS_DMA_STREAMING" -compact
.It Dv BUS_DMA_WAITOK
It is safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_NOWAIT
It is not safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_STREAMING
By default, the
.Nm
API assumes that there is coherency between memory and the device
performing the DMA transaction. Some platforms, however, have
special hardware, such as an
.Dq I/O cache ,
which may improve performance
of some types of DMA transactions, but which break the assumption
that there is coherency between memory and the device performing
the DMA transaction.
This flag allows the use of this special hardware, provided that
the device is doing sequential, unidirectional transfers which
conform to certain alignment and size contraints defined by the
platform. If the platform does not support the feature, or if
the buffer being loaded into the DMA map does not conform to the
contraints required for use of the feature, then this flag will
be silently ignored. Also refer to the use of this flag with the
.Fn bus_dmamem_alloc
function.
.It Dv BUS_DMA_BUS[1-4]
These flags are placeholders, and may be used by busses to
provide bus-dependent functionality.
@ -497,11 +517,24 @@ of segments that the allocated memory may contain.
Used to return the actual number of segments the memory contains.
.It Fa flags
Flags are defined as follows:
.Bl -tag -width BUS_DMA_BUS[1-4] -compact
.Bl -tag -width BUS_DMA_STREAMING -compact
.It Dv BUS_DMA_WAITOK
It is safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_NOWAIT
It is not safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_STREAMING
Adjusts, if necessary, the size, alignment, and boundary contrains
to conform to the platform-dependent requirements for the use of the
.Dv BUS_DMA_STREAMING
flag with the
.Fn bus_dmamap_load
function. If the platform does not support the
.Dv BUS_DMA_STREAMING
feature, or if the size, alignment, and boundary constraints
would already satisfy the platform's requirements, this flag
is silently ignored. The
.Dv BUS_DMA_STREAMING
flag will never relax the constraints specified in the call.
.It Dv BUS_DMA_BUS[1-4]
These flags are placeholders, and may be used by busses to provide
bus-dependent functionality.
@ -576,8 +609,8 @@ This flag is a
to machine-dependent code. If possible, map the memory in such a way
as it will be DMA coherent. This may include mapping the pages into
uncached address space or setting the cache-inhibit bits in page table
entries. If implementation of DMA coherent mappings is impossible, this
is ignored.
entries. If DMA coherent mappings are impossible, this flag is
silently ignored.
.Pp
Later, when this memory is loaded into a DMA map, machine-dependent code
will take whatever steps are necessary to determine if the memory was
@ -587,6 +620,19 @@ cache-inhibit bits are set in page table entries. If it is determined
that the mapping is DMA coherent, state may be placed into the DMA map
for use by later calls to
.Fn bus_dmamap_sync .
.Pp
Note that a device driver must not rely on
.Dv BUS_DMA_COHERENT
for correct operation. All calls to
.Fn bus_dmamap_sync
must still be made. This flag is provided only as an optimization
hint to machine-dependent code.
.Pp
Also note that this flag only applies to coherency between the CPU
and memory. Coherency between memory and the device is controlled
with a different flag. See the description of the
.Fn bus_dmamap_load
function.
.El
.El
.Pp