| blob | dfe56db9f430da46bb9f0a5de8536df862601b4d |
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>
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
22 .LP
23 .nf
24 \fBint\fR \fBscsi_hba_detach\fR(\fBdev_info_t *\fR\fIdip\fR);
25 .fi
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.