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