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

   1 '\" te
   2 .\"  Copyright (c) 2006, 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 SCSI_ALLOC_CONSISTENT_BUF 9F "Jan 16, 2006"
   7 .SH NAME
   8 scsi_alloc_consistent_buf \- allocate an I/O buffer for SCSI DMA
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/scsi/scsi.h>
  13
  14
  15
  16 \fBstruct buf *\fR\fBscsi_alloc_consistent_buf\fR(\fBstructscsi_address*\fR\fIap\fR,
  17      \fBstruct buf *\fR\fIbp\fR, \fBsize_t\fR \fIdatalen\fR, \fBuint_t\fR \fIbflags\fR,
  18      \fBint (*\fR\fIcallback\fR)(caddr_t), \fBcaddr_t\fR \fIarg\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\fIap\fR\fR
  30 .ad
  31 .RS 12n
  32 Pointer to the \fBscsi_address\fR(9S) structure.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIbp\fR\fR
  39 .ad
  40 .RS 12n
  41 Pointer to the \fBbuf\fR(9S) structure.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIdatalen\fR\fR
  48 .ad
  49 .RS 12n
  50 Number of bytes for the data buffer.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIbflags\fR\fR
  57 .ad
  58 .RS 12n
  59 Flags setting for the allocated buffer header. This should either be
  60 \fBB_READ\fR or \fBB_WRITE\fR.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIcallback\fR\fR
  67 .ad
  68 .RS 12n
  69 A pointer to a callback function, \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fIarg\fR\fR
  76 .ad
  77 .RS 12n
  78 The callback function argument.
  79 .RE
  80
  81 .SH DESCRIPTION
  82 .sp
  83 .LP
  84 The \fBscsi_alloc_consistent_buf()\fR function returns allocates a buffer
  85 header and the associated data buffer for direct memory access (DMA) transfer.
  86 This buffer is allocated from the \fBiobp\fR space, which is considered
  87 consistent memory. For more details, see \fBddi_dma_mem_alloc\fR(9F) and
  88 \fBddi_dma_sync\fR(9F).
  89 .sp
  90 .LP
  91 For buffers allocated via \fBscsi_alloc_consistent_buf()\fR, and marked with
  92 the \fBPKT_CONSISTENT\fR flag via \fBscsi_init_pkt\fR(9F), the HBA driver must
  93 ensure that the data transfer for the command is correctly synchronized before
  94 the target driver's command completion callback is performed.
  95 .sp
  96 .LP
  97 If \fIbp\fR is \fINULL\fR, a new buffer header will be allocated using
  98 \fBgetrbuf\fR(9F). In addition, if \fIdatalen\fR is non-zero, a new buffer will
  99 be allocated using \fBddi_dma_mem_alloc\fR(9F).
 100 .sp
 101 .LP
 102 \fIcallback\fR indicates what the allocator routines should do when direct
 103 memory access \fB(DMA)\fR resources are not available; the valid values are:
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBNULL_FUNC\fR\fR
 108 .ad
 109 .RS 16n
 110 Do not wait for resources. Return a \fINULL\fR pointer.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBSLEEP_FUNC\fR\fR
 117 .ad
 118 .RS 16n
 119 Wait indefinitely for resources.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fBOther Values\fR
 126 .ad
 127 .RS 16n
 128 \fIcallback\fR points to a function that is called when resources may become
 129 available. \fIcallback\fR must return either \fB0\fR (indicating that it
 130 attempted to allocate resources but failed to do so), in which case it is put
 131 back on a list to be called again later, or \fB1\fR indicating either success
 132 in allocating resources or indicating that it no longer cares for a retry. The
 133 last argument \fIarg\fR is supplied to the \fIcallback\fR function when it is
 134 invoked.
 135 .RE
 136
 137 .SH RETURN VALUES
 138 .sp
 139 .LP
 140 The \fBscsi_alloc_consistent_buf()\fR function returns a pointer to a
 141 \fBbuf\fR(9S) structure on success. It returns \fBNULL\fR if resources are not
 142 available even if \fIwaitfunc\fR was not \fBSLEEP_FUNC\fR.
 143 .SH CONTEXT
 144 .sp
 145 .LP
 146 If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine may be called only
 147 from user-level code. Otherwise, it may be called fromuser, interrupt, or
 148 kernel context. The \fIcallback\fR function may not block or call routines that
 149 block.
 150 .SH EXAMPLES
 151 .LP
 152 \fBExample 1 \fRAllocate a request sense packet with consistent DMA resources
 153 attached.
 154 .sp
 155 .in +2
 156 .nf
 157    bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL,
 158          SENSE_LENGTH, B_READ, SLEEP_FUNC, NULL);
 159     rqpkt = scsi_init_pkt(&devp->sd_address,
 160          NULL, bp, CDB_GROUP0, 1, 0,
 161          PKT_CONSISTENT, SLEEP_FUNC, NULL);
 162 .fi
 163 .in -2
 164
 165 .LP
 166 \fBExample 2 \fRAllocate an inquiry packet with consistent DMA resources
 167 attached.
 168 .sp
 169 .in +2
 170 .nf
 171     bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL,
 172          SUN_INQSIZE, B_READ, canwait, NULL);
 173     if (bp) {
 174         pkt = scsi_init_pkt(&devp->sd_address, NULL, bp,
 175                 CDB_GROUP0, 1, PP_LEN, PKT_CONSISTENT,
 176                 canwait, NULL);
 177     }
 178 .fi
 179 .in -2
 180
 181 .SH SEE ALSO
 182 .sp
 183 .LP
 184 \fBddi_dma_mem_alloc\fR(9F), \fBddi_dma_sync\fR(9F), \fBgetrbuf\fR(9F),
 185 \fBscsi_destroy_pkt\fR(9F), \fBscsi_init_pkt\fR(9F),
 186 \fBscsi_free_consistent_buf\fR(9F), \fBbuf\fR(9S), \fBscsi_address\fR(9S)
 187 .sp
 188 .LP
 189 \fIWriting Device Drivers\fR