1 '\" te
2 .\" Copyright (c) 2007, 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_IFGETCAP 9F "Oct 16, 2007"
7 .SH NAME
8 scsi_ifgetcap, scsi_ifsetcap \- get/set SCSI transport capability
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/scsi/scsi.h>
13
14
15
16 \fBint\fR \fBscsi_ifgetcap\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBchar *\fR\fIcap\fR, \fBint\fR \fIwhom\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBint\fR \fBscsi_ifsetcap\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBchar *\fR\fIcap\fR, \fBint\fR \fIvalue\fR,
22 \fBint\fR \fIwhom\fR);
23 .fi
24
25 .SH INTERFACE LEVEL
26 .sp
27 .LP
28 Solaris DDI specific (Solaris DDI).
29 .SH PARAMETERS
30 .sp
31 .ne 2
32 .na
33 \fB\fIap\fR\fR
34 .ad
35 .RS 9n
36 Pointer to the \fBscsi_address\fR structure.
37 .RE
38
39 .sp
40 .ne 2
41 .na
42 \fB\fIcap\fR\fR
43 .ad
44 .RS 9n
45 Pointer to the string capability identifier.
46 .RE
47
48 .sp
49 .ne 2
50 .na
51 \fB\fIvalue\fR\fR
52 .ad
53 .RS 9n
54 Defines the new state of the capability.
55 .RE
56
57 .sp
58 .ne 2
59 .na
60 \fB\fIwhom\fR\fR
61 .ad
62 .RS 9n
63 Determines if all targets or only the specified target is affected.
64 .RE
65
66 .SH DESCRIPTION
67 .sp
68 .LP
69 The \fBscsi_ifsetcap()\fR function is used by target drivers to set the
70 capabilities of the host adapter driver. The \fIcap\fR pointer is a name-value
71 pair identified by a null-terminated character string and the integer value of
72 the \fIcap\fR. The current value of the capability can be retrieved with the
73 \fBscsi_ifgetcap()\fR function. If the \fIwhom\fR value is \fB0\fR, all target
74 drivers are affected. Otherwise, the \fBscsi_address\fR structure pointed to by
75 \fIap\fR is the only target that is affected.
76 .sp
77 .LP
78 The driver should confirm that \fBscsi_ifsetcap()\fR and \fBscsi_ifsetcap()\fR
79 functions are called with a \fIcap\fR that points to a capability which is
80 supported by the device.
81 .sp
82 .LP
83 The following capabilities have been defined:
84 .sp
85 .ne 2
86 .na
87 \fB\fBdma-max\fR\fR
88 .ad
89 .RS 24n
90 Maximum \fBdma\fR transfer size that is supported by the host adapter.
91 .RE
92
93 .sp
94 .ne 2
95 .na
96 \fB\fBdma-max-arch\fR\fR
97 .ad
98 .RS 24n
99 Maximum \fBdma\fR transfer size that is supported by system. Takes the host
100 adapter and system architecture into account. This is useful for target drivers
101 which do not support partial \fBDMA\fRs on systems which do not have an
102 \fBIOMMU\fR. In this case, the \fBDMA\fR can also be limited by the host
103 adapters "scatter/gather" list constraints.
104 .sp
105 The "\fBdma-max-arch\fR" capability can not be set. It is implemented with this
106 command and does not rely on a \fBtran_getcap\fR(9E) response from the HBA.
107 .RE
108
109 .sp
110 .ne 2
111 .na
112 \fB\fBmsg-out\fR\fR
113 .ad
114 .RS 24n
115 Message out capability that is supported by the host adapter: \fB0\fR disables,
116 \fB1\fR enables.
117 .RE
118
119 .sp
120 .ne 2
121 .na
122 \fB\fBdisconnect\fR\fR
123 .ad
124 .RS 24n
125 Disconnect capability that is supported by the host adapter: \fB0\fR disables,
126 \fB1\fR enables.
127 .RE
128
129 .sp
130 .ne 2
131 .na
132 \fB\fBsynchronous\fR\fR
133 .ad
134 .RS 24n
135 Synchronous data transfer capability that is supported by the host adapter:
136 \fB0\fR disables, \fB1\fR enables.
137 .RE
138
139 .sp
140 .ne 2
141 .na
142 \fB\fBwide-xfer\fR\fR
143 .ad
144 .RS 24n
145 Wide transfer capability that is supported by the host adapter: \fB0\fR
146 disables, \fB1\fR enables.
147 .RE
148
149 .sp
150 .ne 2
151 .na
152 \fB\fBparity\fR\fR
153 .ad
154 .RS 24n
155 Parity checking capability that is supported by host adapter: \fB0\fR disables,
156 \fB1\fR enables.
157 .RE
158
159 .sp
160 .ne 2
161 .na
162 \fB\fBinitiator-id\fR\fR
163 .ad
164 .RS 24n
165 Host bus address that is returned.
166 .RE
167
168 .sp
169 .ne 2
170 .na
171 \fB\fBuntagged-qing\fR\fR
172 .ad
173 .RS 24n
174 Host adapter capability that supports internal queueing of commands without
175 tagged queueing: \fB0\fR disables, \fB1\fR enables.
176 .RE
177
178 .sp
179 .ne 2
180 .na
181 \fB\fBtagged-qing\fR\fR
182 .ad
183 .RS 24n
184 Host adapter capability that supports queuing: \fB0\fR disables, \fB1\fR
185 enables.
186 .RE
187
188 .sp
189 .ne 2
190 .na
191 \fB\fBauto-rqsense\fR\fR
192 .ad
193 .RS 24n
194 Host adapter capability that supports auto request sense on check conditions:
195 \fB0\fR disables, \fB1\fR enables.
196 .RE
197
198 .sp
199 .ne 2
200 .na
201 \fB\fBsector-size\fR\fR
202 .ad
203 .RS 24n
204 Capability that is set by the target driver to inform the \fBHBA\fR of the
205 granularity, in bytes, of the \fBDMA\fR breakup. The \fBHBA\fR \fBDMA\fR limit
206 structure is set to reflect the byte total of this setting. See
207 \fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S). The \fBsector-size\fR
208 should be set to the size of the physical disk sector. The capability defaults
209 to 512 bytes.
210 .RE
211
212 .sp
213 .ne 2
214 .na
215 \fB\fBtotal-sectors\fR\fR
216 .ad
217 .RS 24n
218 Capability that is set by the target driver to inform the \fBHBA\fR of the
219 total number of sectors on the device returned by the \fBSCSI\fR \fBget
220 capacity\fR command. This capability must be set before the target driver
221 ``gets'' the \fBgeometry\fR capability.
222 .RE
223
224 .sp
225 .ne 2
226 .na
227 \fB\fBgeometry\fR\fR
228 .ad
229 .RS 24n
230 Capability that returns the \fBHBA\fR geometry of a target disk. The target
231 driver sets the \fBtotal-sectors\fR capability before ``getting'' the geometry
232 capability. The geometry is returned as a 32-bit value. The upper 16 bits
233 represent the number of heads per cylinder. The lower 16 bits represent the
234 number of sectors per track. The geometry capability cannot be ``set''.
235 .sp
236 If geometry is not relevant or appropriate for the target disk,
237 \fBscsi_ifgetcap()\fR can return \fB-1\fR to indicate that the geometry is not
238 defined. For example, if the \fBHBA\fR BIOS supports Logical Block Addressing
239 for the target disk, \fBscsi_ifgetcap()\fR returns \fB-1\fR. Attempts to
240 retreive the "virtual geometry" from the target driver, such as the
241 \fBDKIOCG_VIRTGEOM\fR ioctl, will fail. See \fBdkio\fR(7I) for more information
242 about \fBDKIOCG_VIRTGEOM\fR.
243 .RE
244
245 .sp
246 .ne 2
247 .na
248 \fB\fBreset-notification\fR\fR
249 .ad
250 .RS 24n
251 Host adapter capability that supports bus reset notification: \fB0\fR disables,
252 \fB1\fR enables. See \fBscsi_reset_notify\fR(9F).
253 .RE
254
255 .sp
256 .ne 2
257 .na
258 \fB\fBlinked-cmds\fR\fR
259 .ad
260 .RS 24n
261 Host adapter capability that supports linked commands: \fB0\fR disables,
262 \fB1\fR enables.
263 .RE
264
265 .sp
266 .ne 2
267 .na
268 \fB\fBqfull-retries\fR\fR
269 .ad
270 .RS 24n
271 Capability that enables or disables \fBQUEUE\fR \fBFULL\fR handling. If
272 \fB0\fR, the \fBHBA\fR will not retry a command when a \fBQUEUE\fR \fBFULL\fR
273 status is returned. If the value is greater than \fB0\fR, the \fBHBA\fR driver
274 retries the command a specified number of times at an interval determined by
275 the \fBqfull-retry-interval\fR. The range for \fBqfull-retries\fR is
276 \fB0-255\fR.
277 .RE
278
279 .sp
280 .ne 2
281 .na
282 \fB\fBqfull-retry-interval\fR\fR
283 .ad
284 .RS 24n
285 Capability that sets the retry interval in milliseconds (\fBms\fR) for commands
286 completed with a \fBQUEUE\fR \fBFULL\fR status. The range for
287 \fBqfull-retry-intervals\fR is \fB0-1000\fR \fBms\fR.
288 .RE
289
290 .sp
291 .ne 2
292 .na
293 \fB\fBlun-reset\fR\fR
294 .ad
295 .RS 24n
296 Capability that is created with a value of zero by \fBHBA\fR drivers that
297 support the \fBRESET_LUN\fR flag in the \fBtran_reset\fR(9E) function. If it
298 exists, the \fBlun-reset\fR value can be set to \fB1\fR by target drivers to
299 allow the use of \fBLOGICAL UNIT RESET\fR on a specific target instance. If
300 \fBlun-reset\fR does not exist or has a value of zero, \fBscsi_reset\fR(9F) is
301 prevented from passing the \fBRESET_LUN\fR flag to \fBtran_reset()\fR function
302 of the \fBHBA\fR driver. If \fBlun-reset\fR exists and has a value of \fB1\fR,
303 the \fBtran_reset()\fR function of the \fBHBA\fR driver can be called with the
304 \fBRESET_LUN\fR flag.
305 .RE
306
307 .sp
308 .ne 2
309 .na
310 \fBinterconnect-type\fR
311 .ad
312 .RS 24n
313 Capability held in the \fBtran_interconnect_type\fR element of struct
314 \fBscsi_hba_tran\fR that indicates the \fBHBA\fR transport interconnect type .
315 The integer value of the interconnect type of the transport is defined in the
316 \fBservices.h\fR header file.
317 .RE
318
319 .sp
320 .ne 2
321 .na
322 \fBmax-cdb-length\fR
323 .ad
324 .RS 24n
325 Host adapter capability of the maximum supported \fBCDB\fR (Command Descriptor
326 Block) length. The target driver asks for the capability at attach time. If the
327 \fBHBA\fR driver supports the capability, the maximum length of the \fBCDB\fR
328 is returned in bytes. The target driver can then use that value to determine
329 which \fBCDB\fR is used for the \fBHBA\fR.
330 .sp
331 If the \fBHBA\fR driver does not support the \fBmax-cdb-length\fR capability,
332 the default value of the target driver is used for the \fBCDB\fR determination.
333 .RE
334
335 .SH RETURN VALUES
336 .sp
337 .LP
338 The \fBscsi_ifsetcap()\fR function returns:
339 .sp
340 .ne 2
341 .na
342 \fB\fB1\fR\fR
343 .ad
344 .RS 9n
345 If the capability was successfully set to the new value.
346 .RE
347
348 .sp
349 .ne 2
350 .na
351 \fB\fB0\fR\fR
352 .ad
353 .RS 9n
354 If the capability is not variable.
355 .RE
356
357 .sp
358 .ne 2
359 .na
360 \fB\fB\(mi1\fR\fR
361 .ad
362 .RS 9n
363 If the capability was not defined, or setting the capability to a new value
364 failed.
365 .RE
366
367 .sp
368 .LP
369 The \fBscsi_ifgetcap()\fR function returns the current value of a capability,
370 or:
371 .sp
372 .ne 2
373 .na
374 \fB\fB\(mi1\fR\fR
375 .ad
376 .RS 9n
377 If the capability was not defined.
378 .RE
379
380 .SH EXAMPLES
381 .LP
382 \fBExample 1 \fRUsing \fBscsi_ifgetcap()\fR
383 .sp
384 .in +2
385 .nf
386 if (scsi_ifgetcap(&sd->sd_address, "auto-rqsense", 1) == 1) {
387 un->un_arq_enabled = 1;
388 } else {
389 un->un_arq_enabled =
390 ((scsi_ifsetcap(&sd->sd_address, "auto-rqsense", 1, 1) == 1) ?
391 1 : 0);
392 }
393
394 if (scsi_ifsetcap(&devp->sd_address, "tagged-qing", 1, 1) == 1) {
395 un->un_dp->options |= SD_QUEUEING;
396 un->un_throttle = MAX_THROTTLE;
397 } else if (scsi_ifgetcap(&devp->sd_address, "untagged-qing", 0) == 1) {
398 un->un_dp->options |= SD_QUEUEING;
399 un->un_throttle = 3;
400 } else {
401 un->un_dp->options &= ~SD_QUEUEING;
402 un->un_throttle = 1;
403 }
404 .fi
405 .in -2
406
407 .SH CONTEXT
408 .sp
409 .LP
410 These functions can be called from user, interrupt, or kernel context.
411 .SH ATTRIBUTES
412 .sp
413 .LP
414 See \fBattributes\fR(5) for descriptions of the following attributes:
415 .sp
416
417 .sp
418 .TS
419 box;
420 c | c
421 l | l .
422 ATTRIBUTE TYPE ATTRIBUTE VALUE
423 _
424 Interface Stability Committed
425 .TE
426
427 .SH SEE ALSO
428 .sp
429 .LP
430 \fBtran_reset\fR(9E), \fBscsi_hba_lookup_capstr\fR(9F), \fBscsi_reset\fR(9F),
431 \fBscsi_reset_notify\fR(9F), \fBddi_dma_lim_sparc\fR(9S),
432 \fBddi_dma_lim_x86\fR(9S), \fBscsi_address\fR(9S), \fBscsi_arq_status\fR(9S)
433 .sp
434 .LP
435 \fIWriting Device Drivers\fR