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

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