1uscsi(7I) Ioctl Requests uscsi(7I)
2
6 uscsi - user SCSI command interface
7
9 #include <sys/scsi/impl/uscsi.h>
10 ioctl(int fildes, int request, struct uscsi_cmd *cmd);
12
15 The uscsi command is very powerful and somewhat dangerous; therefore it
16 has some permission restrictions. See WARNINGS for more details.
17 Drivers supporting this ioctl(2) provide a general interface allowing
20 user-level applications to cause individual SCSI commands to be
21 directed to a particular SCSI or ATAPI device under control of that
22 driver. The uscsi command is supported by the sd driver for SCSI disks
23 and ATAPI CD-ROM drives, and by the st driver for SCSI tape drives.
24 uscsi may also be supported by other device drivers; see the specific
25 device driver manual page for complete information.
26 Applications must not assume that all Solaris disk device drivers sup‐
29 port the uscsi ioctl command. The SCSI command may include a data
30 transfer to or from that device, if appropriate for that command. Upon
31 completion of the command, the user application can determine how many
32 bytes were transferred and the status returned by the device. Also,
33 optionally, if the command returns a Check Condition status, the driver
34 will automatically issue a Request Sense command and return the sense
35 data along with the original status. See the USCSI_RQENABLE flag below
36 for this Request Sense processing. The uscsi_cmd structure is defined
37 in <sys/scsi/impl/uscsi.h> and includes the following members:
38 int uscsi_flags; /* read, write, etc. see below */
40 short uscsi_status; /* resulting status */
41 short uscsi_timeout; /* Command Timeout */
42 caddr_t uscsi_cdb /* CDB to send to target */
43 caddr_t uscsi_bufaddr; /* i/o source/destination */
44 size_t uscsi_buflen; /* size of i/o to take place*/
45 size_t uscsi_resid; /* resid from i/o operation */
46 uchar_t uscsi_cdblen; /* # of valid CDB bytes */
47 uchar_t uscsi_rqlen; /* size of uscsi_rqbuf */
48 uchar_t uscsi_rqstatus; /* status of request sense cmd */
49 uchar_t uscsi_rqresid; /* resid of request sense cmd */
50 caddr_t uscsi_rqbuf; /* request sense buffer */
51 void *uscsi_reserved_5; /* Reserved for future use */
52 The fields of the uscsi_cmd structure have the following meanings:
56 uscsi_flags The I/O direction and other details of how to carry
58 out the SCSI command. Possible values are described
59 below.
60 uscsi_status The SCSI status byte returned by the device is
63 returned in this field.
64 uscsi_timeout Time in seconds to allow for completion of the com‐
67 mand.
68 uscsi_cdb A pointer to the SCSI CDB (command descriptor
71 block) to be transferred to the device in command
72 phase.
73 uscsi_bufaddr The user buffer containing the data to be read from
76 or written to the device.
77 uscsi_buflen The length of uscsi_bufaddr.
80 uscsi_resid If a data transfer terminates without transferring
83 the entire requested amount, the remainder, or
84 residue, is returned in this field.
85 uscsi_cdblen The length of the SCSI CDB to be transferred to the
88 device in command phase.
89 uscsi_rqlen The length of uscsi_rqbuf, the application's
92 Request Sense buffer.
93 uscsi_rqstatus The SCSI status byte returned for the Request Sense
96 command executed automatically by the driver in
97 response to a Check Condition status return.
98 uscsi_rqresid The residue, or untransferred data length, of the
101 Request Sense data transfer (the number of bytes,
102 less than or equal to uscsi_rqlen, which were not
103 filled with sense data).
104 uscsi_rqbuf Points to a buffer in application address space to
107 which the results of an automatic Request Sense
108 command are written.
109 uscsi_reserved_5 Reserved for future use.
112 The uscsi_flags field defines the following:
116 USCSI_WRITE /* send data to device */
118 USCSI_SILENT /* no error messages */
119 USCSI_DIAGNOSE /* fail if any error occurs */
120 USCSI_ISOLATE /* isolate from normal commands */
121 USCSI_READ /* get data from device */
122 USCSI_ASYNC /* set bus to asynchronous mode */
123 USCSI_SYNC /* return bus to sync mode if possible */
124 USCSI_RESET /* reset target */
125 USCSI_RESET_TARGET /* reset target */
126 USCSI_RESET_LUN /* reset logical unit */
127 USCSI_RESET_ALL /* reset all targets */
128 USCSI_RQENABLE /* enable request sense extensions */
129 USCSI_RENEGOT /* renegotiate wide/sync on next I/O */
130 The uscsi_flags bits have the following interpretation:
134 USCSI_WRITE Data will be written from the initiator to the
136 target.
137 USCSI_SILENT The driver should not print any console error
140 messages or warnings regarding failures associ‐
141 ated with this SCSI command.
142 USCSI_DIAGNOSE The driver should not attempt any retries or
145 other recovery mechanisms if this SCSI command
146 terminates abnormally in any way.
147 USCSI_ISOLATE This SCSI command should not be executed with
150 other commands.
151 USCSI_READ Data will be read from the target to the initia‐
154 tor.
155 USCSI_ASYNC Set the SCSI bus to asynchronous mode before run‐
158 ning this command.
159 USCSI_SYNC Set the SCSI bus to synchronous mode before run‐
162 ning this command.
163 USCSI_RESET Send a SCSI bus device reset message to this tar‐
166 get.
167 USCSI_RESET_TARGET Same as USCSI_RESET. Use this flag to request
170 TARGET RESET. (USCSI_RESET is maintained only for
171 compatibility with old applications).
172 USCSI_RESET_LUN Send a SCSI logical unit reset message to this
175 target.
176 USCSI_RESET_ALL USCSI_RESET_ALL, USCSI_RESET/USCSI_RESET_TARGET
179 and USCSI_RESET_LUN are mutually exclusive
180 options and issuing them in any simultaneous com‐
181 bination will result in implementation-dependent
182 behavior
183 When a USCSI reset request is combined with other
185 SCSI commands, the following semantics take
186 effect:
187 If the USCSI RESET flag is specified, the other
189 fields (other than uscsi_flags) in the uscsi_cmd
190 are ignored. The uscsi_cdblen must be set to
191 zero.
192 USCSI_RQENABLE Enable Request Sense extensions. If the user
195 application is prepared to receive sense data,
196 this bit must be set, the fields uscsi_rqbuf and
197 uscsi_rqbuflen must be non-zero, and the
198 uscsi_rqbuf must point to memory writable by the
199 application.
200 USCSI_RENEGOT Tells USCSI to renegotiate wide mode and synchro‐
203 nous transfer speed before the transmitted SCSI
204 command is executed. This flag in effects tells
205 the target driver to pass the FLAG_RENEGOTI‐
206 ATE_WIDE_SYNC flag in the SCSI packet before
207 passing the command to an adapter driver for
208 transport.
209 See the scsi_pkt(9S) flag FLAG_RENEGOTI‐
211 ATE_WIDE_SYNC for more information.
212
215 The ioctl supported by drivers providing the uscsi interface is:
216 USCSICMD The argument is a pointer to a uscsi_cmd structure. The
218 SCSI device addressed by that driver is selected, and given
219 the SCSI command addressed by uscsi_cdb. If this command
220 requires a data phase, the uscsi_buflen and uscsi_bufaddr
221 fields must be set appropriately; if data phase occurs, the
222 uscsi_resid is returned as the number of bytes not trans‐
223 ferred. The status of the command, as returned by the
224 device, is returned in the uscsi_status field. If the com‐
225 mand terminates with Check Condition status, and Request
226 Sense is enabled, the sense data itself is returned in
227 uscsi_rqbuf. The uscsi_rqresid provides the residue of the
228 Request Sense data transfer.
229
232 EINVAL A parameter has an incorrect, or unsupported, value.
233 EIO An error occurred during the execution of the command.
236 EPERM A process without root credentials tried to execute the USC‐
239 SICMD ioctl.
240 EFAULT The uscsi_cmd itself, the uscsi_cdb, the uscsi_buf, or the
243 uscsi_rqbuf point to an invalid address.
244
247 See attributes(5) for descriptions of the following attributes:
248 ┌─────────────────────────────┬─────────────────────────────┐
253 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
254 ├─────────────────────────────┼─────────────────────────────┤
255 │Availability │SUNWhea │
256 ├─────────────────────────────┼─────────────────────────────┤
257 │Interface Stability │Committed │
258 └─────────────────────────────┴─────────────────────────────┘
259
261 ioctl(2), attributes(5), sd(7D), st(7D)
262 ANSI Small Computer System Interface-2 (SCSI-2)
265
267 The uscsi command is very powerful, but somewhat dangerous, and so its
268 use is restricted to processes running as root, regardless of the file
269 permissions on the device node. The device driver code expects to own
270 the device state, and uscsi commands can change the state of the device
271 and confuse the device driver. It is best to use uscsi commands only
272 with no side effects, and avoid commands such as Mode Select, as they
273 may cause damage to data stored on the drive or system panics. Also, as
274 the commands are not checked in any way by the device driver, any block
275 may be overwritten, and the block numbers are absolute block numbers on
276 the drive regardless of which slice number is used to send the command.
277 The uscsi interface is not recommended for very large data transfers
280 (typically more than 16MB). If the requested transfer size exceeds the
281 maximum transfer size of the DMA engine, it will not be broken up into
282 multiple transfers and DMA errors may result.
283 The USCSICMD ioctl associates a struct uscsi_cmd with a device by using
286 an open file descriptor to the device. Other APIs might provide the
287 same struct uscsi_cmd programming interface, but perform device associ‐
288 ation in some other manner.
289SunOS 5.11 29 May 2007 uscsi(7I)