share/man/man9e/tran_init_pkt.9e

   1 '\" te
   2 .\"  Copyright (c) 2009, 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 TRAN_INIT_PKT 9E "Jan 11, 2009"
   7 .SH NAME
   8 tran_init_pkt, tran_destroy_pkt \- SCSI HBA packet preparation and deallocation
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/scsi/scsi.h>
  13
  14 \fBstruct scsi_pkt *prefix\fR\fBtran_init_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR,
  15      \fBstruct scsi_pkt *\fR\fIpkt\fR, \fBstruct buf *\fR\fIbp\fR, \fBint\fR \fIcmdlen\fR,
  16      \fBint\fR \fIstatuslen\fR, \fBint\fR \fItgtlen\fR, \fBint\fR\fIflags\fR, \fBint (*\fR\fIcallback\fR,
  17      \fBcaddr_t),caddr_t\fR \fIarg\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBvoid prefix\fR\fBtran_destroy_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR,
  23      \fBstruct scsi_pkt *\fR\fIpkt\fR);
  24 .fi
  25
  26 .SH INTERFACE LEVEL
  27 .sp
  28 .LP
  29 Solaris architecture specific (Solaris DDI).
  30 .SH PARAMETERS
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIap\fR\fR
  35 .ad
  36 .RS 13n
  37 Pointer to a \fBscsi_address\fR(9S) structure.
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fIpkt\fR\fR
  44 .ad
  45 .RS 13n
  46 Pointer to a \fBscsi_pkt\fR(9S) structure allocated in an earlier call, or
  47 \fINULL\fR.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIbp\fR\fR
  54 .ad
  55 .RS 13n
  56 Pointer to a \fBbuf\fR(9S) structure if \fBDMA \fRresources are to be allocated
  57 for the \fIpkt\fR, or \fINULL\fR.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIcmdlen\fR\fR
  64 .ad
  65 .RS 13n
  66 The required length for the \fBSCSI \fRcommand descriptor block (\fBCDB\fR) in
  67 bytes.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fIstatuslen\fR\fR
  74 .ad
  75 .RS 13n
  76 The required length for the \fBSCSI \fRstatus completion block (\fBSCB\fR) in
  77 bytes.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fItgtlen\fR\fR
  84 .ad
  85 .RS 13n
  86 The length of the packet private area within the \fBscsi_pkt\fR to be allocated
  87 on behalf of the \fBSCSI \fRtarget driver.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fIflags\fR\fR
  94 .ad
  95 .RS 13n
  96 Flags for creating the packet.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fIcallback\fR\fR
 103 .ad
 104 .RS 13n
 105 Pointer to either \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fIarg\fR\fR
 112 .ad
 113 .RS 13n
 114 Always \fINULL\fR.
 115 .RE
 116
 117 .SH DESCRIPTION
 118 .sp
 119 .LP
 120 The \fBtran_init_pkt()\fR and \fBtran_destroy_pkt()\fR vectors in the
 121 \fBscsi_hba_tran\fR structure must be initialized during the \fBHBA \fRdriver's
 122 \fBattach\fR(9E) to point to \fBHBA \fRentry points to be called when a target
 123 driver calls \fBscsi_init_pkt\fR(9F) and \fBscsi_destroy_pkt\fR(9F).
 124 .SS "\fBtran_init_pkt()\fR"
 125 .sp
 126 .LP
 127 \fBtran_init_pkt()\fR is the entry point into the \fBHBA \fRwhich is used to
 128 allocate and initialize a \fBscsi_pkt\fR structure on behalf of a \fBSCSI
 129 \fRtarget driver. If \fIpkt\fR is \fINULL,\fR the \fBHBA \fRdriver must use
 130 \fBscsi_hba_pkt_alloc\fR(9F) to allocate a new \fBscsi_pkt\fR structure.
 131 .sp
 132 .LP
 133 If \fIbp\fR is non-\fINULL\fR, the \fBHBA \fRdriver must allocate appropriate
 134 \fBDMA \fRresources for the \fIpkt\fR, for example,
 135 through \fBddi_dma_buf_setup\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F).
 136 .sp
 137 .LP
 138 If the \fBPKT_CONSISTENT\fR bit is set in \fIflags\fR, the buffer was allocated
 139 by \fBscsi_alloc_consistent_buf\fR(9F). For packets marked with
 140 \fBPKT_CONSISTENT,\fR the \fBHBA \fRdriver must synchronize any cached data
 141 transfers before calling the target driver's command completion callback.
 142 .sp
 143 .LP
 144 If the \fBPKT_DMA_PARTIAL\fR bit is set in \fIflags\fR, the \fBHBA \fRdriver
 145 should set up partial data transfers, such as setting the \fBDDI_DMA_PARTIAL\fR
 146 bit in the \fIflags\fR argument if interfaces such as
 147 \fBddi_dma_buf_setup\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F) are used.
 148 .sp
 149 .LP
 150 If only partial \fBDMA \fRresources are available,  \fBtran_init_pkt()\fR must
 151 return in the \fBpkt_resid\fR field of \fIpkt\fR the number of bytes of \fBDMA
 152 \fRresources not allocated.
 153 .sp
 154 .LP
 155 If both  \fIpkt\fR and  \fIbp\fR are  non-\fINULL\fR, if the
 156 \fBPKT_DMA_PARTIAL\fR bit is set in  \fIflags\fR, and if \fBDMA \fRresources
 157 have already been allocated for the  pkt with a previous call to
 158 \fBtran_init_pkt()\fR that returned a non-zero \fBpkt_resid\fR field, this
 159 request is to move the \fBDMA \fRresources for the subsequent piece of the
 160 transfer.
 161 .sp
 162 .LP
 163 The contents of \fBscsi_address\fR(9S) pointed to by \fIap\fR are copied into
 164 the \fBpkt_address\fR field of the \fBscsi_pkt\fR(9S) by
 165 \fBscsi_hba_pkt_alloc\fR(9F).
 166 .sp
 167 .LP
 168 \fItgtlen\fR is the length of the packet private area in the \fBscsi_pkt\fR
 169 structure to be allocated on behalf of the \fBSCSI \fRtarget driver.
 170 .sp
 171 .LP
 172 \fIstatuslen\fR is the required length for the \fBSCSI \fRstatus completion
 173 block.  If the requested status length is greater than or equal to
 174 \fBsizeof(struct scsi_arq_status)\fR  and the  \fBauto_rqsense\fR capability
 175 has been set, automatic request sense (\fBARS\fR) is enabled for this packet.
 176 If the status length is less than \fBsizeof(struct scsi_arq_status)\fR,
 177 automatic request sense must be disabled for this \fIpkt\fR.
 178 .sp
 179 .LP
 180 If the \fBHBA\fR driver is not capable of disabling \fBARQ\fR on a per-packet
 181 basis and \fBtran_init_pkt()\fR is called with a \fIstatuslen\fR that is less
 182 than  \fBsizeof(struct scsi_arq_status)\fR, the driver's \fBtran_init_pkt\fR
 183 routine should  allocate at least \fBsizeof(struct scsi_arq_status)\fR. If an
 184 \fBARS\fR is needed, upon successful \fBARS\fR done by the \fBHBA\fR driver,
 185 the driver must copy the sense data over and set \fBSTAT_ARQ_DONE\fR in
 186 \fBpkt_state\fR.
 187 .sp
 188 .LP
 189 \fIcmdlen\fR is the required length for the \fBSCSI \fRcommand descriptor
 190 block.
 191 .sp
 192 .LP
 193 Note: \fItgtlen\fR, \fIstatuslen\fR, and \fIcmdlen\fR are used only when the
 194 \fBHBA \fRdriver allocates the \fBscsi_pkt\fR(9S), in other words, when
 195 \fIpkt\fR is \fINULL\fR.
 196 .sp
 197 .LP
 198 \fIcallback\fR indicates what the allocator routines should do when resources
 199 are not available:
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBNULL_FUNC\fR\fR
 204 .ad
 205 .RS 14n
 206 Do not wait for resources. Return a \fINULL\fR pointer.
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBSLEEP_FUNC\fR\fR
 213 .ad
 214 .RS 14n
 215 Wait indefinitely for resources.
 216 .RE
 217
 218 .SS "tran_destroy_pkt()"
 219 .sp
 220 .LP
 221 \fBtran_destroy_pkt()\fR is the entry point into the \fBHBA \fRthat must free
 222 all of the resources that were allocated to the \fBscsi_pkt\fR(9S) structure
 223 during \fBtran_init_pkt()\fR.
 224 .SH RETURN VALUES
 225 .sp
 226 .LP
 227 \fBtran_init_pkt()\fR must return a pointer to a \fBscsi_pkt\fR(9S) structure
 228 on success, or \fINULL\fR on failure.
 229 .sp
 230 .LP
 231 If \fIpkt\fR is \fINULL\fR on entry, and \fBtran_init_pkt()\fR allocated a
 232 packet through \fBscsi_hba_pkt_alloc\fR(9F) but was unable to allocate \fBDMA
 233 \fRresources, \fBtran_init_pkt()\fR must free the packet through
 234 \fBscsi_hba_pkt_free\fR(9F) before returning \fINULL\fR.
 235 .SH SEE ALSO
 236 .sp
 237 .LP
 238 \fBattach\fR(9E), \fBtran_setup_pkt\fR(9E), \fBtran_sync_pkt\fR(9E),
 239 \fBbiodone\fR(9F), \fBbioerror\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F),
 240 \fBddi_dma_buf_setup\fR(9F), \fBkmem_cache_create\fR(9F),
 241 \fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F),
 242 \fBscsi_hba_attach\fR(9F), \fBscsi_hba_pkt_alloc\fR(9F),
 243 \fBscsi_hba_pkt_free\fR(9F), \fBscsi_init_pkt\fR(9F), \fBbuf\fR(9S),
 244 \fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S)
 245 .sp
 246 .LP
 247 \fIWriting Device Drivers\fR
 248 .SH NOTES
 249 .sp
 250 .LP
 251 If a \fBDMA\fR allocation request fails with \fBDDI_DMA_NOMAPPING\fR, indicate
 252 the error by calling \fBbioerror\fR(9F) with \fIbp\fR and an error code of
 253 \fBEFAULT\fR.
 254 .sp
 255 .LP
 256 If a \fBDMA \fRallocation request fails with \fBDDI_DMA_TOOBIG,\fR indicate the
 257 error by calling \fBbioerror\fR(9F) with \fIbp\fR and an error code of
 258 \fBEINVAL\fR.
 259 .sp
 260 .LP
 261 For increased performance, an HBA driver may want to provide a cache for
 262 \fBscsi_pkt\fR(9S) allocation. This cache should be implemented by the HBA
 263 driver providing a \fBtran_setup_pkt\fR(9E) implementation. Implementing this
 264 cache by direct use of \fBkmem_cache_create\fR(9F) adds a compile-time
 265 dependency on \fBscsi_pkt()\fR size, which is illegal.