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