man/man9f/ddi_dma_getwin.9f

         te
 Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 DDI_DMA_GETWIN 9F "Jan 18, 2020"
 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.
 SEE ALSO
ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F),
ddi_dma_buf_bind_handle(9F), ddi_dma_cookie_get(9F),
 ddi_dma_cookie_iter (9F),  ddi_dma_ncookies (9F),  ddi_dma_numwin (9F),  ddi_dma_sync (9F),  ddi_dma_unbind_handle (9F),  ddi_dma_cookie (9S)
Writing Device Drivers