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