Kernel Functions for Drivers ddidmasync(9F)
NAME
ddidmasync - synchronize CPU and I/O views of memory
SYNOPSIS
#include
#include
int ddidmasync(ddidmahandlet handle, offt offset,
sizet length, uintt type);
INTERFACE LEVEL
Solaris DI specific (Solaris DI).
PARAMETERS
handle The handle filled in by a call to
ddidmaallochandle(9F).
offset The offset into the object described by the han-
dle.
length The length, in bytes, of the area to synchronize.
When length is zero, the entire range starting
from offset to the end of the object has the
requested operation applied to it.
type Indicates the caller's desire about what view of
the memory object to synchronize. The possible
values are DIDMASYNCFORDEV,
DIDMASYNCFORCPU and DIDMASYNCFORKERNEL.
DESCRIPTION
The ddidmasync() function is used to selectively synchron-
ize either a DMA device's or a CPU's view of a memory object
that has DMA resources allocated for I/O . This may involve
operations such as flushes of CPU or I/O caches, as well as
other more complex operations such as stalling until
hardware write buffers have drained.
This function need only be called under certain cir-
cumstances. When resources are allocated for DMA using
ddidmaaddrbindhandle() or ddidmabufbindhandle(), an
implicit ddidmasync() is done. When DMA resources are
deallocated using ddidmaunbindhandle(9F), an implicit
ddidmasync() is done. However, at any time between DMA
resource allocation and deallocation, if the memory object
has been modified by either the DMA device or a CPU and you
SunOS 5.11 Last change: 16 Jan 2006 1
Kernel Functions for Drivers ddidmasync(9F)
wish to ensure that the change is noticed by the party that
did not do the modifying, a call to ddidmasync() is
required. This is true independent of any attributes of the
memory object including, but not limited to, whether or not
the memory was allocated for consistent mode I/O (see
ddidmamemalloc(9F)) or whether or not DMA resources have
been allocated for consistent mode I/O (see
ddidmaaddrbindhandle(9F) or
ddidmabufbindhandle(9F)).
If a consistent view of the memory object must be ensured
between the time DMA resources are allocated for the object
and the time they are deallocated, you must call
ddidmasync() to ensure that either a CPU or a DMA device
has such a consistent view.
What to set type to depends on the view you are trying to
ensure consistency for. If the memory object is modified by
a CPU, and the object is going to be read by the DMA engine
of the device, use DIDMASYNCFORDEV. This ensures that
the device's DMA engine sees any changes that a CPU has made
to the memory object. If the DMA engine for the device has
written to the memory object, and you are going to read
(with a CPU) the object (using an extant virtual address
mapping that you have to the memory object), use
DIDMASYNCFORCPU. This ensures that a CPU's view of the
memory object includes any changes made to the object by the
device's DMA engine. If you are only interested in the
kernel's view (kernel-space part of the CPU's view) you may
use DIDMASYNCFORKERNEL. This gives a hint to the
system-that is, if it is more economical to synchronize the
kernel's view only, then do so; otherwise, synchronize for
CPU.
RETURN VALUES
The ddidmasync() function returns:
DISUCES Caches are successfully flushed.
DIFAILURE The address range to be flushed is out of the
address range established by
ddidmaaddrbindhandle(9F) or
ddidmabufbindhandle(9F).
CONTEXT
The ddidmasync() function can be called from user, inter-
rupt, or kernel context.
SunOS 5.11 Last change: 16 Jan 2006 2
Kernel Functions for Drivers ddidmasync(9F)
SEE ALSO
ddidmaaddrbindhandle(9F), ddidmaallochandle(9F),
ddidmabufbindhandle(9F), ddidmamemalloc(9F),
ddidmaunbindhandle(9F)
Writing Device Drivers
SunOS 5.11 Last change: 16 Jan 2006 3
|
