'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc.
.TH ddi_dma_movwin 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_dma_movwin \- shift current DMA window
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint\fR \fBddi_dma_movwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBoff_t *\fR\fIoffp\fR, 
     \fBuint_t *\fR\fIlenp\fR, \fBddi_dma_cookie_t *\fR\fIcookiep\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
This interface is obsolete. \fBddi_dma_getwin\fR(9F) should be used instead.
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIhandle\fR\fR
.ad
.RS 11n
.rt  
The \fBDMA\fR handle filled in by a call to \fBddi_dma_setup\fR(9F).
.RE

.sp
.ne 2
.mk
.na
\fB\fIoffp\fR\fR
.ad
.RS 11n
.rt  
A pointer to an offset to set the \fBDMA\fR window to. Upon a successful return, it will be filled in with the new offset from the beginning of the object resources are allocated for.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlenp\fR\fR
.ad
.RS 11n
.rt  
A pointer to a value which must either be the current size of the \fBDMA\fR window (as known from a call to \fBddi_dma_curwin\fR(9F) or from a previous call to \fBddi_dma_movwin()\fR). Upon a successful return, it will be filled in with the size, in bytes, of the current window.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcookiep\fR\fR
.ad
.RS 11n
.rt  
A pointer to a \fBDMA\fR cookie (see \fBddi_dma_cookie\fR(9S)). Upon a successful return, cookiep is filled in just as if an implicit \fBddi_dma_htoc\fR(9F) had been made.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_dma_movwin()\fR function shifts the current \fBDMA\fR window. If a \fBDMA\fR request allows the system to allocate resources for less than the entire object by setting the \fBDDI_DMA_PARTIAL\fR flag in the \fBddi_dma_req\fR(9S) structure, the current \fBDMA\fR window can be shifted by a call to \fBddi_dma_movwin()\fR. 
.sp
.LP
The caller must first determine the current \fBDMA\fR window size by a call to \fBddi_dma_curwin\fR(9F). Using the current offset and size of the window thus retrieved, the caller of \fBddi_dma_movwin()\fR may change the window onto the object by changing the offset by a value which is some multiple of the size of the \fBDMA\fR window.
.sp
.LP
The \fBddi_dma_movwin()\fR function takes care of underlying resource synchronizations required to \fBshift\fR the window. However, if you want to \fBaccess\fR the data prior to or after moving the window, further synchronizations using \fBddi_dma_sync\fR(9F) are required.
.sp
.LP
This function 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, it returns without invoking another \fBDMA\fR transfer. Otherwise it calls \fBddi_dma_movwin()\fR to shift the current window and starts another \fBDMA\fR transfer.
.SH RETURN VALUES
.sp
.LP
The \fBddi_dma_movwin()\fR function returns:
.sp
.ne 2
.mk
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
.rt  
The current length and offset are legal and have been set.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
.rt  
Otherwise.
.RE

.SH CONTEXT
.sp
.LP
The \fBddi_dma_movwin()\fR function can be called from user, interrupt, or kernel context.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR
_
Stability LevelObsolete
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBddi_dma_curwin\fR(9F), \fBddi_dma_getwin\fR(9F), \fBddi_dma_htoc\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_cookie\fR(9S), \fBddi_dma_req\fR(9S) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR
.SH WARNINGS
.sp
.LP
The caller must guarantee that the resources used by the object are inactive prior to calling this function.