usr/src/man/man9f/ddi_dma_alloc_handle.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_ALLOC_HANDLE 9F "Sep 22, 1996"
   7 .SH NAME
   8 ddi_dma_alloc_handle \- allocate DMA handle
   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_alloc_handle\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIattr\fR,
  18      \fBint  (*\fR\fIcallback\fR) (caddr_t), \fBcaddr_t\fR \fIarg\fR, \fBddi_dma_handle_t *\fR\fIhandlep\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIdip\fR\fR
  30 .ad
  31 .RS 12n
  32 Pointer to the device's  \fBdev_info\fR structure.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIattr\fR\fR
  39 .ad
  40 .RS 12n
  41 Pointer to a  \fBDMA\fR attribute structure for this device (see
  42 \fBddi_dma_attr\fR(9S)).
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIcallback\fR\fR
  49 .ad
  50 .RS 12n
  51 The address of a function to call back later if resources aren't available now.
  52 The following special function addresses may also be used.
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBDDI_DMA_SLEEP\fR\fR
  57 .ad
  58 .RS 20n
  59 Wait until resources are available.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBDDI_DMA_DONTWAIT\fR\fR
  66 .ad
  67 .RS 20n
  68 Do not wait until resources are available and do not schedule a callback.
  69 .RE
  70
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fIarg\fR\fR
  77 .ad
  78 .RS 12n
  79 Argument to be passed to a callback function, if such a function is specified.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fIhandlep\fR\fR
  86 .ad
  87 .RS 12n
  88 Pointer to the  \fBDMA\fR handle to be initialized.
  89 .RE
  90
  91 .SH DESCRIPTION
  92 .sp
  93 .LP
  94 \fBddi_dma_alloc_handle()\fR allocates a new  \fBDMA\fR handle. A  \fBDMA\fR
  95 handle is an opaque object used as a reference to subsequently allocated
  96 \fBDMA\fR resources.   \fBddi_dma_alloc_handle()\fR accepts as parameters the
  97 device information referred to by  \fIdip\fR and the device's  \fBDMA\fR
  98 attributes described by a \fBddi_dma_attr\fR(9S) structure. A successful call
  99 to \fBddi_dma_alloc_handle()\fR fills in the value pointed to by
 100 \fIhandlep\fR. A  \fBDMA\fR handle must only be used by the device for which it
 101 was allocated and is only valid for one  I/O transaction at a time.
 102 .sp
 103 .LP
 104 The callback function, \fIcallback\fR, indicates how a caller wants to handle
 105 the possibility of resources not being available. If  \fIcallback\fR is set to
 106 \fBDDI_DMA_DONTWAIT\fR, then the caller does not care if the allocation fails,
 107 and can handle an allocation failure appropriately. If  \fIcallback\fR is set
 108 to  \fBDDI_DMA_SLEEP\fR, then the caller wishes to have the allocation routines
 109 wait for resources to become available. If any other value is set, and a
 110 \fBDMA\fR resource allocation fails, this value is assumed to be a function to
 111 call at a later time when resources may become available. When the specified
 112 function is called, it is passed \fIarg\fR as an argument. The specified
 113 callback function must return either \fBDDI_DMA_CALLBACK_RUNOUT\fR or
 114 \fBDDI_DMA_CALLBACK_DONE\fR. \fBDDI_DMA_CALLBACK_RUNOUT\fR indicates that the
 115 callback routine attempted to allocate \fBDMA\fR resources but failed to do so,
 116 in which case the callback function is put back on a list to be called again
 117 later.  \fBDDI_DMA_CALLBACK_DONE\fR indicates either success at allocating
 118 \fBDMA\fR resources or the driver no longer wishes to retry.
 119 .sp
 120 .LP
 121 The callback function is called in interrupt context. Therefore, only system
 122 functions that are accessible from interrupt context  is available. The
 123 callback function must take whatever steps necessary to protect its critical
 124 resources, data structures, queues, and so forth.
 125 .sp
 126 .LP
 127 When a  \fBDMA\fR handle is no longer needed, \fBddi_dma_free_handle\fR(9F)
 128 must be called to free the handle.
 129 .SH RETURN VALUES
 130 .sp
 131 .LP
 132 \fBddi_dma_alloc_handle()\fR returns:
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBDDI_SUCCESS\fR\fR
 137 .ad
 138 .RS 23n
 139 Successfully allocated a new \fBDMA\fR handle.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBDDI_DMA_BADATTR\fR\fR
 146 .ad
 147 .RS 23n
 148 The attributes specified in the \fBddi_dma_attr\fR(9S) structure make it
 149 impossible for the system to allocate potential  \fBDMA\fR resources.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fBDDI_DMA_NORESOURCES\fR\fR
 156 .ad
 157 .RS 23n
 158 No resources are available.
 159 .RE
 160
 161 .SH CONTEXT
 162 .sp
 163 .LP
 164 \fBddi_dma_alloc_handle()\fR can be called from user, kernel, or interrupt
 165 context, except when \fIcallback\fR is set to  \fBDDI_DMA_SLEEP\fR, in which
 166 case it can be called from user or kernel context only.
 167 .SH SEE ALSO
 168 .sp
 169 .LP
 170 \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F),
 171 \fBddi_dma_burstsizes\fR(9F), \fBddi_dma_free_handle\fR(9F),
 172 \fBddi_dma_unbind_handle\fR(9F), \fBddi_dma_attr\fR(9S)
 173 .sp
 174 .LP
 175 \fIWriting Device Drivers\fR