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

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.,
   3 .\" All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH SCSI_PKTALLOC 9F "Jan 16, 2006"
   8 .SH NAME
   9 scsi_pktalloc, scsi_resalloc, scsi_pktfree, scsi_resfree \- SCSI packet utility
  10 routines
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/scsi/scsi.h>
  15
  16 \fBstruct scsi_pkt *\fR\fBscsi_pktalloc\fR (\fBstruct scsi_address*\fR \fIap\fR, \fBint\fR \fIcmdlen\fR,
  17      \fBint\fR \fIstatuslen\fR, \fBint\fR (\fI*callback\fR)(\fIvoid\fR));
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBstruct scsi_pkt *\fR\fBscsi_resalloc\fR (\fBstruct scsi_address*\fR \fIap\fR, \fBint\fR \fIcmdlen\fR,
  23      \fBint\fR \fIstatuslen\fR, \fBopaque_t\fR \fIdmatoken\fR, \fBint\fR (\fI*callback\fR)(\fIvoid\fR));
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBscsi_pktfree\fR (\fBstruct scsi_pkt*\fR \fIpkt\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBvoid\fR \fBscsi_resfree\fR (\fBstruct scsi_pkt*\fR \fIpkt\fR);
  34 .fi
  35
  36 .SH INTERFACE LEVEL
  37 .sp
  38 .LP
  39 The \fBscsi_pktalloc()\fR, \fBscsi_pktfree()\fR, \fBscsi_resalloc()\fR, and
  40 \fBscsi_resfree()\fR functions are obsolete. The \fBscsi_pktalloc()\fR and
  41 \fBscsi_resalloc()\fR functions have been replaced by \fBscsi_init_pkt\fR(9F).
  42 The \fBscsi_pktfree()\fR and \fBscsi_resfree()\fR functions have been replaced
  43 by \fBscsi_destroy_pkt\fR(9F).
  44 .SH PARAMETERS
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIap\fR\fR
  49 .ad
  50 .RS 13n
  51 Pointer to a \fBscsi_address\fR structure.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIcmdlen\fR\fR
  58 .ad
  59 .RS 13n
  60 The required length for the \fBSCSI \fRcommand descriptor block (\fBCDB\fR) in
  61 bytes.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fIstatuslen\fR\fR
  68 .ad
  69 .RS 13n
  70 The required length for the \fBSCSI\fR status completion block (\fBSCB\fR) in
  71 bytes.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIdmatoken\fR\fR
  78 .ad
  79 .RS 13n
  80 Pointer to an implementation-dependent object.
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fIcallback\fR\fR
  87 .ad
  88 .RS 13n
  89 A pointer to a callback function, or \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fIpkt\fR\fR
  96 .ad
  97 .RS 13n
  98 Pointer to a \fBscsi_pkt\fR(9S) structure.
  99 .RE
 100
 101 .SH DESCRIPTION
 102 .sp
 103 .LP
 104 The \fBscsi_pktalloc()\fR function requests the host adapter driver to allocate
 105 a command packet. For commands that have a data transfer associated with them,
 106 \fBscsi_resalloc()\fR should be used.
 107 .sp
 108 .LP
 109 \fIap\fR is a pointer to a \fBscsi_address\fR structure. Allocator routines use
 110 it to determine the associated host adapter.
 111 .sp
 112 .LP
 113 The \fIcmdlen\fR parameter is the required length for the \fBSCSI \fRcommand
 114 descriptor block. This block is allocated such that a kernel virtual address is
 115 established in the \fBpkt_cdbp\fR field of the allocated \fBscsi_pkt\fR
 116 structure.
 117 .sp
 118 .LP
 119 \fIstatuslen\fR is the required length for the \fBSCSI \fRstatus completion
 120 block. The address of the allocated block is placed into the \fBpkt_scbp\fR
 121 field of the \fBscsi_pkt\fR structure.
 122 .sp
 123 .LP
 124 The \fIdmatoken\fR parameter is a pointer to an implementation dependent object
 125 which defines the length, direction, and address of the data transfer
 126 associated with this \fBSCSI\fR packet (command). The \fIdmatoken\fR must be a
 127 pointer to a \fBbuf\fR(9S) structure. If \fIdmatoken\fR is \fINULL\fR, no
 128 \fBDMA\fR resources are required by this \fBSCSI\fR command, so none are
 129 allocated. Only one transfer direction is allowed per command. If there is an
 130 unexpected data transfer phase (either no data transfer phase expected, or the
 131 wrong direction encountered), the command is terminated with the
 132 \fBpkt_reason\fR set to \fBCMD_DMA_DERR\fR. \fIdmatoken\fR provides the
 133 information to determine if the transfer count is correct.
 134 .sp
 135 .LP
 136 \fIcallback\fR indicates what the allocator routines should do when resources
 137 are not available:
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBNULL_FUNC\fR\fR
 142 .ad
 143 .RS 16n
 144 Do not wait for resources. Return a \fINULL\fR pointer.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBSLEEP_FUNC\fR\fR
 151 .ad
 152 .RS 16n
 153 Wait indefinitely for resources.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fBOther Values\fR
 160 .ad
 161 .RS 16n
 162 \fIcallback\fR points to a function which is called when resources may have
 163 become available. \fIcallback\fR must return either \fB0\fR (indicating that it
 164 attempted to allocate resources but again failed to do so), in which case it is
 165 put back on a list to be called again later, or \fB1\fR indicating either
 166 success in allocating resources or indicating that it no longer cares for a
 167 retry.
 168 .RE
 169
 170 .sp
 171 .LP
 172 The \fBscsi_pktfree()\fR function frees the packet.
 173 .sp
 174 .LP
 175 The \fBscsi_resfree()\fR function free all resources held by the packet and the
 176 packet itself.
 177 .SH RETURN VALUES
 178 .sp
 179 .LP
 180 Both allocation routines return a pointer to a \fBscsi_pkt\fR structure on
 181 success, or \fINULL\fR on failure.
 182 .SH CONTEXT
 183 .sp
 184 .LP
 185 If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine can be called only
 186 from user or kernel context. Otherwise, it can be called from user, kernel, or
 187 interrupt context. The \fIcallback\fR function may not block or call routines
 188 that block. Both deallocation routines can be called from user, kernel, or
 189 interrupt context.
 190 .SH ATTRIBUTES
 191 .sp
 192 .LP
 193 See \fBattributes\fR(5) for a description of the following attributes:
 194 .sp
 195
 196 .sp
 197 .TS
 198 box;
 199 c | c
 200 l | l .
 201 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 202 _
 203 Stability Level Obsolete
 204 .TE
 205
 206 .SH SEE ALSO
 207 .sp
 208 .LP
 209 \fBattributes\fR(5), \fBscsi_dmafree\fR(9F), \fBscsi_dmaget\fR(9F),
 210 \fBbuf\fR(9S), \fBscsi_pkt\fR(9S)
 211 .sp
 212 .LP
 213 \fIWriting Device Drivers\fR
 214 .SH NOTES
 215 .sp
 216 .LP
 217 The \fBscsi_pktalloc()\fR, \fBscsi_pktfree()\fR, \fBscsi_resalloc()\fR, and
 218 \fBscsi_resfree()\fR functions are obsolete and will be discontinued in a
 219 future release. The \fBscsi_pktalloc()\fR and \fBscsi_resalloc()\fR functions
 220 have been replaced by \fBscsi_init_pkt\fR(9F). The \fBscsi_pktfree()\fR and
 221 \fBscsi_resfree()\fR functions have been replaced by
 222 \fBscsi_destroy_pkt\fR(9F).