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