'\" 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]
.TH DDI_DMA_GETWIN 9F "Jan 18, 2020"
.SH NAME
ddi_dma_getwin \- activate a new DMA window
.SH SYNOPSIS
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint\fR \fBddi_dma_getwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBuint_t\fR \fIwin\fR,
     \fBoff_t *\fR\fIoffp\fR, \fBsize_t *\fR\fIlenp\fR, \fBddi_dma_cookie_t\fR \fI*cookiep\fR,
     \fBuint_t *\fR\fIccountp\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH PARAMETERS
.ne 2
.na
\fB\fIhandle\fR \fR
.ad
.RS 12n
The  \fBDMA\fR handle previously allocated by a call to
\fBddi_dma_alloc_handle\fR(9F).
.RE

.sp
.ne 2
.na
\fB\fIwin\fR \fR
.ad
.RS 12n
Number of the window to activate.
.RE

.sp
.ne 2
.na
\fB\fIoffp\fR \fR
.ad
.RS 12n
Pointer to an offset.  Upon a successful return,  \fIoffp\fR will contain the
new offset indicating the  beginning of the window within the object.
.RE

.sp
.ne 2
.na
\fB\fIlenp\fR \fR
.ad
.RS 12n
Upon a successful return,  \fIlenp\fR will contain the size, in bytes, of the
current window.
.RE

.sp
.ne 2
.na
\fB\fIcookiep\fR \fR
.ad
.RS 12n
A pointer to the first \fBddi_dma_cookie\fR(9S) structure.  This should
be left as \fBNULL\fR in new callers.
.RE

.sp
.ne 2
.na
\fB\fIccountp\fR \fR
.ad
.RS 12n
Upon a successful return,  \fIccountp\fR will contain the number of cookies for
this  \fBDMA\fR window.  This can
be left as \fBNULL\fR in new callers.  The cookie count can be obtained
by calling \fBddi_dma_ncookies\fR(9F).
.RE

.SH DESCRIPTION
\fBddi_dma_getwin()\fR activates a new  \fBDMA\fR window. If a  \fBDMA\fR
resource allocation request returns \fBDDI_DMA_PARTIAL_MAP\fR indicating that
resources for less than the entire object were allocated, the current
\fBDMA\fR window can be changed by a call to  \fBddi_dma_getwin()\fR.
.sp
.LP
The caller must first determine the number of  \fBDMA\fR windows,  \fIN\fR,
using \fBddi_dma_numwin\fR(9F). \fBddi_dma_getwin()\fR takes a  \fBDMA\fR
window number from the range  \fI[0..N-1]\fR as the parameter \fIwin\fR and
makes it the current  \fBDMA\fR window.
.sp
.LP
\fBddi_dma_getwin()\fR allocates and assosciates a number of
\fBDMA\fR cookies with \fIhandle\fR.  To get the total number of
cookies, callers should use the \fBddi_dma_ncookies\fR(9F) function. To
get all of the cookies, callers should use the
\fBddi_dma_cookie_iter\fR(9F) or \fBddi_dma_cookie_get\fR(9F) functions.
Callers should pass \fBNULL\fR for \fIcookiep\fR and \fIccountp\fR.
These values are required if using the deprecated
\fBddi_dma_nextcookie\fR(9F) interface, in which case \fIcookiep\fR is
filled in with the first \fBddi_dma_cookie\fR(9S) structure.
.sp
.LP
\fBddi_dma_getwin()\fR 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
\fBddi_dma_sync\fR(9F).
.sp
.LP
\fBddi_dma_getwin()\fR is normally called from an interrupt routine. The first
invocation of the  \fBDMA\fR engine is done from the driver. All subsequent
invocations of the  \fBDMA\fR 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  \fBDMA\fR transfer.
Otherwise, it calls  \fBddi_dma_getwin()\fR to shift the current window and
start another \fBDMA\fR transfer.
.SH RETURN VALUES
\fBddi_dma_getwin()\fR returns:
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR \fR
.ad
.RS 16n
Resources for the specified \fBDMA\fR window are allocated.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR \fR
.ad
.RS 16n
\fIwin\fR is not a valid window index.
.RE

.SH CONTEXT
\fBddi_dma_getwin()\fR can be called from user, kernel, or interrupt context.
.SH SEE ALSO
\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F),
\fBddi_dma_buf_bind_handle\fR(9F),  \fBddi_dma_cookie_get\fR(9F),
.BR ddi_dma_cookie_iter (9F),
.BR ddi_dma_ncookies (9F),
.BR ddi_dma_numwin (9F),
.BR ddi_dma_sync (9F),
.BR ddi_dma_unbind_handle (9F),
.BR ddi_dma_cookie (9S)
.sp
.LP
\fIWriting Device Drivers\fR