1 .\" Copyright (c) 2007 by Sun Microsystems, Inc. All rights reserved. 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 63 specific device driver manual page for complete information. 64 .Pp 65 Applications must not assume that all Solaris disk device drivers support the 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 75 Check Condition status, the driver will automatically issue a Request Sense 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 */ 87 short uscsi_status; /* resulting status */ 88 short uscsi_timeout; /* Command Timeout */ 89 caddr_t uscsi_cdb /* CDB to send to target */ 90 caddr_t uscsi_bufaddr; /* i/o source/destination */ 91 size_t uscsi_buflen; /* size of i/o to take place*/ 92 size_t uscsi_resid; /* resid from i/o operation */ 93 uchar_t uscsi_cdblen; /* # of valid CDB bytes */ 94 uchar_t uscsi_rqlen; /* size of uscsi_rqbuf */ 95 uchar_t uscsi_rqstatus; /* status of request sense cmd */ 96 uchar_t uscsi_rqresid; /* resid of request sense cmd */ 97 caddr_t uscsi_rqbuf; /* request sense buffer */ 98 void *uscsi_reserved_5; /* Reserved for future use */ 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 117 Time in seconds to allow for completion of the command. 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 123 The user buffer containing the data to be read from or written to the device. 124 .It Sy uscsi_buflen 125 The length of 126 .Fa uscsi_bufaddr . 127 .It Fa uscsi_resid 128 If a data transfer terminates without transferring the entire requested amount, 129 the remainder, or residue, is returned in this field. 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 142 automatically by the driver in response to a Check Condition status return. 143 .It Fa uscsi_rqresid 144 The residue, or untransferred data length, of the Request Sense data transfer 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 149 Points to a buffer in application address space to which the results of an 150 automatic Request Sense command are written. 151 .It Fa uscsi_reserved_5 152 Reserved for future use. 153 .El 154 .Pp 155 The 156 .Fa uscsi_flags 157 field defines the following: 158 .Bd -literal -offset 2n 159 USCSI_WRITE /* send data to device */ 160 USCSI_SILENT /* no error messages */ 161 USCSI_DIAGNOSE /* fail if any error occurs */ 162 USCSI_ISOLATE /* isolate from normal commands */ 163 USCSI_READ /* get data from device */ 164 USCSI_ASYNC /* set bus to asynchronous mode */ 165 USCSI_SYNC /* return bus to sync mode if possible */ 166 USCSI_RESET /* reset target */ 167 USCSI_RESET_TARGET /* reset target */ 168 USCSI_RESET_LUN /* reset logical unit */ 169 USCSI_RESET_ALL /* reset all targets */ 170 USCSI_RQENABLE /* enable request sense extensions */ 171 USCSI_RENEGOT /* renegotiate wide/sync on next I/O */ 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 179 Data will be written from the initiator to the target. 180 .It Dv USCSI_SILENT 181 The driver should not print any console error messages or warnings regarding 182 failures associated with this 183 .Sy SCSI 184 command. 185 .It Dv USCSI_DIAGNOSE 186 The driver should not attempt any retries or other recovery mechanisms if this 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 194 Data will be read from the target to the initiator. 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 224 mutually exclusive options and issuing them in any simultaneous combination 225 will result in implementation-dependent behavior 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 252 Tells USCSI to renegotiate wide mode and synchronous transfer speed before the 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 257 before passing the command to an adapter driver for transport. 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 272 used for determining the maximum transfer size that can be performed in a single 273 .Dv USCSICMD 274 ioctl. 275 If the SCSI request is larger than the specified size, 276 then it may not work, depending on the hardware platform. 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 305 status, and Request Sense is enabled, the sense data itself is returned in 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 328 A parameter has an incorrect, or unsupported, value. 329 .It Er EIO 330 An error occurred during the execution of the command. 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 364 use is restricted to processes running as root, regardless of the file 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.