ddi_dma_getwin(9F) Kernel Functions for Drivers ddi_dma_getwin(9F)
NAME
ddi_dma_getwin - activate a new DMA window
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_dma_getwin(ddi_dma_handle_t handle, uint_t win, off_t *offp, size_t *lenp, 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).
win Number of the window to activate.
offp Pointer to an offset. Upon a successful return, offp will contain the new offset indicating the
beginning of the window within the object.
lenp Upon a successful return, lenp will contain the size, in bytes, of the current window.
cookiep A pointer to the first ddi_dma_cookie(9S) structure.
ccountp Upon a successful return, ccountp will contain the number of cookies for this DMA window.
DESCRIPTION
ddi_dma_getwin() activates a new DMA window. If a DMA resource allocation request returns DDI_DMA_PARTIAL_MAP indicating that resources
for less than the entire object were allocated, the current DMA window can be changed by a call to ddi_dma_getwin().
The caller must first determine the number of DMA windows, N, using ddi_dma_numwin(9F). ddi_dma_getwin() takes a DMA window number from
the range [0..N-1] as the parameter win and makes it the current DMA window.
ddi_dma_getwin() 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 using ddi_dma_nextcookie(9F).
ddi_dma_getwin() takes care of underlying resource synchronizations required to shift the window. However accessing the data prior to or
after moving the window requires further synchronization steps using ddi_dma_sync(9F).
ddi_dma_getwin() is normally called from an interrupt routine. The first invocation of the DMA engine is done from the driver. All subse-
quent invocations of the DMA engine are done from the interrupt routine. The interrupt routine checks to see if the request has been com-
pleted. If it has, the interrupt routine returns without invoking another DMA transfer. Otherwise, it calls ddi_dma_getwin() to shift the
current window and start another DMA transfer.
RETURN VALUES
ddi_dma_getwin() returns:
DDI_SUCCESS Resources for the specified DMA window are allocated.
DDI_FAILURE win is not a valid window index.
CONTEXT
ddi_dma_getwin() can be called from user, kernel, or interrupt context.
SEE ALSO
ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F), ddi_dma_buf_bind_handle(9F), ddi_dma_nextcookie(9F), ddi_dma_numwin(9F),
ddi_dma_sync(9F), ddi_dma_unbind_handle(9F), ddi_dma_cookie(9S)
Writing Device Drivers
SunOS 5.10 15 Nov 1996 ddi_dma_getwin(9F)
