1 '\" te
   2 .\" Copyright (c) 2006 Sun Microsystems, Inc., All Rights Reserved
   3 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   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_HBA_ATTACH_SETUP 9F "May 24, 2014"
   8 .SH NAME
   9 scsi_hba_attach_setup, scsi_hba_detach \- SCSI HBA attach and
  10 detach routines
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/scsi/scsi.h>
  15 
  16 
  17 
  18 \fBint\fR \fBscsi_hba_attach_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIhba_dma_attr\fR,
  19      \fBscsi_hba_tran_t *\fR\fIhba_tran\fR, \fBint\fR \fIhba_flags\fR);
  20 .fi
  21 
  22 .LP
  23 .nf
  24 \fBint\fR \fBscsi_hba_detach\fR(\fBdev_info_t *\fR\fIdip\fR);
  25 .fi
  26 
  27 .SH INTERFACE LEVEL
  28 .sp
  29 .LP
  30 Solaris architecture specific (Solaris DDI).
  31 .SH PARAMETERS
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIdip\fR\fR
  36 .ad
  37 .RS 16n
  38 Pointer to the \fBdev_info_t\fR structure that refers to the instance of the
  39 HBA device.
  40 .RE
  41 
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIhba_tran\fR\fR
  46 .ad
  47 .RS 16n
  48 Pointer to a \fBscsi_hba_tran\fR(9S) structure.
  49 .RE
  50 
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIhba_flags\fR\fR
  55 .ad
  56 .RS 16n
  57 Flag modifiers. The defined flag values are \fBSCSI_HBA_TRAN_CLONE\fR,
  58 \fBSCSI_HBA_TRAN_SCB\fR, and \fBSCSI_HBA_TRAN_CDB\fR.
  59 .RE
  60 
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fIhba_options\fR\fR
  65 .ad
  66 .RS 16n
  67 Optional features provided by the HBA driver for future extensions; must be
  68 \fINULL\fR.
  69 .RE
  70 
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fIhba_dma_attr\fR\fR
  75 .ad
  76 .RS 16n
  77 Pointer to a \fBddi_dma_attr\fR(9S) structure.
  78 .RE
  79 
  80 .SH DESCRIPTION
  81 .sp
  82 .SS "scsi_hba_attach_setup(\|)"
  83 .sp
  84 .LP
  85 The \fBscsi_hba_attach_setup()\fR function registers the
  86 \fIhba_dma_attr\fR DMA attributes and the \fIhba_tran\fR transport vectors of
  87 each instance of the HBA device defined by \fIdip\fR. The HBA driver can pass
  88 different DMA attributes and the transport vectors for each
  89 instance of the device to support any constraints imposed by the  HBA itself.
  90 .sp
  91 .LP
  92 The \fBscsi_hba_attach_setup()\fR function uses the
  93 \fBdev_bus_ops\fR field in the \fBdev_ops\fR(9S) structure. The HBA driver
  94 should initialize this field to \fINULL\fR before calling
  95 \fBscsi_hba_attach_setup()\fR.
  96 .sp
  97 .LP
  98 If \fBSCSI_HBA_TRAN_CLONE\fR is requested in \fIhba_flags\fR, the
  99 \fBhba_tran\fR structure is cloned once for each target that is attached to the
 100 HBA. The structure is cloned before the \fBtran_tgt_init\fR(9E) entry point is
 101 called to initialize a target. At all subsequent HBA entry points, including
 102 \fBtran_tgt_init\fR(9E), the \fBscsi_hba_tran_t\fR structure passed as an
 103 argument or found in a \fBscsi_address\fR structure is the cloned
 104 \fBscsi_hba_tran_t\fR structure,which allows the HBA to use the
 105 \fBtran_tgt_private\fR field in the \fBscsi_hba_tran_t\fR structure to point to
 106 per-target data. The HBA should free only the same \fBscsi_hba_tran_t\fR
 107 structure allocated when the HBA detaches. All cloned \fBscsi_hba_tran_t\fR
 108 structures that are allocated by the system are freed by the system.
 109 .sp
 110 .LP
 111 The flags \fBSCSI_HBA_TRAN_CDB\fR and \fBSCSI_HBA_TRAN_SCB\fR are only valid
 112 when \fBtran_setup_pkt()\fR is used. See \fBtran_setup_pkt\fR(9E) for
 113 information on using these flags.
 114 .sp
 115 .LP
 116 The \fBscsi_hba_attach_setup()\fR function attaches
 117 a number of integer-valued properties to \fIdip\fR, unless properties of the
 118 same name are already attached to the node. An HBA driver should retrieve these
 119 configuration parameters via \fBddi_prop_get_int\fR(9F), and respect any
 120 settings for features provided the HBA.
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBscsi-options\fR\fR
 125 .ad
 126 .RS 26n
 127 \fBOptional\fR \fBSCSI\fR \fBconfiguration bits\fR
 128 .RE
 129 
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBSCSI_OPTIONS_DR\fR\fR
 134 .ad
 135 .RS 26n
 136 If not set, the HBA should not grant Disconnect privileges to target devices.
 137 .RE
 138 
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBSCSI_OPTIONS_TAG\fR\fR
 143 .ad
 144 .RS 26n
 145 If not set, the HBA should not operate in Command Tagged Queueing mode.
 146 .RE
 147 
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBSCSI_OPTIONS_PARITY\fR\fR
 152 .ad
 153 .RS 26n
 154 If not set, the HBA should not operate in parity mode.
 155 .RE
 156 
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBSCSI_OPTIONS_QAS\fR\fR
 161 .ad
 162 .RS 26n
 163 If not set, the HBA should not make use of the Quick Arbitration Select
 164 feature. Consult your Sun hardware documentation to determine whether your
 165 machine supports QAS.
 166 .RE
 167 
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBSCSI_OPTIONS_FAST\fR\fR
 172 .ad
 173 .RS 26n
 174 If not set, the HBA should not operate the bus in FAST SCSI mode.
 175 .RE
 176 
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBSCSI_OPTIONS_FAST20\fR\fR
 181 .ad
 182 .RS 26n
 183 If not set, the HBA should not operate the bus in FAST20 SCSI mode.
 184 .RE
 185 
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBSCSI_OPTIONS_FAST40\fR\fR
 190 .ad
 191 .RS 26n
 192 If not set, the HBA should not operate the bus in FAST40 SCSI mode.
 193 .RE
 194 
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBSCSI_OPTIONS_FAST80\fR\fR
 199 .ad
 200 .RS 26n
 201 If not set, the HBA should not operate the bus in FAST80 SCSI mode.
 202 .RE
 203 
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBSCSI_OPTIONS_FAST160\fR\fR
 208 .ad
 209 .RS 26n
 210 If not set, the HBA should not operate the bus in FAST160 SCSI mode.
 211 .RE
 212 
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBSCSI_OPTIONS_FAST320\fR\fR
 217 .ad
 218 .RS 26n
 219 If not set, the HBA should not operate the bus in FAST320 SCSI mode.
 220 .RE
 221 
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBSCSI_OPTIONS_WIDE\fR\fR
 226 .ad
 227 .RS 26n
 228 If not set, the HBA should not operate the bus in WIDE SCSI mode.
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBSCSI_OPTIONS_SYNC\fR\fR
 235 .ad
 236 .RS 26n
 237 If not set, the HBA should not operate the bus in synchronous transfer mode.
 238 .RE
 239 
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fBscsi-reset-delay\fR\fR
 244 .ad
 245 .RS 26n
 246 SCSI bus or device reset recovery time, in milliseconds.
 247 .RE
 248 
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBscsi-selection-timeout\fR\fR
 253 .ad
 254 .RS 26n
 255 Default SCSI selection phase timeout value, in milliseconds. Please refer to
 256 individual HBA man pages for any HBA-specific information
 257 .RE
 258 
 259 .SS "scsi_hba_detach(\|)"
 260 .sp
 261 .LP
 262 The \fBscsi_hba_detach()\fR function removes the reference to the DMA
 263 attributes structure and the transport vector for the given instance of an HBA
 264 driver.
 265 .SH RETURN VALUES
 266 .sp
 267 .LP
 268 The \fBscsi_hba_attach_setup()\fR and
 269 \fBscsi_hba_detach()\fR functions return \fBDDI_SUCCESS\fR if the function call
 270 succeeds, and return \fBDDI_FAILURE\fR on failure.
 271 .SH CONTEXT
 272 .sp
 273 .LP
 274 The \fBscsi_hba_attach_setup()\fR function should
 275 be called from \fBattach\fR(9E). The \fBscsi_hba_detach()\fR function should be
 276 called from \fBdetach\fR(9E).
 277 .SH SEE ALSO
 278 .sp
 279 .LP
 280 \fBattach\fR(9E), \fBdetach\fR(9E), \fBtran_setup_pkt\fR(9E),
 281 \fBtran_tgt_init\fR(9E), \fBddi_prop_get_int\fR(9F), \fBddi_dma_attr\fR(9S),
 282 \fBdev_ops\fR(9S), \fBscsi_address\fR(9S),
 283 \fBscsi_hba_tran\fR(9S)
 284 .sp
 285 .LP
 286 \fIWriting Device Drivers\fR
 287 .SH NOTES
 288 .sp
 289 .LP
 290 It is the HBA driver's responsibility to ensure that no more transport requests
 291 will be taken on behalf of any SCSI target device driver after
 292 \fBscsi_hba_detach()\fR is called.