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_INIT_PKT 9F "Jan 16, 2006"
   7 .SH NAME
   8 scsi_init_pkt \- prepare a complete SCSI packet
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/scsi/scsi.h>
  13 
  14 
  15 
  16 \fBstruct scsi_pkt *\fR\fBscsi_init_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR,
  17      \fBstruct scsi_pkt *\fR\fIpktp\fR, \fBstruct buf *\fR\fIbp\fR, \fBint\fR \fIcmdlen\fR, \fBint\fR \fIstatuslen\fR,
  18      \fBint\fR \fIprivatelen\fR, \fBint\fR \fIflags\fR, \fBint\fR \fB(*\fRcallback\fB)(caddr_t)\fR, \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 .sp .6
  32 .RS 4n
  33 Pointer to a \fBscsi_address\fR(9S) structure.
  34 .RE
  35 
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIpktp\fR\fR
  40 .ad
  41 .sp .6
  42 .RS 4n
  43 A pointer to a \fBscsi_pkt\fR(9S) structure.
  44 .RE
  45 
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIbp\fR\fR
  50 .ad
  51 .sp .6
  52 .RS 4n
  53 Pointer to a \fBbuf\fR(9S) structure.
  54 .RE
  55 
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIcmdlen\fR\fR
  60 .ad
  61 .sp .6
  62 .RS 4n
  63 The required length for the \fBSCSI \fRcommand descriptor block (\fBCDB\fR) in
  64 bytes.
  65 .RE
  66 
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fIstatuslen\fR\fR
  71 .ad
  72 .sp .6
  73 .RS 4n
  74 The required length for the \fBSCSI \fRstatus completion block (\fBSCB\fR) in
  75 bytes. Valid values are:
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fB0\fR\fR
  80 .ad
  81 .sp .6
  82 .RS 4n
  83 No status back.
  84 .RE
  85 
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fB1\fR\fR
  90 .ad
  91 .sp .6
  92 .RS 4n
  93 Return SCSI status byte.
  94 .RE
  95 
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBsizeof(scsi_arq_status)\fR\fR
 100 .ad
 101 .sp .6
 102 .RS 4n
 103 Return status information in a \fBscsi_arq_status\fR structure. This will
 104 include up to 20 bytes of sense data. Please refer to \fBscsi_arq_status\fR(9S)
 105 for more information.
 106 .sp
 107 For extra sense packets (\fBPKT_XARQ\fR flag asserted), set \fIstatuslen\fR to
 108 be a greater number like, (\fIN\fR + \fBsizeof(struct scsi_arq_status)\fR)
 109 where \fIN\fR is the number of extra bytes beyond the default 20. For example,
 110 \fIN\fR=1 requests 21 bytes of sense, \fIN\fR=235 asks for 255 bytes.
 111 .RE
 112 
 113 .RE
 114 
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fIprivatelen\fR\fR
 119 .ad
 120 .sp .6
 121 .RS 4n
 122 The required length for the \fIpkt_private\fR area.
 123 .RE
 124 
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fIflags\fR\fR
 129 .ad
 130 .sp .6
 131 .RS 4n
 132 Flags modifier.
 133 .RE
 134 
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fIcallback\fR\fR
 139 .ad
 140 .sp .6
 141 .RS 4n
 142 A pointer to a callback function, \fBNULL_FUNC\fR, or \fBSLEEP_FUNC\fR.
 143 .RE
 144 
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fIarg\fR\fR
 149 .ad
 150 .sp .6
 151 .RS 4n
 152 The \fIcallback\fR function argument.
 153 .RE
 154 
 155 .SH DESCRIPTION
 156 .sp
 157 .LP
 158 Target drivers use \fBscsi_init_pkt()\fR to request the transport layer to
 159 allocate and initialize a packet for a \fBSCSI\fR command which possibly
 160 includes a data transfer. If \fIpktp\fR is \fINULL,\fR a new \fBscsi_pkt\fR(9S)
 161 is allocated using the \fBHBA\fR driver's packet allocator. The \fIbp\fR is a
 162 pointer to a \fBbuf\fR(9S) structure. If \fIbp\fR is non-\fINULL\fR and
 163 contains a valid byte count, the \fBbuf\fR(9S) structure is also set up for
 164 \fBDMA \fRtransfer using the \fBHBA\fR driver \fBDMA\fR resources allocator.
 165 When \fIbp\fR is allocated by \fBscsi_alloc_consistent_buf\fR(9F), the
 166 \fBPKT_CONSISTENT\fR bit must be set in the \fIflags\fR argument to ensure
 167 proper operation. If \fIprivatelen\fR is non-zero then additional space is
 168 allocated for the \fIpkt_private\fR area of the \fBscsi_pkt\fR(9S). On return
 169 \fIpkt_private\fR points to this additional space. Otherwise \fIpkt_private\fR
 170 is a pointer that is typically used to store the \fIbp\fR during execution of
 171 the command. In this case \fIpkt_private\fR is \fINULL\fR on return.
 172 .sp
 173 .LP
 174 The \fIflags\fR argument is a set of bit flags. Possible bits include:
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBPKT_CONSISTENT\fR\fR
 179 .ad
 180 .sp .6
 181 .RS 4n
 182 This must be set if the \fBDMA\fR buffer was allocated using
 183 \fBscsi_alloc_consistent_buf\fR(9F). In this case, the \fBHBA\fR driver will
 184 guarantee that the data transfer is properly synchronized before performing the
 185 target driver's command completion callback.
 186 .RE
 187 
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBPKT_DMA_PARTIAL\fR\fR
 192 .ad
 193 .sp .6
 194 .RS 4n
 195 This may be set if the driver can accept a partial \fBDMA\fR mapping. If set,
 196 \fBscsi_init_pkt()\fR will allocate \fBDMA\fR resources with the
 197 \fBDDI_DMA_PARTIAL\fR bit set in the \fBdmar_flag\fR element of the
 198 \fBddi_dma_req\fR(9S) structure. The \fBpkt_resid\fR field of the
 199 \fBscsi_pkt\fR(9S) structure may be returned with a non-zero value, which
 200 indicates the number of bytes for which \fBscsi_init_pkt()\fR was unable to
 201 allocate DMA resources. In this case, a subsequent call to
 202 \fBscsi_init_pkt()\fR may be made for the same \fIpktp\fR and \fIbp\fR to
 203 adjust the DMA resources to the next portion of the transfer. This sequence
 204 should be repeated until the \fBpkt_resid\fR field is returned with a zero
 205 value, which indicates that with transport of this final portion the entire
 206 original request will have been satisfied.
 207 .RE
 208 
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBPKT_XARQ\fR\fR
 213 .ad
 214 .sp .6
 215 .RS 4n
 216 Setting this flag requests that the \fBHBA\fR return  extra sense data for this
 217 \fBscsi_pkt\fR(9S). The default  auto request sense mechanism returns up to  20
 218 bytes. More than 20 bytes of sense data can be requested by setting this flag
 219 and setting the \fIstatuslen\fR correctly. Set the \fIstatuslen\fR to be the
 220 \fBsizeof(struct scsi_arq_status)\fR plus the number of sense bytes needed
 221 beyond 20. For example, set statuslen to be \fB(sizeof(struct scsi_arq_status)
 222 + 5)\fR for 25 bytes of sense.
 223 .RE
 224 
 225 .sp
 226 .LP
 227 When calling \fBscsi_init_pkt()\fR to move already-allocated \fBDMA\fR
 228 resources, the \fIcmdlen\fR, \fIstatuslen\fR, and \fIprivatelen\fR fields are
 229 ignored.
 230 .sp
 231 .LP
 232 The last argument \fIarg\fR is supplied to the \fIcallback\fR function when it
 233 is invoked.
 234 .sp
 235 .LP
 236 \fIcallback\fR indicates what the allocator routines should do when resources
 237 are not available:
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBNULL_FUNC\fR\fR
 242 .ad
 243 .RS 16n
 244 Do not wait for resources. Return a \fINULL\fR pointer.
 245 .RE
 246 
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBSLEEP_FUNC\fR\fR
 251 .ad
 252 .RS 16n
 253 Wait indefinitely for resources.
 254 .RE
 255 
 256 .sp
 257 .ne 2
 258 .na
 259 \fBOther Values\fR
 260 .ad
 261 .RS 16n
 262 \fIcallback\fR points to a function which is called when resources may have
 263 become available. \fIcallback\fR must return either \fB0\fR (indicating that it
 264 attempted to allocate resources but again failed to do so), in which case it is
 265 put back on a list to be called again later, or \fB1\fR indicating either
 266 success in allocating resources or indicating that it no longer cares for a
 267 retry.
 268 .RE
 269 
 270 .sp
 271 .LP
 272 When allocating \fBDMA\fR resources, \fBscsi_init_pkt()\fR returns the
 273 \fBscsi_pkt\fR field \fBpkt_resid\fR as the number of residual bytes for which
 274 the system was unable to allocate \fBDMA\fR resources.  A \fBpkt_resid\fR of
 275 \fB0\fR means that all necessary \fBDMA\fR resources were allocated.
 276 .SH RETURN VALUES
 277 .sp
 278 .LP
 279 The \fBscsi_init_pkt()\fR function returns \fINULL\fR if the packet or
 280 \fBDMA\fR resources could not be allocated. Otherwise, it returns a pointer to
 281 an initialized \fBscsi_pkt\fR(9S). If \fIpktp\fR was not \fINULL\fR the return
 282 value will be \fIpktp\fR on successful initialization of the packet.
 283 .SH CONTEXT
 284 .sp
 285 .LP
 286 If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine can be called only
 287 from user-level code. Otherwise, it can be called from user, interrupt, or
 288 kernel context. The \fIcallback\fR function may not block or call routines that
 289 block.
 290 .SH EXAMPLES
 291 .LP
 292 \fBExample 1 \fRAllocating a Packet Without \fBDMA\fR Resources Attached
 293 .sp
 294 .LP
 295 To allocate a packet without \fBDMA\fR resources attached, use:
 296 
 297 .sp
 298 .in +2
 299 .nf
 300 pkt = scsi_init_pkt(&devp->sd_address, NULL, NULL, CDB_GROUP1,
 301         1, sizeof (struct my_pkt_private *), 0,
 302         sd_runout, sd_unit);
 303 .fi
 304 .in -2
 305 
 306 .LP
 307 \fBExample 2 \fRAllocating a Packet With \fBDMA\fR Resources Attached
 308 .sp
 309 .LP
 310 To allocate a packet with \fBDMA\fR resources attached use:
 311 
 312 .sp
 313 .in +2
 314 .nf
 315 pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP1,
 316         sizeof(struct scsi_arq_status), 0, 0, NULL_FUNC, NULL);
 317 .fi
 318 .in -2
 319 
 320 .LP
 321 \fBExample 3 \fRAttaching \fBDMA\fR Resources to a Preallocated Packet
 322 .sp
 323 .LP
 324 To attach \fBDMA\fR resources to a preallocated packet, use:
 325 
 326 .sp
 327 .in +2
 328 .nf
 329 pkt = scsi_init_pkt(&devp->sd_address, old_pkt, bp, 0,
 330         0, 0, 0, sd_runout, (caddr_t) sd_unit);
 331 .fi
 332 .in -2
 333 
 334 .LP
 335 \fBExample 4 \fRAllocating a Packet with Consistent \fBDMA\fR Resources
 336 Attached
 337 .sp
 338 .LP
 339 Since the packet is already allocated, the \fIcmdlen\fR, \fIstatuslen\fR and
 340 \fIprivatelen\fR are \fB0\fR. To allocate a packet with consistent \fBDMA\fR
 341 resources attached, use:
 342 
 343 .sp
 344 .in +2
 345 .nf
 346 bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL,
 347                SENSE_LENGTH, B_READ, SLEEP_FUNC, NULL);
 348         pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP0,
 349         sizeof(struct scsi_arq_status), sizeof (struct my_pkt_private *),
 350         PKT_CONSISTENT, SLEEP_FUNC, NULL);
 351 .fi
 352 .in -2
 353 
 354 .LP
 355 \fBExample 5 \fRAllocating a Packet with Partial \fBDMA\fR Resources Attached
 356 .sp
 357 .LP
 358 To allocate a packet with partial \fBDMA\fR resources attached, use:
 359 
 360 .sp
 361 .in +2
 362 .nf
 363 my_pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP0,
 364           1, sizeof (struct buf *), PKT_DMA_PARTIAL,
 365           SLEEP_FUNC, NULL);
 366 .fi
 367 .in -2
 368 
 369 .SH SEE ALSO
 370 .sp
 371 .LP
 372 \fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F),
 373 \fBscsi_dmaget\fR(9F), \fBscsi_pktalloc\fR(9F), \fBbuf\fR(9S),
 374 \fBddi_dma_req\fR(9S), \fBscsi_address\fR(9S), \fBscsi_pkt\fR(9S)
 375 .sp
 376 .LP
 377 \fIWriting Device Drivers\fR
 378 .SH NOTES
 379 .sp
 380 .LP
 381 If a \fBDMA\fR allocation request fails with \fBDDI_DMA_NOMAPPING\fR, the
 382 \fBB_ERROR\fR flag will be set in \fIbp\fR, and the \fBb_error\fR field will be
 383 set to \fBEFAULT\fR.
 384 .sp
 385 .LP
 386 If a \fBDMA\fR allocation request fails with \fBDDI_DMA_TOOBIG\fR, the
 387 \fBB_ERROR\fR flag will be set in \fIbp\fR, and the \fBb_error\fR field will be
 388 set to \fBEINVAL\fR.