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