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