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

   1 '\" te
   2 .\"  Copyright (c) 2003, 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_UMEM_IOSETUP 9F "Feb 4, 2003"
   7 .SH NAME
   8 ddi_umem_iosetup \- Setup I/O requests to application memory
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBstruct buf *\fR\fBddi_umem_iosetup\fR(\fBddi_umem_cookie_t\fR \fIcookie,\fRoff_t off,
  18      size_t \fIlen\fR, int \fIdirection\fR, dev_t \fIdev\fR, daddr_t \fIblkno\fR,
  19      int (*iodone) (struct buf *), int \fIsleepflag\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\fIcookie\fR \fR
  31 .ad
  32 .RS 14n
  33 The kernel memory cookie allocated by \fBddi_umem_lock\fR(9F).
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIoff\fR \fR
  40 .ad
  41 .RS 14n
  42 Offset from the start of the cookie.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIlen\fR \fR
  49 .ad
  50 .RS 14n
  51 Length of the I/O request in bytes.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIdirection\fR \fR
  58 .ad
  59 .RS 14n
  60 Must be set to \fBB_READ\fR for reads from the device or \fBB_WRITE\fR for
  61 writes to the device.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fIdev\fR \fR
  68 .ad
  69 .RS 14n
  70 Device number
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fIblkno\fR \fR
  77 .ad
  78 .RS 14n
  79 Block number on device.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fIiodone\fR \fR
  86 .ad
  87 .RS 14n
  88 Specific \fBbiodone\fR(9F) routine.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIsleepflag\fR \fR
  95 .ad
  96 .RS 14n
  97 Determines whether caller can sleep for memory. Possible flags are
  98 \fBDDI_UMEM_SLEEP\fR to allow sleeping until memory is available, or
  99 \fBDDI_UMEM_NOSLEEP\fR to return \fBNULL\fR immediately if memory is not
 100 available.
 101 .RE
 102
 103 .SH DESCRIPTION
 104 .sp
 105 .LP
 106 The \fBddi_umem_iosetup\fR(9F) function is used by drivers to setup I/O
 107 requests to application memory which has been locked down using
 108 \fBddi_umem_lock\fR(9F).
 109 .sp
 110 .LP
 111 The \fBddi_umem_iosetup\fR(9F) function returns a pointer to a \fBbuf\fR(9S)
 112 structure corresponding to the memory cookie \fBcookie\fR. Drivers can setup
 113 multiple buffer structures simultaneously active using the same memory cookie.
 114 The \fBbuf\fR(9S) structures can span all or part of the region represented by
 115 the cookie and can overlap each other. The \fBbuf\fR(9S) structure can be
 116 passed to \fBddi_dma_buf_bind_handle\fR(9F) to initiate DMA transfers to or
 117 from the locked down memory.
 118 .sp
 119 .LP
 120 The \fIoff \fR parameter specifies the offset from the start of the cookie. The
 121 \fIlen\fR parameter represents the length of region to be mapped by the buffer.
 122 The \fIdirection\fR parameter must be set to either \fBB_READ\fR or
 123 \fBB_WRITE\fR, to indicate the action that will be performed by the device.
 124 (Note that this direction is in the opposite sense of the VM system's direction
 125 of \fBDDI_UMEMLOCK_READ\fR and \fBDDI_UMEMLOCK_WRITE\fR.) The direction must be
 126 compatible with the flags used to create the memory cookie in
 127 \fBddi_umem_lock\fR(9F). For example, if \fBddi_umem_lock()\fR is called with
 128 the \fIflags\fR parameter set to DDI_UMEMLOCK_READ, the \fIdirection\fR
 129 parameter in \fBddi_umem_iosetup()\fR should be set to \fBB_WRITE\fR.
 130 .sp
 131 .LP
 132 The \fIdev\fR parameter specifies the device to which the buffer is to perform
 133 I/O.The \fIblkno\fR parameter represents the block number on the device. It
 134 will be assigned to the \fBb_blkno\fR field of the returned buffer structure.
 135 The \fIiodone\fR parameter enables the driver to identify a specific
 136 \fBbiodone\fR(9F) routine to be called by the driver when the I/O is complete.
 137 The \fIsleepflag \fR parameter determines if the caller can sleep for memory.
 138 \fBDDI_UMEM_SLEEP\fR allocations may sleep but are guaranteed to succeed.
 139 \fBDDI_UMEM_NOSLEEP\fR allocations do not sleep but may fail (return
 140 \fBNULL\fR) if memory is currently not available.
 141 .sp
 142 .LP
 143 After the I/O has completed and the buffer structure is no longer needed, the
 144 driver calls \fBfreerbuf\fR(9F) to free the buffer structure.
 145 .SH RETURN VALUES
 146 .sp
 147 .LP
 148 The \fBddi_umem_iosetup\fR(9F) function returns a pointer to the initialized
 149 buffer header, or \fBNULL\fR if no space is available.
 150 .SH CONTEXT
 151 .sp
 152 .LP
 153 The \fBddi_umem_iosetup\fR(9F) function can be called from any context only if
 154 flag is set to \fBDDI_UMEM_NOSLEEP\fR. If \fBDDI_UMEM_SLEEP\fR is set,
 155 \fBddi_umem_iosetup\fR(9F) can be called from user and kernel context only.
 156 .SH SEE ALSO
 157 .sp
 158 .LP
 159 \fBddi_umem_lock\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), \fBfreerbuf\fR(9F),
 160 \fBphysio\fR(9F), \fBbuf\fR(9S)