ddi_dma_buf_bind_handle(9F)
NAME
ddi_dma_buf_bind_handle - binds a system buffer to a DMA
handle
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_dma_buf_bind_handle(ddi_dma_handle_t handle, struct
buf *bp, uint_t flags, int (*callback)(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).
bp A pointer to a system buffer structure (see buf(9S)).
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 available now. 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_buf_bind_handle() allocates DMA resources for a sys-
tem buffer such that a device can perform DMA to or from the
buffer. 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_buf_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) *countp-1 times.
When a DMA transfer completes, the driver should free 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 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 allocated. If
resources were allocated for only part of the object,
ddi_dma_addr_bind_handle() returns resources for the
first DMA window. Even when DDI_DMA_PARTIAL is set,
the system may decide to allocate 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 rou-
tines 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 call at
a later time when resources may become available. When the
specified function is called, it is passed arg as an argu-
ment. 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 to do so. In
this case the callback function is put back on a list to be
called again later. DDI_DMA_CALLBACK_DONE indicates either a
successful allocation of DMA resources or that 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 necessary to protect its critical resources, data
structures, queues, etc.
RETURN VALUES
ddi_dma_buf_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 max-
imum size varies depending on machine and configura-
tion.
CONTEXT
ddi_dma_buf_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 be called from user or
kernel context only.
SEE ALSO
ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F),
ddi_dma_free_handle(9F), ddi_dma_getwin(9F),
ddi_dma_nextcookie(9F), ddi_dma_sync(9F),
ddi_dma_unbind_handle(9F), buf(9S), 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 perform
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