1 USCSI(7I) Ioctl Requests USCSI(7I)
2
3
4
5 NAME
6 uscsi - user SCSI command interface
7
8 SYNOPSIS
9 #include <sys/scsi/impl/uscsi.h>
10
11 ioctl(int fildes, int request, struct uscsi_cmd *cmd);
12
13
14 DESCRIPTION
15 The uscsi command is very powerful and somewhat dangerous; therefore it
16 has some permission restrictions. See WARNINGS for more details.
17
18
19 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
27
28 Applications must not assume that all Solaris disk device drivers
29 support 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
39 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
53
54
55 The fields of the uscsi_cmd structure have the following meanings:
56
57 uscsi_flags
58 The I/O direction and other details of how to carry
59 out the SCSI command. Possible values are described
60 below.
61
62
63 uscsi_status
64 The SCSI status byte returned by the device is
65 returned in this field.
66
67
68 uscsi_timeout
69 Time in seconds to allow for completion of the
70 command.
71
72
73 uscsi_cdb
74 A pointer to the SCSI CDB (command descriptor
75 block) to be transferred to the device in command
76 phase.
77
78
79 uscsi_bufaddr
80 The user buffer containing the data to be read from
81 or written to the device.
82
83
84 uscsi_buflen
85 The length of uscsi_bufaddr.
86
87
88 uscsi_resid
89 If a data transfer terminates without transferring
90 the entire requested amount, the remainder, or
91 residue, is returned in this field.
92
93
94 uscsi_cdblen
95 The length of the SCSI CDB to be transferred to the
96 device in command phase.
97
98
99 uscsi_rqlen
100 The length of uscsi_rqbuf, the application's
101 Request Sense buffer.
102
103
104 uscsi_rqstatus
105 The SCSI status byte returned for the Request Sense
106 command executed automatically by the driver in
107 response to a Check Condition status return.
108
109
110 uscsi_rqresid
111 The residue, or untransferred data length, of the
112 Request Sense data transfer (the number of bytes,
113 less than or equal to uscsi_rqlen, which were not
114 filled with sense data).
115
116
117 uscsi_rqbuf
118 Points to a buffer in application address space to
119 which the results of an automatic Request Sense
120 command are written.
121
122
123 uscsi_reserved_5
124 Reserved for future use.
125
126
127
128 The uscsi_flags field defines the following:
129
130 USCSI_WRITE /* send data to device */
131 USCSI_SILENT /* no error messages */
132 USCSI_DIAGNOSE /* fail if any error occurs */
133 USCSI_ISOLATE /* isolate from normal commands */
134 USCSI_READ /* get data from device */
135 USCSI_ASYNC /* set bus to asynchronous mode */
136 USCSI_SYNC /* return bus to sync mode if possible */
137 USCSI_RESET /* reset target */
138 USCSI_RESET_TARGET /* reset target */
139 USCSI_RESET_LUN /* reset logical unit */
140 USCSI_RESET_ALL /* reset all targets */
141 USCSI_RQENABLE /* enable request sense extensions */
142 USCSI_RENEGOT /* renegotiate wide/sync on next I/O */
143
144
145
146 The uscsi_flags bits have the following interpretation:
147
148 USCSI_WRITE
149 Data will be written from the initiator to the
150 target.
151
152
153 USCSI_SILENT
154 The driver should not print any console error
155 messages or warnings regarding failures
156 associated with this SCSI command.
157
158
159 USCSI_DIAGNOSE
160 The driver should not attempt any retries or
161 other recovery mechanisms if this SCSI command
162 terminates abnormally in any way.
163
164
165 USCSI_ISOLATE
166 This SCSI command should not be executed with
167 other commands.
168
169
170 USCSI_READ
171 Data will be read from the target to the
172 initiator.
173
174
175 USCSI_ASYNC
176 Set the SCSI bus to asynchronous mode before
177 running this command.
178
179
180 USCSI_SYNC
181 Set the SCSI bus to synchronous mode before
182 running this command.
183
184
185 USCSI_RESET
186 Send a SCSI bus device reset message to this
187 target.
188
189
190 USCSI_RESET_TARGET
191 Same as USCSI_RESET. Use this flag to request
192 TARGET RESET. (USCSI_RESET is maintained only for
193 compatibility with old applications).
194
195
196 USCSI_RESET_LUN
197 Send a SCSI logical unit reset message to this
198 target.
199
200
201 USCSI_RESET_ALL
202 USCSI_RESET_ALL, USCSI_RESET/USCSI_RESET_TARGET
203 and USCSI_RESET_LUN are mutually exclusive
204 options and issuing them in any simultaneous
205 combination will result in implementation-
206 dependent behavior
207
208 When a USCSI reset request is combined with other
209 SCSI commands, the following semantics take
210 effect:
211
212 If the USCSI RESET flag is specified, the other
213 fields (other than uscsi_flags) in the uscsi_cmd
214 are ignored. The uscsi_cdblen must be set to
215 zero.
216
217
218 USCSI_RQENABLE
219 Enable Request Sense extensions. If the user
220 application is prepared to receive sense data,
221 this bit must be set, the fields uscsi_rqbuf and
222 uscsi_rqbuflen must be non-zero, and the
223 uscsi_rqbuf must point to memory writable by the
224 application.
225
226
227 USCSI_RENEGOT
228 Tells USCSI to renegotiate wide mode and
229 synchronous transfer speed before the transmitted
230 SCSI command is executed. This flag in effects
231 tells the target driver to pass the
232 FLAG_RENEGOTIATE_WIDE_SYNC flag in the SCSI
233 packet before passing the command to an adapter
234 driver for transport.
235
236 See the scsi_pkt(9S) flag
237 FLAG_RENEGOTIATE_WIDE_SYNC for more information.
238
239 The uscsi_xfer_t is a type definition that corresponds to a 64-bit
240 unsigned integer. It should be used for the USCSIMAXXFER ioctls. This
241 is used for determining the maximum transfer size that can be performed
242 in a single USCSICMD ioctl. If the SCSI request is larger than the
243 specified size, then it may not work, depending on the hardware
244 platform.
245
246
247 IOCTLS
248 The ioctl supported by drivers providing the uscsi interface is:
249
250 USCSICMD
251 The argument is a pointer to a uscsi_cmd structure. The
252 SCSI device addressed by that driver is selected, and given
253 the SCSI command addressed by uscsi_cdb. If this command
254 requires a data phase, the uscsi_buflen and uscsi_bufaddr
255 fields must be set appropriately; if data phase occurs, the
256 uscsi_resid is returned as the number of bytes not
257 transferred. The status of the command, as returned by the
258 device, is returned in the uscsi_status field. If the
259 command terminates with Check Condition status, and Request
260 Sense is enabled, the sense data itself is returned in
261 uscsi_rqbuf. The uscsi_rqresid provides the residue of the
262 Request Sense data transfer.
263
264
265 USCSIMAXXFER
266 The argument is a pointer to a uscsi_xfer_t value. The
267 maximum transfer size that can be used with the USCSICMD
268 ioctl for the current device will be returned in the
269 uscsi_xfer_t.
270
271
272 Not all devices which support the USCSICMD ioctl also
273 support the USCSIMAXXFER ioctl.
274
275
276 ERRORS
277 EINVAL
278 A parameter has an incorrect, or unsupported, value.
279
280
281 EIO
282 An error occurred during the execution of the command.
283
284
285 EPERM
286 A process without root credentials tried to execute the
287 USCSICMD or USCSIMAXXFER ioctl.
288
289
290 EFAULT
291 The uscsi_cmd itself, the uscsi_cdb, the uscsi_buf, the
292 uscsi_rqbuf, or the uscsi_xfer_t point to an invalid address.
293
294
295 ATTRIBUTES
296 See attributes(5) for descriptions of the following attributes:
297
298
299
300
301 +---------------------+-----------------+
302 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
303 +---------------------+-----------------+
304 |Interface Stability | Committed |
305 +---------------------+-----------------+
306
307 SEE ALSO
308 ioctl(2), attributes(5), sd(7D), st(7D)
309
310
311 ANSI Small Computer System Interface-2 (SCSI-2)
312
313 WARNINGS
314 The uscsi command is very powerful, but somewhat dangerous, and so its
315 use is restricted to processes running as root, regardless of the file
316 permissions on the device node. The device driver code expects to own
317 the device state, and uscsi commands can change the state of the device
318 and confuse the device driver. It is best to use uscsi commands only
319 with no side effects, and avoid commands such as Mode Select, as they
320 may cause damage to data stored on the drive or system panics. Also, as
321 the commands are not checked in any way by the device driver, any block
322 may be overwritten, and the block numbers are absolute block numbers on
323 the drive regardless of which slice number is used to send the command.
324
325
326 The uscsi interface is not recommended for very large data transfers
327 (typically more than 16MB). If the requested transfer size exceeds the
328 maximum transfer size of the DMA engine, it will not be broken up into
329 multiple transfers and DMA errors may result. The USCSIMAXXFER ioctl
330 can be used to determine the maximum transfer size.
331
332
333 The USCSICMD ioctl associates a struct uscsi_cmd with a device by using
334 an open file descriptor to the device. Other APIs might provide the
335 same struct uscsi_cmd programming interface, but perform device
336 association in some other manner.
337
338
339
340 September 23, 2016 USCSI(7I)
|
1 USCSI(7I) Ioctl Requests USCSI(7I)
2
3 NAME
4 uscsi - user SCSI command interface
5
6 SYNOPSIS
7 #include <sys/scsi/impl/uscsi.h>
8
9 ioctl(int filedes, int request, struct uscsi_cmd *cmd);
10
11 DESCRIPTION
12 The uscsi command is very powerful and somewhat dangerous; therefore it
13 has some permission restrictions. See WARNINGS for more details.
14
15 Drivers supporting this ioctl(2) provide a general interface allowing
16 user-level applications to cause individual SCSI commands to be directed
17 to a particular SCSI or ATAPI device under control of that driver. The
18 uscsi command is supported by the sd(7D) driver for SCSI disks and ATAPI
19 CD-ROM drives, and by the st(7D) driver for SCSI tape drives. uscsi may
20 also be supported by other device drivers; see the specific device driver
21 manual page for complete information.
22
23 Applications must not assume that all Solaris disk device drivers support
24 the uscsi ioctl command. The SCSI command may include a data transfer to
25 or from that device, if appropriate for that command. Upon completion of
26 the command, the user application can determine how many bytes were
27 transferred and the status returned by the device. Also, optionally, if
28 the command returns a Check Condition status, the driver will
29 automatically issue a Request Sense command and return the sense data
30 along with the original status. See the USCSI_RQENABLE flag below for
31 this Request Sense processing. The uscsi_cmd structure is defined in
32 <sys/scsi/impl/uscsi.h> and includes the following members:
33
34 int uscsi_flags; /* read, write, etc. see below */
35 short uscsi_status; /* resulting status */
36 short uscsi_timeout; /* Command Timeout */
37 caddr_t uscsi_cdb /* CDB to send to target */
38 caddr_t uscsi_bufaddr; /* i/o source/destination */
39 size_t uscsi_buflen; /* size of i/o to take place*/
40 size_t uscsi_resid; /* resid from i/o operation */
41 uchar_t uscsi_cdblen; /* # of valid CDB bytes */
42 uchar_t uscsi_rqlen; /* size of uscsi_rqbuf */
43 uchar_t uscsi_rqstatus; /* status of request sense cmd */
44 uchar_t uscsi_rqresid; /* resid of request sense cmd */
45 caddr_t uscsi_rqbuf; /* request sense buffer */
46 void *uscsi_reserved_5; /* Reserved for future use */
47
48 The fields of the uscsi_cmd structure have the following meanings:
49
50 uscsi_flags The I/O direction and other details of how to carry out
51 the SCSI command. Possible values are described below.
52
53 uscsi_status The SCSI status byte returned by the device is returned
54 in this field.
55
56 uscsi_timeout Time in seconds to allow for completion of the command.
57
58 uscsi_cdb A pointer to the SCSI CDB (command descriptor block) to
59 be transferred to the device in command phase.
60
61 uscsi_bufaddr The user buffer containing the data to be read from or
62 written to the device.
63
64 uscsi_buflen The length of uscsi_bufaddr.
65
66 uscsi_resid If a data transfer terminates without transferring the
67 entire requested amount, the remainder, or residue, is
68 returned in this field.
69
70 uscsi_cdblen The length of the SCSI CDB to be transferred to the
71 device in command phase.
72
73 uscsi_rqlen The length of uscsi_rqbuf, the application's Request
74 Sense buffer.
75
76 uscsi_rqstatus The SCSI status byte returned for the Request Sense
77 command executed automatically by the driver in
78 response to a Check Condition status return.
79
80 uscsi_rqresid The residue, or untransferred data length, of the
81 Request Sense data transfer (the number of bytes, less
82 than or equal to uscsi_rqlen, which were not filled
83 with sense data).
84
85 uscsi_rqbuf Points to a buffer in application address space to
86 which the results of an automatic Request Sense command
87 are written.
88
89 uscsi_reserved_5 Reserved for future use.
90
91 The uscsi_flags field defines the following:
92
93 USCSI_WRITE /* send data to device */
94 USCSI_SILENT /* no error messages */
95 USCSI_DIAGNOSE /* fail if any error occurs */
96 USCSI_ISOLATE /* isolate from normal commands */
97 USCSI_READ /* get data from device */
98 USCSI_ASYNC /* set bus to asynchronous mode */
99 USCSI_SYNC /* return bus to sync mode if possible */
100 USCSI_RESET /* reset target */
101 USCSI_RESET_TARGET /* reset target */
102 USCSI_RESET_LUN /* reset logical unit */
103 USCSI_RESET_ALL /* reset all targets */
104 USCSI_RQENABLE /* enable request sense extensions */
105 USCSI_RENEGOT /* renegotiate wide/sync on next I/O */
106
107 The uscsi_flags bits have the following interpretation:
108
109 USCSI_WRITE Data will be written from the initiator to the
110 target.
111
112 USCSI_SILENT The driver should not print any console error
113 messages or warnings regarding failures associated
114 with this SCSI command.
115
116 USCSI_DIAGNOSE The driver should not attempt any retries or other
117 recovery mechanisms if this SCSI command terminates
118 abnormally in any way.
119
120 USCSI_ISOLATE This SCSI command should not be executed with other
121 commands.
122
123 USCSI_READ Data will be read from the target to the initiator.
124
125 USCSI_ASYNC Set the SCSI bus to asynchronous mode before running
126 this command.
127
128 USCSI_SYNC Set the SCSI bus to synchronous mode before running
129 this command.
130
131 USCSI_RESET Send a SCSI bus device reset message to this target.
132
133 USCSI_RESET_TARGET Same as USCSI_RESET. Use this flag to request TARGET
134 RESET. (USCSI_RESET is maintained only for
135 compatibility with old applications).
136
137 USCSI_RESET_LUN Send a SCSI logical unit reset message to this
138 target.
139
140 USCSI_RESET_ALL USCSI_RESET_ALL, USCSI_RESET/USCSI_RESET_TARGET, and
141 USCSI_RESET_LUN are mutually exclusive options and
142 issuing them in any simultaneous combination will
143 result in implementation-dependent behavior When a
144 USCSI reset request is combined with other SCSI
145 commands, the following semantics take effect: If the
146 USCSI RESET flag is specified, the other fields
147 (other than uscsi_flags) in the uscsi_cmd are
148 ignored. The uscsi_cdblen field must be set to zero.
149
150 USCSI_RQENABLE Enable Request Sense extensions. If the user
151 application is prepared to receive sense data, this
152 bit must be set, the fields uscsi_rqbuf and
153 uscsi_rqbuflen must be non-zero, and the uscsi_rqbuf
154 must point to memory writable by the application.
155
156 USCSI_RENEGOT Tells USCSI to renegotiate wide mode and synchronous
157 transfer speed before the transmitted SCSI command is
158 executed. This flag in effects tells the target
159 driver to pass the FLAG_RENEGOTIATE_WIDE_SYNC flag in
160 the SCSI packet before passing the command to an
161 adapter driver for transport. See the scsi_pkt(9S)
162 flag FLAG_RENEGOTIATE_WIDE_SYNC for more information.
163
164 The uscsi_xfer_t is a type definition that corresponds to a 64-bit
165 unsigned integer. It should be used for the USCSIMAXXFER ioctls. This
166 is used for determining the maximum transfer size that can be performed
167 in a single USCSICMD ioctl. If the SCSI request is larger than the
168 specified size, then it may not work, depending on the hardware platform.
169
170 IOCTLS
171 The ioctl() supported by drivers providing the uscsi interface is:
172
173 USCSICMD The argument is a pointer to a uscsi_cmd structure. The
174 SCSI device addressed by that driver is selected, and given
175 the SCSI command addressed by uscsi_cdb. If this command
176 requires a data phase, the uscsi_buflen and uscsi_bufaddr
177 fields must be set appropriately; if data phase occurs, the
178 uscsi_resid is returned as the number of bytes not
179 transferred. The status of the command, as returned by the
180 device, is returned in the uscsi_status field. If the
181 command terminates with Check Condition status, and Request
182 Sense is enabled, the sense data itself is returned in
183 uscsi_rqbuf. The uscsi_rqresid provides the residue of the
184 Request Sense data transfer.
185
186 USCSIMAXXFER The argument is a pointer to a uscsi_xfer_t value. The
187 maximum transfer size that can be used with the USCSICMD
188 ioctl for the current device will be returned in the
189 uscsi_xfer_t.
190
191 Not all devices which support the USCSICMD ioctl also
192 support the USCSIMAXXFER ioctl.
193
194 ERRORS
195 EINVAL A parameter has an incorrect, or unsupported, value.
196
197 EIO An error occurred during the execution of the command.
198
199 EPERM A process without root credentials tried to execute the USCSICMD
200 or USCSIMAXXFER ioctl.
201
202 EFAULT The uscsi_cmd itself, the uscsi_cdb, the uscsi_buf, the
203 uscsi_rqbuf, or the uscsi_xfer_t point to an invalid address.
204
205 STABILITY
206 Committed
207
208 SEE ALSO
209 ioctl(2), attributes(5), sd(7D), st(7D)
210
211 ANSI Small Computer System Interface-2 (SCSI-2).
212
213 WARNINGS
214 The uscsi command is very powerful, but somewhat dangerous, and so its
215 use is restricted to processes running as root, regardless of the file
216 permissions on the device node. The device driver code expects to own
217 the device state, and uscsi commands can change the state of the device
218 and confuse the device driver. It is best to use uscsi commands only
219 with no side effects, and avoid commands such as Mode Select, as they may
220 cause damage to data stored on the drive or system panics. Also, as the
221 commands are not checked in any way by the device driver, any block may
222 be overwritten, and the block numbers are absolute block numbers on the
223 drive regardless of which slice number is used to send the command.
224
225 The uscsi interface is not recommended for very large data transfers
226 (typically more than 16MB). If the requested transfer size exceeds the
227 maximum transfer size of the DMA engine, it will not be broken up into
228 multiple transfers and DMA errors may result. The USCSIMAXXFER ioctl can
229 be used to determine the maximum transfer size.
230
231 The USCSICMD ioctl associates a struct uscsi_cmd with a device by using
232 an open file descriptor to the device. Other APIs might provide the same
233 struct uscsi_cmd programming interface, but perform device association in
234 some other manner.
235
236 illumos October 23, 2017 illumos
|