ddi_dma_addr_bind_handle(9F)
NAME
ddi_dma_addr_bind_handle - binds an address to a DMA handle
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_dma_addr_bind_handle(ddi_dma_handle_t handle, struct
as *as, caddr_t addr, size_t len, uint_t flags, int (*call-
back) (caddr_t) , caddr_t arg, ddi_dma_cookie_t *cookiep,
uint_t *ccountp);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).
PARAMETERS
handle
The DMA handle previously allocated by a call to
ddi_dma_alloc_handle(9F).
as A pointer to an address space structure. This parame-
ter should be set to NULL, which implies kernel
address space.
addr Virtual address of the memory object.
len Length of the memory object in bytes.
flags Valid flags include:
DDI_DMA_WRITE
Transfer direction is from memory to I/O.
DDI_DMA_READ
Transfer direction is from I/O to memory.
DDI_DMA_RDWR
Both read and write.
DDI_DMA_REDZONE
Establish an MMU redzone at end of the object.
DDI_DMA_PARTIAL
Partial resource allocation.
DDI_DMA_CONSISTENT
Nonsequential, random, and small block
transfers.
DDI_DMA_STREAMING
Sequential, unidirectional, block-sized, and
block-aligned transfers.
callback
The address of a function to call back later if
resources are not currently available. The following
special function addresses may also be used.
DDI_DMA_SLEEP
Wait until resources are available.
DDI_DMA_DONTWAIT
Do not wait until resources are available and do
not schedule a callback.
arg Argument to be passed to the callback function, call-
back, if such a function is specified.
cookiep
A pointer to the first ddi_dma_cookie(9S) structure.
ccountp
Upon a successful return, ccountp points to a value
representing the number of cookies for this DMA
object.
DESCRIPTION
ddi_dma_addr_bind_handle() allocates DMA resources for a
memory object such that a device can perform DMA to or from
the object. DMA resources are allocated considering the
device's DMA attributes as expressed by ddi_dma_attr(9S)
(see ddi_dma_alloc_handle(9F)).
ddi_dma_addr_bind_handle() fills in the first DMA cookie
pointed to by cookiep with the appropriate address, length,
and bus type. *ccountp is set to the number of DMA cookies
representing this DMA object. Subsequent DMA cookies must be
retrieved by calling ddi_dma_nextcookie(9F) the number of
times specified by *countp-1.
When a DMA transfer completes, the driver frees up system
DMA resources by calling ddi_dma_unbind_handle(9F).
The flags argument contains information for mapping rou-
tines.
DDI_DMA_WRITE, DDI_DMA_READ, DDI_DMA_RDWR
These flags describe the intended direction of the DMA
transfer.
DDI_DMA_STREAMING
This flag should be set if the device is doing sequen-
tial, unidirectional, block-sized, and block-aligned
transfers to or from memory. The alignment and
padding constraints specified by the minxfer and
burstsizes fields in the DMA attribute structure,
ddi_dma_attr(9S) (see ddi_dma_alloc_handle(9F)) is
used to allocate the most effective hardware support
for large transfers.
DDI_DMA_CONSISTENT
This flag should be set if the device accesses memory
randomly, or if synchronization steps using
ddi_dma_sync(9F) need to be as efficient as possible.
I/O parameter blocks used for communication between a
device and a driver should be allocated using
DDI_DMA_CONSISTENT.
DDI_DMA_REDZONE
If this flag is set, the system attempts to establish
a protected red zone after the object. The DMA
resource allocation functions do not guarantee the
success of this request as some implementations may
not have the hardware ability to support a red zone.
DDI_DMA_PARTIAL
Setting this flag indicates the caller can accept
resources for part of the object. That is, if the size
of the object exceeds the resources available, only
resources for a portion of the object are allocated.
The system indicates this condition by returning
status DDI_DMA_PARTIAL_MAP. At a later point, the
caller can use ddi_dma_getwin(9F) to change the valid
portion of the object for which resources are allo-
cated. If resources were allocated for only part of
the object, ddi_dma_addr_bind_handle() returns
resources for the first DMAwindow. Even when
DDI_DMA_PARTIAL is set, the system may decide to allo-
cate resources for the entire object (less overhead)
in which case DDI_DMA_MAPPED is returned.
The callback function callback indicates how a caller wants
to handle the possibility of resources not being available.
If callback is set to DDI_DMA_DONTWAIT, the caller does not
care if the allocation fails, and can handle an allocation
failure appropriately. If callback is set to DDI_DMA_SLEEP,
the caller wishes to have the allocation routines wait for
resources to become available. If any other value is set and
a DMA resource allocation fails, this value is assumed to be
the address of a function to be called when resources
become available. When the specified function is called,
arg is passed to it as an argument. The specified callback
function must return either DDI_DMA_CALLBACK_RUNOUT or
DDI_DMA_CALLBACK_DONE. DDI_DMA_CALLBACK_RUNOUT indicates
that the callback function attempted to allocate DMA
resources but failed. In this case, the callback function
is put back on a list to be called again later.
DDI_DMA_CALLBACK_DONE indicates that either the allocation
of DMA resources was successful or the driver no longer
wishes to retry.
The callback function is called in interrupt context. There-
fore, only system functions accessible from interrupt con-
text are be available. The callback function must take what-
ever steps are necessary to protect its critical resources,
data structures, queues, and so on.
RETURN VALUES
ddi_dma_addr_bind_handle() returns:
DDI_DMA_MAPPED
Successfully allocated resources for the entire
object.
DDI_DMA_PARTIAL_MAP
Successfully allocated resources for a part of the
object. This is acceptable when partial transfers are
permitted by setting the DDI_DMA_PARTIAL flag in
flags.
DDI_DMA_INUSE
Another I/O transaction is using the DMA handle.
DDI_DMA_NORESOURCES
No resources are available at the present time.
DDI_DMA_NOMAPPING
The object cannot be reached by the device requesting
the resources.
DDI_DMA_TOOBIG
The object is too big. A request of this size can
never be satisfied on this particular system. The
maximum size varies depending on machine and confi-
guration.
CONTEXT
ddi_dma_addr_bind_handle() can be called from user, kernel,
or interrupt context, except when callback is set to
DDI_DMA_SLEEP, in which case it can only be called from user
or kernel context.
SEE ALSO
ddi_dma_alloc_handle(9F), ddi_dma_free_handle(9F),
ddi_dma_getwin(9F), ddi_dma_mem_alloc(9F),
ddi_dma_mem_free(9F), ddi_dma_nextcookie(9F),
ddi_dma_sync(9F), ddi_dma_unbind_handle(9F),
ddi_umem_iosetup(9F), ddi_dma_attr(9S), ddi_dma_cookie(9S)
Writing Device Drivers
NOTES
If the driver permits partial mapping with the
DDI_DMA_PARTIAL flag, the number of cookies in each window
may exceed the size of the device's scatter/gather list as
specified in the dma_attr_sgllen field in the
ddi_dma_attr(9S) structure. In this case, each set of cook-
ies comprising a DMA window will satisfy the DMA attributes
as described in the ddi_dma_attr(9S) structure in all
aspects. The driver should set up its DMA engine and per-
form one transfer for each set of cookies sufficient for its
scatter/gather list, up to the number of cookies for this
window, before advancing to the next window using
ddi_dma_getwin(9F).
Man(1) output converted with
man2html