usr/src/man/man9f/ddi_dma_getwin.9f

   1 '\" te
   2 .\"  Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DDI_DMA_GETWIN 9F "Nov 15, 1996"
   7 .SH NAME
   8 ddi_dma_getwin \- activate a new DMA window
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBddi_dma_getwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBuint_t\fR \fIwin\fR,
  18      \fBoff_t *\fR\fIoffp\fR, \fBsize_t *\fR\fIlenp\fR, \fBddi_dma_cookie_t\fR \fI*cookiep\fR,
  19      \fBuint_t *\fR\fIccountp\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI).
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIhandle\fR \fR
  31 .ad
  32 .RS 12n
  33 The  \fBDMA\fR handle previously allocated by a call to
  34 \fBddi_dma_alloc_handle\fR(9F).
  35 .RE
  36
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIwin\fR \fR
  41 .ad
  42 .RS 12n
  43 Number of the window to activate.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIoffp\fR \fR
  50 .ad
  51 .RS 12n
  52 Pointer to an offset.  Upon a successful return,  \fIoffp\fR will contain the
  53 new offset indicating the  beginning of the window within the object.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIlenp\fR \fR
  60 .ad
  61 .RS 12n
  62 Upon a successful return,  \fIlenp\fR will contain the size, in bytes, of the
  63 current window.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIcookiep\fR \fR
  70 .ad
  71 .RS 12n
  72 A pointer to the first  \fBddi_dma_cookie\fR(9S) structure.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fIccountp\fR \fR
  79 .ad
  80 .RS 12n
  81 Upon a successful return,  \fIccountp\fR will contain the number of cookies for
  82 this  \fBDMA\fR window.
  83 .RE
  84
  85 .SH DESCRIPTION
  86 .sp
  87 .LP
  88 \fBddi_dma_getwin()\fR activates a new  \fBDMA\fR window. If a  \fBDMA\fR
  89 resource allocation request returns \fBDDI_DMA_PARTIAL_MAP\fR indicating that
  90 resources for less than the entire object were allocated, the current
  91 \fBDMA\fR window can be changed by a call to  \fBddi_dma_getwin()\fR.
  92 .sp
  93 .LP
  94 The caller must first determine the number of  \fBDMA\fR windows,  \fIN\fR,
  95 using \fBddi_dma_numwin\fR(9F). \fBddi_dma_getwin()\fR takes a  \fBDMA\fR
  96 window number from the range  \fI[0..N-1]\fR as the parameter \fIwin\fR and
  97 makes it the current  \fBDMA\fR window.
  98 .sp
  99 .LP
 100 \fBddi_dma_getwin()\fR fills in the first \fBDMA\fR cookie pointed to by
 101 \fIcookiep\fR with the appropriate address, length, and bus type.
 102 \fB*\fR\fIccountp\fR is set to the number of \fBDMA\fR cookies representing
 103 this \fBDMA \fRobject. Subsequent \fBDMA\fR cookies must be retrieved using
 104 \fBddi_dma_nextcookie\fR(9F).
 105 .sp
 106 .LP
 107 \fBddi_dma_getwin()\fR takes care of underlying resource synchronizations
 108 required to shift the window. However accessing the data prior to or after
 109 moving the window requires further synchronization steps using
 110 \fBddi_dma_sync\fR(9F).
 111 .sp
 112 .LP
 113 \fBddi_dma_getwin()\fR is normally called from an interrupt routine. The first
 114 invocation of the  \fBDMA\fR engine is done from the driver. All subsequent
 115 invocations of the  \fBDMA\fR engine are done from the interrupt routine. The
 116 interrupt routine checks to see if the request has been completed. If it has,
 117 the interrupt routine returns without invoking another  \fBDMA\fR transfer.
 118 Otherwise, it calls  \fBddi_dma_getwin()\fR to shift the current window and
 119 start another \fBDMA\fR transfer.
 120 .SH RETURN VALUES
 121 .sp
 122 .LP
 123 \fBddi_dma_getwin()\fR returns:
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBDDI_SUCCESS\fR \fR
 128 .ad
 129 .RS 16n
 130 Resources for the specified \fBDMA\fR window are allocated.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBDDI_FAILURE\fR \fR
 137 .ad
 138 .RS 16n
 139 \fIwin\fR is not a valid window index.
 140 .RE
 141
 142 .SH CONTEXT
 143 .sp
 144 .LP
 145 \fBddi_dma_getwin()\fR can be called from user, kernel, or interrupt context.
 146 .SH SEE ALSO
 147 .sp
 148 .LP
 149 \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F),
 150 \fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_nextcookie\fR(9F),
 151 \fBddi_dma_numwin\fR(9F), \fBddi_dma_sync\fR(9F),
 152 \fBddi_dma_unbind_handle\fR(9F), \fBddi_dma_cookie\fR(9S)
 153 .sp
 154 .LP
 155 \fIWriting Device Drivers\fR