usr/src/man/man9e/tran_setup_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_SETUP_PKT 9E "Mar 13, 2016"
   7 .SH NAME
   8 tran_setup_pkt, tran_teardown_pkt, tran_pkt_constructor, tran_pkt_destructor \-
   9 SCSI HBA packet allocation and deallocation
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/scsi/scsi.h>
  14
  15 \fBint \fR\fBprefix_tran_setup_pkt\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR,
  16      \fBint (*\fR\fIcallback\fR) (\fIcaddr_t\fR), \fBcaddr_t\fR \fIarg\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBprefix_tran_teardown_pkt\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBprefix_tran_pkt_constructor\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR,
  27      \fBscsi_hba_tran_t *\fR\fItranp\fR, \fBint\fR \fIkmflags\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBvoid\fR \fBprefix_tran_pkt_destructor\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR,
  33      \fBstruct scsi_hba_tran_t *\fR\fItranp\fR);
  34 .fi
  35
  36 .SH INTERFACE LEVEL
  37 .LP
  38 Solaris architecture specific (Solaris DDI).
  39 .SH PARAMETERS
  40 .ne 2
  41 .na
  42 \fB\fIpkt\fR\fR
  43 .ad
  44 .RS 12n
  45 Pointer to the \fBscsi_pkt\fR(9S) structure.
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIflags\fR\fR
  52 .ad
  53 .RS 12n
  54 Flags for associating DMA resources with the packet.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fIcallback\fR\fR
  61 .ad
  62 .RS 12n
  63 Pointer to either \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIarg\fR\fR
  70 .ad
  71 .RS 12n
  72 Always \fINULL\fR.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fIkmflags\fR\fR
  79 .ad
  80 .RS 12n
  81 Either \fBKM_SLEEP\fR or \fBKM_NOSLEEP\fR.
  82 .RE
  83
  84 .SH DESCRIPTION
  85 .LP
  86 The \fBtran_setup_pkt()\fR and \fBtran_destroy_pkt()\fR vectors in the
  87 \fBscsi_hba_tran\fR(9S) structure are alternatives to the \fBtran_init_pkt()\fR
  88 and \fBtran_destroy_pkt()\fR entry points. They are initialized during the
  89 \fBHBA\fR driver's \fBattach\fR(9E) and they are used when a target driver
  90 calls \fBscsi_init_pkt\fR(9F) and \fBscsi_destroy_pkt\fR(9F).
  91 .SS "tran_setup_pkt(\|)"
  92 .LP
  93 The \fBtran_setup_pkt()\fR vector is the entry point into the \fBHBA\fR which
  94 is used to initialize \fBHBA\fR specific information in a \fBscsi_pkt\fR
  95 structure on behalf of a SCSI target driver. All fields documented in
  96 \fBscsi_pkt\fR(9S) are initialized.
  97 .sp
  98 .LP
  99 If the \fBHBA\fR driver chose not to preallocate memory for \fBpkt_cdbp\fR
 100 and/or \fBpkt_scbp\fR, it must allocate the requested memory at this time and
 101 point \fBpkt_cdbp\fR and \fBpkt_scbp\fR to the allocated memory.
 102 .sp
 103 .LP
 104 An \fBHBA\fR driver which provides a \fBtran_setup_pkt\fR entry point inspects
 105 the \fBpkt_numcookies\fR and \fBpkt_cookies\fR fields at \fBtran_start\fR time
 106 to set up the transfer. If \fBpkt_numcookies\fR is zero, there are no \fBDMA\fR
 107 resources associated with this packet. If \fBpkt_numcookies\fR is not zero, it
 108 indicates the number of \fBDMA\fR cookies that \fBpkt_cookies\fR points to.
 109 .sp
 110 .LP
 111 The \fBpkt_tgtlen\fR field contains the length of the packet private area
 112 pointed to by \fBpkt_private\fR, allocated on behalf of the SCSI target driver.
 113 .sp
 114 .LP
 115 The \fBpkt_scblen\fR field contains the length of the SCSI status completion
 116 block pointed to by \fBpkt_scbp\fR. If the status length is greater than or
 117 equal to sizeof (\fBstruct\fR \fBscsi_arq_status\fR) and the
 118 \fBauto-rqsense\fR capability has been set, automatic request sense (\fBARS\fR)
 119 is enabled for this packet. If the status length is less than \fBsizeof\fR
 120 (\fBstruct\fR \fBscsi_arq_status\fR), automatic request sense should be
 121 disabled for this pkt if the \fBHBA\fR driver is capable of disabling \fBARQ\fR
 122 on a per-packet basis.
 123 .sp
 124 .LP
 125 The \fBpkt_cdblen\fR field contains the length of the SCSI command descriptor
 126 block.
 127 .sp
 128 .LP
 129 The \fIcallback\fR argument indicates what the allocator routines should do
 130 when resources are not available:
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBNULL_FUNC\fR\fR
 135 .ad
 136 .RS 14n
 137 Do not wait for resources. Return \fB-1\fR when resources are not available.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBSLEEP_FUNC\fR\fR
 144 .ad
 145 .RS 14n
 146 Wait indefinitely for resources.
 147 .RE
 148
 149 .SS "tran_teardown_pkt(\|)"
 150 .LP
 151 The \fBtran_teardown_pkt()\fR is the entry point into the \fBHBA\fR that must
 152 free all of the resources that were allocated to the \fBscsi_pkt\fR(9S)
 153 structure during \fBtran_setup_pkt()\fR.
 154 .SS "tran_pkt_constructor(\|) tran_pkt_destructor(\|)"
 155 .LP
 156 When using \fBtran_pkt_setup()\fR and \fBtran_pkt_teardown()\fR,
 157 \fBtran_pkt_constructor()\fR and \fBtran_pkt_destructor()\fR are additional
 158 optional entry points that perform the actions of a constructor and destructor.
 159 The constructor is called after the following fields in the \fBscsi_pkt\fR
 160 structure have been initialized:
 161 .RS +4
 162 .TP
 163 .ie t \(bu
 164 .el o
 165 \fBpkt_address\fR
 166 .RE
 167 .RS +4
 168 .TP
 169 .ie t \(bu
 170 .el o
 171 \fBpkt_ha_private\fR
 172 .RE
 173 .RS +4
 174 .TP
 175 .ie t \(bu
 176 .el o
 177 \fBpkt_cdbp\fR
 178 .RE
 179 .RS +4
 180 .TP
 181 .ie t \(bu
 182 .el o
 183 \fBpkt_private\fR
 184 .RE
 185 .RS +4
 186 .TP
 187 .ie t \(bu
 188 .el o
 189 \fBpkt_scbp\fR
 190 .RE
 191 .RS +4
 192 .TP
 193 .ie t \(bu
 194 .el o
 195 \fBpkt_cdblen\fR
 196 .RE
 197 .RS +4
 198 .TP
 199 .ie t \(bu
 200 .el o
 201 \fBpkt_tgtlen\fR
 202 .RE
 203 .RS +4
 204 .TP
 205 .ie t \(bu
 206 .el o
 207 \fBpkt_scblen\fR
 208 .RE
 209 .sp
 210 .LP
 211 Allocating and freeing a \fBDMA\fR handle are examples of something that could
 212 be done in the constructor and destructor. See \fBkmem_cache_create\fR(9F) for
 213 additional restrictions on what actions can be performed in a constructor and
 214 destructor.
 215 .sp
 216 .LP
 217 HBA drivers that implement \fBtran_setup_pkt()\fR must signal
 218 \fBscsi_pkt\fR(9S) completion by calling \fBscsi_hba_pkt_comp\fR(9F). Direct
 219 use of  the \fBscsi_pkt\fR \fIpkt_comp\fR field is not permitted and results in
 220 undefined behavior.
 221 .SH RETURN VALUES
 222 .LP
 223 \fBtran_setup_pkt()\fR must return zero on success, and \fB-1\fR on failure.
 224 .SH SEE ALSO
 225 .LP
 226 \fBattach\fR(9E), \fBtran_sync_pkt\fR(9E), \fBbioerror\fR(9F),
 227 \fBddi_dma_buf_bind_handle\fR(9F), \fBkmem_cache_create\fR(9F),
 228 \fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F),
 229 \fBscsi_hba_attach\fR(9F), \fBscsi_hba_pkt_alloc\fR(9F),
 230 \fBscsi_hba_pkt_comp\fR(9F), \fBscsi_hba_pkt_free\fR(9F),
 231 \fBscsi_init_pkt\fR(9F), \fBbuf\fR(9S), \fBscsi_address\fR(9S),
 232 \fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S)
 233 .sp
 234 .LP
 235 \fIWriting Device Drivers\fR