Print this page
10564 Convert uscsi(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/uscsi.7i
+++ new/usr/src/man/man7i/uscsi.7i
1 -'\" te
2 1 .\" Copyright (c) 2007 by Sun Microsystems, Inc. All rights reserved.
3 -.\" Copyright 2016 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]
7 -.TH USCSI 7I "Sep 23, 2016"
8 -.SH NAME
9 -uscsi \- user SCSI command interface
10 -.SH SYNOPSIS
11 -.LP
12 -.nf
13 -#include <sys/scsi/impl/uscsi.h>
14 -
15 -\fB\fR\fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIrequest\fR, \fBstruct uscsi_cmd *\fR\fIcmd\fR);
16 -.fi
17 -
18 -.SH DESCRIPTION
19 -.LP
20 -The \fBuscsi\fR command is very powerful and somewhat dangerous; therefore it
21 -has some permission restrictions. See \fBWARNINGS\fR for more details.
22 -.sp
23 -.LP
24 -Drivers supporting this \fBioctl\fR(2) provide a general interface allowing
25 -user-level applications to cause individual \fBSCSI\fR commands to be directed
26 -to a particular \fBSCSI\fR or \fBATAPI\fR device under control of that driver.
27 -The \fBuscsi\fR command is supported by the \fBsd\fR driver for \fBSCSI\fR
28 -disks and \fBATAPI\fR CD-ROM drives, and by the \fBst\fR driver for \fBSCSI\fR
29 -tape drives. \fBuscsi\fR may also be supported by other device drivers; see the
2 +.\" Copyright 2017 Joyent, Inc.
3 +.\" The contents of this file are subject to the terms of the
4 +.\" Common Development and Distribution License (the "License").
5 +.\" You may not use this file except in compliance with the License.
6 +.\"
7 +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 +.\" or http://www.opensolaris.org/os/licensing.
9 +.\" See the License for the specific language governing permissions
10 +.\" and limitations under the License.
11 +.\"
12 +.\" When distributing Covered Code, include this CDDL HEADER in each
13 +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 +.\" If applicable, add the following below this CDDL HEADER, with the
15 +.\" fields enclosed by brackets "[]" replaced with your own identifying
16 +.\" information: Portions Copyright [yyyy] [name of copyright owner]
17 +.Dd October 23, 2017
18 +.Dt USCSI 7I
19 +.Os
20 +.Sh NAME
21 +.Nm uscsi
22 +.Nd user SCSI command interface
23 +.Sh SYNOPSIS
24 +.In sys/scsi/impl/uscsi.h
25 +.Fo ioctl
26 +.Fa "int filedes"
27 +.Fa "int request"
28 +.Fa "struct uscsi_cmd *cmd"
29 +.Fc
30 +.Sh DESCRIPTION
31 +The
32 +.Nm
33 +command is very powerful and somewhat dangerous; therefore it
34 +has some permission restrictions.
35 +See
36 +.Sx WARNINGS
37 +for more details.
38 +.Pp
39 +Drivers supporting this
40 +.Xr ioctl 2
41 +provide a general interface allowing user-level applications to cause individual
42 +.Sy SCSI
43 +commands to be directed to a particular
44 +.Sy SCSI
45 +or
46 +.Sy ATAPI
47 +device under control of that driver.
48 +The
49 +.Nm
50 +command is supported by the
51 +.Xr sd 7D
52 +driver for
53 +.Sy SCSI
54 +disks and
55 +.Sy ATAPI
56 +CD-ROM drives, and by the
57 +.Xr st 7D
58 +driver for
59 +.Sy SCSI
60 +tape drives.
61 +.Nm
62 +may also be supported by other device drivers; see the
30 63 specific device driver manual page for complete information.
31 -.sp
32 -.LP
64 +.Pp
33 65 Applications must not assume that all Solaris disk device drivers support the
34 -\fBuscsi\fR ioctl command. The \fBSCSI\fR command may include a data transfer
35 -to or from that device, if appropriate for that command. Upon completion of the
36 -command, the user application can determine how many bytes were transferred and
37 -the status returned by the device. Also, optionally, if the command returns a
66 +.Nm
67 +ioctl command.
68 +The
69 +.Sy SCSI
70 +command may include a data transfer
71 +to or from that device, if appropriate for that command.
72 +Upon completion of the command, the user application can determine how many
73 +bytes were transferred and the status returned by the device.
74 +Also, optionally, if the command returns a
38 75 Check Condition status, the driver will automatically issue a Request Sense
39 -command and return the sense data along with the original status. See the
40 -\fBUSCSI_RQENABLE\fR flag below for this Request Sense processing. The
41 -\fBuscsi_cmd\fR structure is defined in \fB<sys/scsi/impl/uscsi.h>\fR and
42 -includes the following members:
43 -.sp
44 -.in +2
45 -.nf
46 -int uscsi_flags; /* read, write, etc. see below */
76 +command and return the sense data along with the original status.
77 +See the
78 +.Sy USCSI_RQENABLE
79 +flag below for this Request Sense processing.
80 +The
81 +.Vt uscsi_cmd
82 +structure is defined in
83 +.In sys/scsi/impl/uscsi.h
84 +and includes the following members:
85 +.Bd -literal -offset 2n
86 +int uscsi_flags; /* read, write, etc. see below */
47 87 short uscsi_status; /* resulting status */
48 88 short uscsi_timeout; /* Command Timeout */
49 89 caddr_t uscsi_cdb /* CDB to send to target */
50 90 caddr_t uscsi_bufaddr; /* i/o source/destination */
51 91 size_t uscsi_buflen; /* size of i/o to take place*/
52 92 size_t uscsi_resid; /* resid from i/o operation */
53 93 uchar_t uscsi_cdblen; /* # of valid CDB bytes */
54 94 uchar_t uscsi_rqlen; /* size of uscsi_rqbuf */
55 95 uchar_t uscsi_rqstatus; /* status of request sense cmd */
56 96 uchar_t uscsi_rqresid; /* resid of request sense cmd */
57 97 caddr_t uscsi_rqbuf; /* request sense buffer */
58 98 void *uscsi_reserved_5; /* Reserved for future use */
59 -.fi
60 -.in -2
61 -
62 -.sp
63 -.LP
64 -The fields of the \fBuscsi_cmd\fR structure have the following meanings:
65 -.sp
66 -.ne 2
67 -.na
68 -\fB\fBuscsi_flags\fR\fR
69 -.ad
70 -.RS 20n
71 -The \fBI/O\fR direction and other details of how to carry out the \fBSCSI\fR
72 -command. Possible values are described below.
73 -.RE
74 -
75 -.sp
76 -.ne 2
77 -.na
78 -\fB\fBuscsi_status\fR\fR
79 -.ad
80 -.RS 20n
81 -The \fBSCSI\fR status byte returned by the device is returned in this field.
82 -.RE
83 -
84 -.sp
85 -.ne 2
86 -.na
87 -\fB\fBuscsi_timeout\fR\fR
88 -.ad
89 -.RS 20n
99 +.Ed
100 +.Pp
101 +The fields of the
102 +.Vt uscsi_cmd
103 +structure have the following meanings:
104 +.Bl -tag -width uscsi_reserved_5
105 +.It Sy uscsi_flags
106 +The
107 +.Sy I/O
108 +direction and other details of how to carry out the
109 +.Sy SCSI
110 +command.
111 +Possible values are described below.
112 +.It Fa uscsi_status
113 +The
114 +.Sy SCSI
115 +status byte returned by the device is returned in this field.
116 +.It Fa uscsi_timeout
90 117 Time in seconds to allow for completion of the command.
91 -.RE
92 -
93 -.sp
94 -.ne 2
95 -.na
96 -\fB\fBuscsi_cdb\fR\fR
97 -.ad
98 -.RS 20n
99 -A pointer to the \fBSCSI\fR CDB (command descriptor block) to be transferred to
100 -the device in command phase.
101 -.RE
102 -
103 -.sp
104 -.ne 2
105 -.na
106 -\fB\fBuscsi_bufaddr\fR\fR
107 -.ad
108 -.RS 20n
118 +.It Fa uscsi_cdb
119 +A pointer to the
120 +.Sy SCSI
121 +CDB (command descriptor block) to be transferred to the device in command phase.
122 +.It Fa uscsi_bufaddr
109 123 The user buffer containing the data to be read from or written to the device.
110 -.RE
111 -
112 -.sp
113 -.ne 2
114 -.na
115 -\fB\fBuscsi_buflen\fR\fR
116 -.ad
117 -.RS 20n
118 -The length of \fBuscsi_bufaddr\fR.
119 -.RE
120 -
121 -.sp
122 -.ne 2
123 -.na
124 -\fB\fBuscsi_resid\fR\fR
125 -.ad
126 -.RS 20n
124 +.It Sy uscsi_buflen
125 +The length of
126 +.Fa uscsi_bufaddr .
127 +.It Fa uscsi_resid
127 128 If a data transfer terminates without transferring the entire requested amount,
128 129 the remainder, or residue, is returned in this field.
129 -.RE
130 -
131 -.sp
132 -.ne 2
133 -.na
134 -\fB\fBuscsi_cdblen\fR\fR
135 -.ad
136 -.RS 20n
137 -The length of the \fBSCSI\fR CDB to be transferred to the device in command
138 -phase.
139 -.RE
140 -
141 -.sp
142 -.ne 2
143 -.na
144 -\fB\fBuscsi_rqlen\fR\fR
145 -.ad
146 -.RS 20n
147 -The length of \fBuscsi_rqbuf\fR, the application's Request Sense buffer.
148 -.RE
149 -
150 -.sp
151 -.ne 2
152 -.na
153 -\fB\fBuscsi_rqstatus\fR\fR
154 -.ad
155 -.RS 20n
156 -The \fBSCSI\fR status byte returned for the Request Sense command executed
130 +.It Fa uscsi_cdblen
131 +The length of the
132 +.Sy SCSI
133 +CDB to be transferred to the device in command phase.
134 +.It Fa uscsi_rqlen
135 +The length of
136 +.Fa uscsi_rqbuf ,
137 +the application's Request Sense buffer.
138 +.It Fa uscsi_rqstatus
139 +The
140 +.Sy SCSI
141 +status byte returned for the Request Sense command executed
157 142 automatically by the driver in response to a Check Condition status return.
158 -.RE
159 -
160 -.sp
161 -.ne 2
162 -.na
163 -\fB\fBuscsi_rqresid\fR\fR
164 -.ad
165 -.RS 20n
143 +.It Fa uscsi_rqresid
166 144 The residue, or untransferred data length, of the Request Sense data transfer
167 -(the number of bytes, less than or equal to \fBuscsi_rqlen\fR, which were not
168 -filled with sense data).
169 -.RE
170 -
171 -.sp
172 -.ne 2
173 -.na
174 -\fB\fBuscsi_rqbuf\fR\fR
175 -.ad
176 -.RS 20n
145 +(the number of bytes, less than or equal to
146 +.Fa uscsi_rqlen ,
147 +which were not filled with sense data).
148 +.It Fa uscsi_rqbuf
177 149 Points to a buffer in application address space to which the results of an
178 150 automatic Request Sense command are written.
179 -.RE
180 -
181 -.sp
182 -.ne 2
183 -.na
184 -\fB\fBuscsi_reserved_5\fR\fR
185 -.ad
186 -.RS 20n
151 +.It Fa uscsi_reserved_5
187 152 Reserved for future use.
188 -.RE
189 -
190 -.sp
191 -.LP
192 -The \fBuscsi_flags\fR field defines the following:
193 -.sp
194 -.in +2
195 -.nf
153 +.El
154 +.Pp
155 +The
156 +.Fa uscsi_flags
157 +field defines the following:
158 +.Bd -literal -offset 2n
196 159 USCSI_WRITE /* send data to device */
197 160 USCSI_SILENT /* no error messages */
198 161 USCSI_DIAGNOSE /* fail if any error occurs */
199 162 USCSI_ISOLATE /* isolate from normal commands */
200 163 USCSI_READ /* get data from device */
201 164 USCSI_ASYNC /* set bus to asynchronous mode */
202 165 USCSI_SYNC /* return bus to sync mode if possible */
203 166 USCSI_RESET /* reset target */
204 167 USCSI_RESET_TARGET /* reset target */
205 168 USCSI_RESET_LUN /* reset logical unit */
206 169 USCSI_RESET_ALL /* reset all targets */
207 170 USCSI_RQENABLE /* enable request sense extensions */
208 171 USCSI_RENEGOT /* renegotiate wide/sync on next I/O */
209 -.fi
210 -.in -2
211 -
212 -.sp
213 -.LP
214 -The \fBuscsi_flags\fR bits have the following interpretation:
215 -.sp
216 -.ne 2
217 -.na
218 -\fB\fBUSCSI_WRITE\fR\fR
219 -.ad
220 -.RS 22n
172 +.Ed
173 +.Pp
174 +The
175 +.Fa uscsi_flags
176 +bits have the following interpretation:
177 +.Bl -tag -width USCSI_RESET_TARGET
178 +.It Dv USCSI_WRITE
221 179 Data will be written from the initiator to the target.
222 -.RE
223 -
224 -.sp
225 -.ne 2
226 -.na
227 -\fB\fBUSCSI_SILENT\fR\fR
228 -.ad
229 -.RS 22n
180 +.It Dv USCSI_SILENT
230 181 The driver should not print any console error messages or warnings regarding
231 -failures associated with this \fBSCSI\fR command.
232 -.RE
233 -
234 -.sp
235 -.ne 2
236 -.na
237 -\fB\fBUSCSI_DIAGNOSE\fR\fR
238 -.ad
239 -.RS 22n
182 +failures associated with this
183 +.Sy SCSI
184 +command.
185 +.It Dv USCSI_DIAGNOSE
240 186 The driver should not attempt any retries or other recovery mechanisms if this
241 -\fBSCSI\fR command terminates abnormally in any way.
242 -.RE
243 -
244 -.sp
245 -.ne 2
246 -.na
247 -\fB\fBUSCSI_ISOLATE\fR\fR
248 -.ad
249 -.RS 22n
250 -This \fBSCSI\fR command should not be executed with other commands.
251 -.RE
252 -
253 -.sp
254 -.ne 2
255 -.na
256 -\fB\fBUSCSI_READ\fR\fR
257 -.ad
258 -.RS 22n
187 +.Sy SCSI
188 +command terminates abnormally in any way.
189 +.It Dv USCSI_ISOLATE
190 +This
191 +.Sy SCSI
192 +command should not be executed with other commands.
193 +.It Dv USCSI_READ
259 194 Data will be read from the target to the initiator.
260 -.RE
261 -
262 -.sp
263 -.ne 2
264 -.na
265 -\fB\fBUSCSI_ASYNC\fR\fR
266 -.ad
267 -.RS 22n
268 -Set the \fBSCSI\fR bus to asynchronous mode before running this command.
269 -.RE
270 -
271 -.sp
272 -.ne 2
273 -.na
274 -\fB\fBUSCSI_SYNC\fR\fR
275 -.ad
276 -.RS 22n
277 -Set the \fBSCSI\fR bus to synchronous mode before running this command.
278 -.RE
279 -
280 -.sp
281 -.ne 2
282 -.na
283 -\fB\fBUSCSI_RESET\fR\fR
284 -.ad
285 -.RS 22n
286 -Send a \fBSCSI\fR bus device reset message to this target.
287 -.RE
288 -
289 -.sp
290 -.ne 2
291 -.na
292 -\fB\fBUSCSI_RESET_TARGET\fR\fR
293 -.ad
294 -.RS 22n
295 -Same as USCSI_RESET. Use this flag to request TARGET RESET. (USCSI_RESET is
296 -maintained only for compatibility with old applications).
297 -.RE
298 -
299 -.sp
300 -.ne 2
301 -.na
302 -\fB\fBUSCSI_RESET_LUN\fR\fR
303 -.ad
304 -.RS 22n
305 -Send a \fBSCSI\fR logical unit reset message to this target.
306 -.RE
307 -
308 -.sp
309 -.ne 2
310 -.na
311 -\fB\fBUSCSI_RESET_ALL\fR\fR
312 -.ad
313 -.RS 22n
314 -USCSI_RESET_ALL, USCSI_RESET/USCSI_RESET_TARGET and USCSI_RESET_LUN are
195 +.It Dv USCSI_ASYNC
196 +Set the
197 +.Sy SCSI
198 +bus to asynchronous mode before running this command.
199 +.It Dv USCSI_SYNC
200 +Set the
201 +.Sy SCSI
202 +bus to synchronous mode before running this command.
203 +.It Dv USCSI_RESET
204 +Send a
205 +.Sy SCSI
206 +bus device reset message to this target.
207 +.It Dv USCSI_RESET_TARGET
208 +Same as USCSI_RESET.
209 +Use this flag to request TARGET RESET.
210 +.Po
211 +.Dv USCSI_RESET
212 +is maintained only for compatibility with old applications
213 +.Pc .
214 +.It Dv USCSI_RESET_LUN
215 +Send a
216 +.Sy SCSI
217 +logical unit reset message to this target.
218 +.It Dv USCSI_RESET_ALL
219 +.Dv USCSI_RESET_ALL ,
220 +.Dv USCSI_RESET/USCSI_RESET_TARGET ,
221 +and
222 +.Dv USCSI_RESET_LUN
223 +are
315 224 mutually exclusive options and issuing them in any simultaneous combination
316 225 will result in implementation-dependent behavior
317 -.sp
318 -When a USCSI reset request is combined with other \fBSCSI\fR commands, the
319 -following semantics take effect:
320 -.sp
321 -If the USCSI RESET flag is specified, the other fields (other than uscsi_flags)
322 -in the uscsi_cmd are ignored. The uscsi_cdblen \fBmust\fR be set to zero.
323 -.RE
324 -
325 -.sp
326 -.ne 2
327 -.na
328 -\fB\fBUSCSI_RQENABLE\fR\fR
329 -.ad
330 -.RS 22n
331 -Enable Request Sense extensions. If the user application is prepared to receive
332 -sense data, this bit must be set, the fields \fBuscsi_rqbuf\fR and
333 -\fBuscsi_rqbuflen\fR must be non-zero, and the \fBuscsi_rqbuf\fR must point to
334 -memory writable by the application.
335 -.RE
336 -
337 -.sp
338 -.ne 2
339 -.na
340 -\fB\fBUSCSI_RENEGOT\fR\fR
341 -.ad
342 -.RS 22n
226 +When a USCSI reset request is combined with other
227 +.Sy SCSI
228 +commands, the following semantics take effect:
229 +If the
230 +.Dv USCSI RESET
231 +flag is specified, the other fields (other than
232 +.Fa uscsi_flags )
233 +in the
234 +.Vt uscsi_cmd
235 +are ignored.
236 +The
237 +.Fa uscsi_cdblen
238 +field
239 +.Em must
240 +be set to zero.
241 +.It Dv USCSI_RQENABLE
242 +Enable Request Sense extensions.
243 +If the user application is prepared to receive
244 +sense data, this bit must be set, the fields
245 +.Fa uscsi_rqbuf
246 +and
247 +.Fa uscsi_rqbuflen
248 +must be non-zero, and the
249 +.Fa uscsi_rqbuf
250 +must point to memory writable by the application.
251 +.It Dv USCSI_RENEGOT
343 252 Tells USCSI to renegotiate wide mode and synchronous transfer speed before the
344 -transmitted SCSI command is executed. This flag in effects tells the target
345 -driver to pass the \fBFLAG_RENEGOTIATE_WIDE_SYNC\fR flag in the SCSI packet
253 +transmitted SCSI command is executed.
254 +This flag in effects tells the target driver to pass the
255 +.Dv FLAG_RENEGOTIATE_WIDE_SYNC
256 +flag in the SCSI packet
346 257 before passing the command to an adapter driver for transport.
347 -.sp
348 -See the \fBscsi_pkt\fR(9S) flag \fBFLAG_RENEGOTIATE_WIDE_SYNC\fR for more
349 -information.
350 -.RE
351 -
352 -The \fBuscsi_xfer_t\fR is a type definition that corresponds to a 64-bit
353 -unsigned integer. It should be used for the \fBUSCSIMAXXFER\fR ioctls. This is
258 +See the
259 +.Xr scsi_pkt 9S
260 +flag
261 +.Dv FLAG_RENEGOTIATE_WIDE_SYNC
262 +for more information.
263 +.El
264 +.Pp
265 +The
266 +.Vt uscsi_xfer_t
267 +is a type definition that corresponds to a 64-bit unsigned integer.
268 +It should be used for the
269 +.Dv USCSIMAXXFER
270 +ioctls.
271 +This is
354 272 used for determining the maximum transfer size that can be performed in a single
355 -\fBUSCSICMD\fR ioctl. If the SCSI request is larger than the specified size,
273 +.Dv USCSICMD
274 +ioctl.
275 +If the SCSI request is larger than the specified size,
356 276 then it may not work, depending on the hardware platform.
357 -
358 -.SH IOCTLS
359 -.LP
360 -The \fBioctl\fR supported by drivers providing the \fBuscsi\fR interface is:
361 -.sp
362 -.ne 2
363 -.na
364 -\fB\fBUSCSICMD\fR\fR
365 -.ad
366 -.RS 12n
367 -The argument is a pointer to a \fBuscsi_cmd\fR structure. The \fBSCSI\fR device
368 -addressed by that driver is selected, and given the \fBSCSI\fR command
369 -addressed by \fBuscsi_cdb\fR. If this command requires a data phase, the
370 -\fBuscsi_buflen\fR and \fBuscsi_bufaddr\fR fields must be set appropriately; if
371 -data phase occurs, the \fBuscsi_resid\fR is returned as the number of bytes not
372 -transferred. The status of the command, as returned by the device, is returned
373 -in the \fBuscsi_status\fR field. If the command terminates with Check Condition
277 +.Sh IOCTLS
278 +The
279 +.Fn ioctl
280 +supported by drivers providing the
281 +.Nm
282 +interface is:
283 +.Bl -tag -width USCSIMAXXFER
284 +.It Dv USCSICMD
285 +The argument is a pointer to a
286 +.Vt uscsi_cmd
287 +structure.
288 +The
289 +.Sy SCSI
290 +device addressed by that driver is selected, and given the
291 +.Sy SCSI
292 +command addressed by
293 +.Fa uscsi_cdb .
294 +If this command requires a data phase, the
295 +.Fa uscsi_buflen
296 +and
297 +.Fa uscsi_bufaddr
298 +fields must be set appropriately; if data phase occurs, the
299 +.Fa uscsi_resid
300 +is returned as the number of bytes not transferred.
301 +The status of the command, as returned by the device, is returned in the
302 +.Fa uscsi_status
303 +field.
304 +If the command terminates with Check Condition
374 305 status, and Request Sense is enabled, the sense data itself is returned in
375 -\fBuscsi_rqbuf\fR. The \fBuscsi_rqresid\fR provides the residue of the Request
376 -Sense data transfer.
377 -.RE
378 -
379 -.sp
380 -.ne 2
381 -.na
382 -.B USCSIMAXXFER
383 -.ad
384 -.RS 12n
385 -The argument is a pointer to a \fBuscsi_xfer_t\fR value. The maximum transfer
386 -size that can be used with the \fBUSCSICMD\fR ioctl for the current device will
387 -be returned in the \fBuscsi_xfer_t\fR.
388 -.sp
389 -.LP
390 -Not all devices which support the \fBUSCSICMD\fR ioctl also support the
391 -\fBUSCSIMAXXFER\fR ioctl.
392 -.RE
393 -
394 -.SH ERRORS
395 -.ne 2
396 -.na
397 -\fB\fBEINVAL\fR\fR
398 -.ad
399 -.RS 10n
306 +.Fa uscsi_rqbuf .
307 +The
308 +.Fa uscsi_rqresid
309 +provides the residue of the Request Sense data transfer.
310 +.It Dv USCSIMAXXFER
311 +The argument is a pointer to a
312 +.Vt uscsi_xfer_t
313 +value.
314 +The maximum transfer size that can be used with the
315 +.Dv USCSICMD
316 +ioctl for the current device will be returned in the
317 +.Vt uscsi_xfer_t .
318 +.Pp
319 +Not all devices which support the
320 +.Dv USCSICMD
321 +ioctl also support the
322 +.Dv USCSIMAXXFER
323 +ioctl.
324 +.El
325 +.Sh ERRORS
326 +.Bl -tag -width EINVAL
327 +.It Er EINVAL
400 328 A parameter has an incorrect, or unsupported, value.
401 -.RE
402 -
403 -.sp
404 -.ne 2
405 -.na
406 -\fB\fBEIO\fR\fR
407 -.ad
408 -.RS 10n
329 +.It Er EIO
409 330 An error occurred during the execution of the command.
410 -.RE
411 -
412 -.sp
413 -.ne 2
414 -.na
415 -\fB\fBEPERM\fR\fR
416 -.ad
417 -.RS 10n
418 -A process without root credentials tried to execute the \fBUSCSICMD\fR or
419 -\fBUSCSIMAXXFER\fR ioctl.
420 -.RE
421 -
422 -.sp
423 -.ne 2
424 -.na
425 -\fB\fBEFAULT\fR\fR
426 -.ad
427 -.RS 10n
428 -The \fBuscsi_cmd\fR itself, the \fBuscsi_cdb\fR, the \fBuscsi_buf\fR, the
429 -\fBuscsi_rqbuf\fR, or the \fBuscsi_xfer_t\fR point to an invalid address.
430 -.RE
431 -
432 -.SH ATTRIBUTES
433 -.LP
434 -See \fBattributes\fR(5) for descriptions of the following attributes:
435 -.sp
436 -
437 -.sp
438 -.TS
439 -box;
440 -c | c
441 -l | l .
442 -ATTRIBUTE TYPE ATTRIBUTE VALUE
443 -_
444 -Interface Stability Committed
445 -.TE
446 -
447 -.SH SEE ALSO
448 -.LP
449 -\fBioctl\fR(2), \fBattributes\fR(5), \fBsd\fR(7D), \fBst\fR(7D)
450 -.sp
451 -.LP
452 -\fIANSI Small Computer System Interface-2 (SCSI-2)\fR
453 -.SH WARNINGS
454 -.LP
455 -The \fBuscsi\fR command is very powerful, but somewhat dangerous, and so its
331 +.It Er EPERM
332 +A process without root credentials tried to execute the
333 +.Dv USCSICMD
334 +or
335 +.Dv USCSIMAXXFER
336 +ioctl.
337 +.It Er EFAULT
338 +The
339 +.Vt uscsi_cmd
340 +itself, the
341 +.Fa uscsi_cdb ,
342 +the
343 +.Fa uscsi_buf ,
344 +the
345 +.Fa uscsi_rqbuf ,
346 +or the
347 +.Vt uscsi_xfer_t
348 +point to an invalid address.
349 +.El
350 +.Sh STABILITY
351 +Committed
352 +.Sh SEE ALSO
353 +.Xr ioctl 2 ,
354 +.Xr attributes 5 ,
355 +.Xr sd 7D ,
356 +.Xr st 7D
357 +.Rs
358 +.%T ANSI Small Computer System Interface-2 (SCSI-2)
359 +.Re
360 +.Sh WARNINGS
361 +The
362 +.Nm
363 +command is very powerful, but somewhat dangerous, and so its
456 364 use is restricted to processes running as root, regardless of the file
457 -permissions on the device node. The device driver code expects to own the
458 -device state, and \fBuscsi\fR commands can change the state of the device and
459 -confuse the device driver. It is best to use \fBuscsi\fR commands only with no
460 -side effects, and avoid commands such as Mode Select, as they may cause damage
461 -to data stored on the drive or system panics. Also, as the commands are not
462 -checked in any way by the device driver, any block may be overwritten, and the
463 -block numbers are absolute block numbers on the drive regardless of which slice
464 -number is used to send the command.
465 -.sp
466 -.LP
467 -The \fBuscsi\fR interface is not recommended for very large data transfers
468 -(typically more than 16MB). If the requested transfer size exceeds the maximum
469 -transfer size of the DMA engine, it will not be broken up into multiple
470 -transfers and DMA errors may result. The \fBUSCSIMAXXFER\fR ioctl can be used
471 -to determine the maximum transfer size.
472 -.sp
473 -.LP
474 -The \fBUSCSICMD\fR ioctl associates a \fBstruct uscsi_cmd\fR with a device by
475 -using an open file descriptor to the device. Other APIs might provide the same
476 -\fBstruct uscsi_cmd\fR programming interface, but perform device association in
477 -some other manner.
365 +permissions on the device node.
366 +The device driver code expects to own the device state, and
367 +.Nm
368 +commands can change the state of the device and confuse the device driver.
369 +It is best to use
370 +.Nm
371 +commands only with no side effects, and avoid commands such as Mode Select, as
372 +they may cause damage to data stored on the drive or system panics.
373 +Also, as the commands are not checked in any way by the device driver, any block
374 +may be overwritten, and the block numbers are absolute block numbers on the
375 +drive regardless of which slice number is used to send the command.
376 +.Pp
377 +The
378 +.Nm
379 +interface is not recommended for very large data transfers
380 +(typically more than 16MB).
381 +If the requested transfer size exceeds the maximum transfer size of the DMA
382 +engine, it will not be broken up into multiple transfers and DMA errors may
383 +result.
384 +The
385 +.Dv USCSIMAXXFER
386 +ioctl can be used to determine the maximum transfer size.
387 +.Pp
388 +The
389 +.Dv USCSICMD
390 +ioctl associates a
391 +.Vt struct uscsi_cmd
392 +with a device by using an open file descriptor to the device.
393 +Other APIs might provide the same
394 +.Vt struct uscsi_cmd
395 +programming interface, but perform device association in some other manner.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX