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.