1 .\" Copyright (c) 2006 Sun Microsystems, Inc., All Rights Reserved
2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
3 .\" Copyright (c) 2017, Joyent, 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]
8 .Dt SCSI_HBA_ATTACH_SETUP 9F
11 .Nm scsi_hba_attach_setup ,
13 .Nd SCSI HBA attach and detach routines
17 .Fo scsi_hba_attach_setup
19 .Fa "ddi_dma_attr_t *hba_dma_attr"
20 .Fa "scsi_hba_tran_t *hba_tran"
28 illumos architecture specific (illumos DDI).
34 structure that refers to the instance of the HBA device.
41 The defined flag values are
42 .Dv SCSI_HBA_TRAN_CLONE ,
43 .Dv SCSI_HBA_TRAN_SCB ,
44 .Dv SCSI_HBA_TRAN_CDB ,
47 .Dv SCSI_HBA_ADDR_COMPLEX .
54 .Ss Fn scsi_hba_attach_setup
56 .Fn scsi_hba_attach_setup
57 function registers the
59 DMA attributes and the
61 transport vectors of each instance of the HBA device defined by
63 The HBA driver can pass different DMA attributes and the transport
64 vectors for each instance of the device to support any constraints
65 imposed by the HBA itself.
68 .Fn scsi_hba_attach_setup
74 The HBA driver should initialize this field to
77 .Fn scsi_hba_attach_setup .
80 .Dv SCSI_HBA_TRAN_CLONE
85 structure is cloned once for each target that is attached to the
87 The use of this flag is deprecated, drivers should instead use
88 .Dv SCSI_HBA_ADDR_COMPLEX
91 The structure is cloned before the
93 entry point is called to initialize a target.
95 entry points, including
96 .Xr tran_tgt_init 9E ,
99 structure passed as an
100 argument or found in a
102 structure is the cloned
104 structure, which allows the HBA to use the
108 structure to point to per-target data.
109 The HBA should free only the same
111 structure allocated when the HBA detaches.
114 structures that are allocated by the system are freed by the system.
117 .Dv SCSI_HBA_TRAN_CDB
119 .Dv SCSI_HBA_TRAN_SCB
125 .Xr tran_setup_pkt 9E
126 for information on using these flags.
129 .Dv SCSI_HBA_ADDR_COMPLEX
130 indicates to the system that this device handles more complex SCSI
131 topologies, such as SAS.
132 When this flag is set, the
134 structure becomes opaque.
135 The driver must not check it for the traditional target and LUN values.
136 Instead, a target and LUN are identified by a unit address which can be
138 .Xr scsi_device_unit_address 9F
141 When operating with the flag
142 .Dv SCSI_HBA_ADDR COMPLEX ,
143 the driver may associate private data with the
146 This obviates the need and complexity around using
147 .Dv SCSI_HBA_TRAN_CLONE
149 To get and set private data, the driver can use the
150 .Xr scsi_device_hba_private_get 9F
152 .Xr scsi_device_hba_private_set 9F
155 .Fn scsi_device_hba_private_set
156 function should be used during the
160 .Fn scsi_device_hba_private_get
161 function should then be used during other SCSI HBA entry points.
163 .Xr scsi_address_device 9F
164 function now becomes available to the driver to map between the
172 flag indicates that the HBA driver will only enumerate direct children
176 This mode of operation is recommended for device drivers as
177 it simplifies the management of discovered devices.
178 This flag is often used in tandem with
179 .Dv SCSI_HBA_ADDR_COMPLEX
180 and is recommended for all new SAS-based HBA drivers.
181 For more information on the management of iports and the use of target
186 .Fn scsi_hba_attach_setup
187 function attaches a number of integer-valued properties to
189 unless properties of the same name are already attached to the node.
190 An HBA driver should retrieve these configuration parameters via
191 .Xr ddi_prop_get_int 9F ,
192 and respect any settings for features provided the HBA.
195 .Sy Optional SCSI configuration bits .
196 The following values may be bitwise-inclusive-ORed together.
198 .It Dv SCSI_OPTIONS_DR
199 If not set, the HBA should not grant Disconnect privileges to target devices.
200 .It Dv SCSI_OPTIONS_TAG
201 If not set, the HBA should not operate in Command Tagged Queueing mode.
202 .It Dv SCSI_OPTIONS_PARITY
203 If not set, the HBA should not operate in parity mode.
204 .It Dv SCSI_OPTIONS_QAS
205 If not set, the HBA should not make use of the Quick Arbitration Select
207 Consult your hardware documentation to determine whether your
208 machine supports QAS.
209 .It Dv SCSI_OPTIONS_FAST
210 If not set, the HBA should not operate the bus in FAST SCSI mode.
211 .It Dv SCSI_OPTIONS_FAST20
212 If not set, the HBA should not operate the bus in FAST20 SCSI mode.
213 .It Dv SCSI_OPTIONS_FAST40
214 If not set, the HBA should not operate the bus in FAST40 SCSI mode.
215 .It Dv SCSI_OPTIONS_FAST80
216 If not set, the HBA should not operate the bus in FAST80 SCSI mode.
217 .It Dv SCSI_OPTIONS_FAST160
218 If not set, the HBA should not operate the bus in FAST160 SCSI mode.
219 .It Dv SCSI_OPTIONS_FAST320
220 If not set, the HBA should not operate the bus in FAST320 SCSI mode.
221 .It Dv SCSI_OPTIONS_WIDE
222 If not set, the HBA should not operate the bus in WIDE SCSI mode.
223 .It Dv SCSI_OPTIONS_SYNC
224 If not set, the HBA should not operate the bus in synchronous transfer mode.
226 .It Sy scsi-reset-delay
227 SCSI bus or device reset recovery time, in milliseconds.
228 .It Sy scsi-selection-timeout
229 Default SCSI selection phase timeout value, in milliseconds.
230 Please refer to individual HBA man pages for any HBA-specific
233 .Ss Fn scsi_hba_detach
236 function removes the reference to the DMA attributes structure and the
237 transport vector for the given instance of an HBA driver.
240 .Fn scsi_hba_attach_setup
241 function should be called from
245 function should be called from
249 .Fn scsi_hba_attach_setup
254 if the function call succeeds, and return
261 .Xr tran_setup_pkt 9E ,
262 .Xr tran_tgt_init 9E ,
263 .Xr ddi_prop_get_int 9F ,
264 .Xr scsi_address_device 9F ,
265 .Xr scsi_device_hba_private_get 9F ,
266 .Xr scsi_device_hba_private_set 9F ,
267 .Xr scsi_device_unit_address 9F ,
268 .Xr ddi_dma_attr 9S ,
270 .Xr scsi_address 9S ,
275 .%T Writing Device Drivers
278 It is the HBA driver's responsibility to ensure that no more transport requests
279 will be taken on behalf of any SCSI target device driver after