Kernel Functions for Drivers ddi_dma_buf_bind_handle(9F)
NAME
ddi_dma_buf_bind_handle - binds a system buffer to a DMA
handleSYNOPSIS
#include
#include
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 toddi_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 alloca-
tionDDI_DMA_CONSISTENT Nonsequential, random, and
small block transfers.SunOS 5.11 Last change: 27 Jul 1996 1
Kernel Functions for Drivers ddi_dma_buf_bind_handle(9F)
DDI_DMA_STREAMING Sequential, unidirec-
tional, 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, callback, if such a function is specified.cookiep A pointer to the first ddi_dma_cookie(9S) struc-
ture. 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'sDMA 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 beretrieved by calling ddi_dma_nextcookie(9F) *countp-1 times.
When a DMA transfer completes, the driver should free upsystem DMA resources by calling ddi_dma_unbind_handle(9F).
SunOS 5.11 Last change: 27 Jul 1996 2
Kernel Functions for Drivers ddi_dma_buf_bind_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 burstsizesfields 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 usingddi_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 statusDDI_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
SunOS 5.11 Last change: 27 Jul 1996 3
Kernel Functions for Drivers ddi_dma_buf_bind_handle(9F)
system may decide to allocate resources for the entireobject (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 beingavailable. 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 toDDI_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 thespecified function is called, it is passed arg as an argu-
ment. The specified callback function must return eitherDDI_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 becalled 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 accept-
able when partial transfers are per-
mitted by setting the DDI_DMA_PARTIAL
flag in flags.DDI_DMA_INUSE Another I/O transaction is using the
DMA handle.SunOS 5.11 Last change: 27 Jul 1996 4
Kernel Functions for Drivers ddi_dma_buf_bind_handle(9F)
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 configuration.CONTEXT
ddi_dma_buf_bind_handle() can be called from user, kernel,
or interrupt context, except when callback is set toDDI_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 theDDI_DMA_PARTIAL flag, the number of cookies in each window
may exceed the size of the device's scatter/gather list asspecified 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 attributesas 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 usingddi_dma_getwin(9F).
SunOS 5.11 Last change: 27 Jul 1996 5