USCSI(7I) Ioctl Requests USCSI(7I) NNAAMMEE uussccssii - user SCSI command interface SSYYNNOOPPSSIISS ##iinncclluuddee <> iiooccttll(_i_n_t _f_i_l_e_d_e_s, _i_n_t _r_e_q_u_e_s_t, _s_t_r_u_c_t _u_s_c_s_i___c_m_d _*_c_m_d); DDEESSCCRRIIPPTTIIOONN The uussccssii command is very powerful and somewhat dangerous; therefore it has some permission restrictions. See _W_A_R_N_I_N_G_S for more details. Drivers supporting this ioctl(2) provide a general interface allowing user-level applications to cause individual SSCCSSII commands to be directed to a particular SSCCSSII or AATTAAPPII device under control of that driver. The uussccssii command is supported by the sd(7D) driver for SSCCSSII disks and AATTAAPPII CD-ROM drives, and by the st(7D) driver for SSCCSSII tape drives. uussccssii may also be supported by other device drivers; see the specific device driver manual page for complete information. Applications must not assume that all Solaris disk device drivers support the uussccssii ioctl command. The SSCCSSII command may include a data transfer to or from that device, if appropriate for that command. Upon completion of the command, the user application can determine how many bytes were transferred and the status returned by the device. Also, optionally, if the command returns a Check Condition status, the driver will automatically issue a Request Sense command and return the sense data along with the original status. See the UUSSCCSSII__RRQQEENNAABBLLEE flag below for this Request Sense processing. The _u_s_c_s_i___c_m_d structure is defined in <_s_y_s_/_s_c_s_i_/_i_m_p_l_/_u_s_c_s_i_._h> and includes the following members: int uscsi_flags; /* read, write, etc. see below */ short uscsi_status; /* resulting status */ short uscsi_timeout; /* Command Timeout */ caddr_t uscsi_cdb /* CDB to send to target */ caddr_t uscsi_bufaddr; /* i/o source/destination */ size_t uscsi_buflen; /* size of i/o to take place*/ size_t uscsi_resid; /* resid from i/o operation */ uchar_t uscsi_cdblen; /* # of valid CDB bytes */ uchar_t uscsi_rqlen; /* size of uscsi_rqbuf */ uchar_t uscsi_rqstatus; /* status of request sense cmd */ uchar_t uscsi_rqresid; /* resid of request sense cmd */ caddr_t uscsi_rqbuf; /* request sense buffer */ void *uscsi_reserved_5; /* Reserved for future use */ The fields of the _u_s_c_s_i___c_m_d structure have the following meanings: uussccssii__ffllaaggss The II//OO direction and other details of how to carry out the SSCCSSII command. Possible values are described below. _u_s_c_s_i___s_t_a_t_u_s The SSCCSSII status byte returned by the device is returned in this field. _u_s_c_s_i___t_i_m_e_o_u_t Time in seconds to allow for completion of the command. _u_s_c_s_i___c_d_b A pointer to the SSCCSSII CDB (command descriptor block) to be transferred to the device in command phase. _u_s_c_s_i___b_u_f_a_d_d_r The user buffer containing the data to be read from or written to the device. uussccssii__bbuufflleenn The length of _u_s_c_s_i___b_u_f_a_d_d_r. _u_s_c_s_i___r_e_s_i_d If a data transfer terminates without transferring the entire requested amount, the remainder, or residue, is returned in this field. _u_s_c_s_i___c_d_b_l_e_n The length of the SSCCSSII CDB to be transferred to the device in command phase. _u_s_c_s_i___r_q_l_e_n The length of _u_s_c_s_i___r_q_b_u_f, the application's Request Sense buffer. _u_s_c_s_i___r_q_s_t_a_t_u_s The SSCCSSII status byte returned for the Request Sense command executed automatically by the driver in response to a Check Condition status return. _u_s_c_s_i___r_q_r_e_s_i_d The residue, or untransferred data length, of the Request Sense data transfer (the number of bytes, less than or equal to _u_s_c_s_i___r_q_l_e_n, which were not filled with sense data). _u_s_c_s_i___r_q_b_u_f Points to a buffer in application address space to which the results of an automatic Request Sense command are written. _u_s_c_s_i___r_e_s_e_r_v_e_d___5 Reserved for future use. The _u_s_c_s_i___f_l_a_g_s field defines the following: USCSI_WRITE /* send data to device */ USCSI_SILENT /* no error messages */ USCSI_DIAGNOSE /* fail if any error occurs */ USCSI_ISOLATE /* isolate from normal commands */ USCSI_READ /* get data from device */ USCSI_ASYNC /* set bus to asynchronous mode */ USCSI_SYNC /* return bus to sync mode if possible */ USCSI_RESET /* reset target */ USCSI_RESET_TARGET /* reset target */ USCSI_RESET_LUN /* reset logical unit */ USCSI_RESET_ALL /* reset all targets */ USCSI_RQENABLE /* enable request sense extensions */ USCSI_RENEGOT /* renegotiate wide/sync on next I/O */ The _u_s_c_s_i___f_l_a_g_s bits have the following interpretation: USCSI_WRITE Data will be written from the initiator to the target. USCSI_SILENT The driver should not print any console error messages or warnings regarding failures associated with this SSCCSSII command. USCSI_DIAGNOSE The driver should not attempt any retries or other recovery mechanisms if this SSCCSSII command terminates abnormally in any way. USCSI_ISOLATE This SSCCSSII command should not be executed with other commands. USCSI_READ Data will be read from the target to the initiator. USCSI_ASYNC Set the SSCCSSII bus to asynchronous mode before running this command. USCSI_SYNC Set the SSCCSSII bus to synchronous mode before running this command. USCSI_RESET Send a SSCCSSII bus device reset message to this target. USCSI_RESET_TARGET Same as USCSI_RESET. Use this flag to request TARGET RESET. (USCSI_RESET is maintained only for compatibility with old applications). USCSI_RESET_LUN Send a SSCCSSII logical unit reset message to this target. USCSI_RESET_ALL USCSI_RESET_ALL, USCSI_RESET/USCSI_RESET_TARGET, and USCSI_RESET_LUN are mutually exclusive options and issuing them in any simultaneous combination will result in implementation-dependent behavior When a USCSI reset request is combined with other SSCCSSII commands, the following semantics take effect: If the USCSI RESET flag is specified, the other fields (other than _u_s_c_s_i___f_l_a_g_s) in the _u_s_c_s_i___c_m_d are ignored. The _u_s_c_s_i___c_d_b_l_e_n field _m_u_s_t be set to zero. USCSI_RQENABLE Enable Request Sense extensions. If the user application is prepared to receive sense data, this bit must be set, the fields _u_s_c_s_i___r_q_b_u_f and _u_s_c_s_i___r_q_b_u_f_l_e_n must be non-zero, and the _u_s_c_s_i___r_q_b_u_f must point to memory writable by the application. USCSI_RENEGOT Tells USCSI to renegotiate wide mode and synchronous transfer speed before the transmitted SCSI command is executed. This flag in effects tells the target driver to pass the FLAG_RENEGOTIATE_WIDE_SYNC flag in the SCSI packet before passing the command to an adapter driver for transport. See the scsi_pkt(9S) flag FLAG_RENEGOTIATE_WIDE_SYNC for more information. The _u_s_c_s_i___x_f_e_r___t is a type definition that corresponds to a 64-bit unsigned integer. It should be used for the USCSIMAXXFER ioctls. This is used for determining the maximum transfer size that can be performed in a single USCSICMD ioctl. If the SCSI request is larger than the specified size, then it may not work, depending on the hardware platform. IIOOCCTTLLSS The iiooccttll() supported by drivers providing the uussccssii interface is: USCSICMD The argument is a pointer to a _u_s_c_s_i___c_m_d structure. The SSCCSSII device addressed by that driver is selected, and given the SSCCSSII command addressed by _u_s_c_s_i___c_d_b. If this command requires a data phase, the _u_s_c_s_i___b_u_f_l_e_n and _u_s_c_s_i___b_u_f_a_d_d_r fields must be set appropriately; if data phase occurs, the _u_s_c_s_i___r_e_s_i_d is returned as the number of bytes not transferred. The status of the command, as returned by the device, is returned in the _u_s_c_s_i___s_t_a_t_u_s field. If the command terminates with Check Condition status, and Request Sense is enabled, the sense data itself is returned in _u_s_c_s_i___r_q_b_u_f. The _u_s_c_s_i___r_q_r_e_s_i_d provides the residue of the Request Sense data transfer. USCSIMAXXFER The argument is a pointer to a _u_s_c_s_i___x_f_e_r___t value. The maximum transfer size that can be used with the USCSICMD ioctl for the current device will be returned in the _u_s_c_s_i___x_f_e_r___t. Not all devices which support the USCSICMD ioctl also support the USCSIMAXXFER ioctl. EERRRROORRSS EINVAL A parameter has an incorrect, or unsupported, value. EIO An error occurred during the execution of the command. EPERM A process without root credentials tried to execute the USCSICMD or USCSIMAXXFER ioctl. EFAULT The _u_s_c_s_i___c_m_d itself, the _u_s_c_s_i___c_d_b, the _u_s_c_s_i___b_u_f, the _u_s_c_s_i___r_q_b_u_f, or the _u_s_c_s_i___x_f_e_r___t point to an invalid address. SSTTAABBIILLIITTYY Committed SSEEEE AALLSSOO ioctl(2), attributes(5), sd(7D), st(7D) _A_N_S_I _S_m_a_l_l _C_o_m_p_u_t_e_r _S_y_s_t_e_m _I_n_t_e_r_f_a_c_e_-_2 _(_S_C_S_I_-_2_). WWAARRNNIINNGGSS The uussccssii command is very powerful, but somewhat dangerous, and so its use is restricted to processes running as root, regardless of the file permissions on the device node. The device driver code expects to own the device state, and uussccssii commands can change the state of the device and confuse the device driver. It is best to use uussccssii commands only with no side effects, and avoid commands such as Mode Select, as they may cause damage to data stored on the drive or system panics. Also, as the commands are not checked in any way by the device driver, any block may be overwritten, and the block numbers are absolute block numbers on the drive regardless of which slice number is used to send the command. The uussccssii interface is not recommended for very large data transfers (typically more than 16MB). If the requested transfer size exceeds the maximum transfer size of the DMA engine, it will not be broken up into multiple transfers and DMA errors may result. The USCSIMAXXFER ioctl can be used to determine the maximum transfer size. The USCSICMD ioctl associates a _s_t_r_u_c_t _u_s_c_s_i___c_m_d with a device by using an open file descriptor to the device. Other APIs might provide the same _s_t_r_u_c_t _u_s_c_s_i___c_m_d programming interface, but perform device association in some other manner. illumos October 23, 2017 illumos