Tribblix: manual page: ddi_dma

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

illumos DDI specific (illumos 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.
This should be left as NULL in new callers.

ccountp
Upon a successful return, ccountp will contain the
number of cookies for this DMA window. This can be left
as NULL in new callers. The cookie count can be obtained
by calling ddi_dma_ncookies(9F).

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() allocates and assosciates a number of DMA cookies
with handle. To get the total number of cookies, callers should use
the ddi_dma_ncookies(9F) function. To get all of the cookies, callers
should use the ddi_dma_cookie_iter(9F) or ddi_dma_cookie_get(9F)
functions. Callers should pass NULL for cookiep and ccountp. These
values are required if using the deprecated ddi_dma_nextcookie(9F)
interface, in which case cookiep is filled in with the first
ddi_dma_cookie(9S) structure.

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
subsequent invocations of the DMA engine are done from the interrupt
routine. The interrupt routine checks to see if the request has been
completed. 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.