USCSI(4I) | Ioctl Requests | USCSI(4I) |
uscsi
— user SCSI
command interface
#include
<sys/scsi/impl/uscsi.h>
ioctl
(int filedes,
int request, struct uscsi_cmd
*cmd);
The uscsi
command is very powerful and
somewhat dangerous; therefore it has some permission restrictions. See
WARNINGS for more details.
Drivers supporting this
ioctl(2) provide a general interface
allowing user-level applications to cause individual SCSI
commands to be directed to a particular SCSI or
ATAPI device under control of that driver. The
uscsi
command is supported by the
sd(4D) driver for SCSI
disks and ATAPI CD-ROM drives, and by the
st(4D) driver for SCSI
tape drives. uscsi
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 uscsi
ioctl command. The
SCSI 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
USCSI_RQENABLE flag below for this Request Sense
processing. The uscsi_cmd structure is defined in
<sys/scsi/impl/uscsi.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 uscsi_cmd structure have the following meanings:
The uscsi_flags 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 uscsi_flags bits have the following interpretation:
USCSI_WRITE
USCSI_SILENT
USCSI_DIAGNOSE
USCSI_ISOLATE
USCSI_READ
USCSI_ASYNC
USCSI_SYNC
USCSI_RESET
USCSI_RESET_TARGET
USCSI_RESET
is maintained only for compatibility
with old applications).USCSI_RESET_LUN
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 SCSI commands, the following semantics take
effect: If the USCSI RESET
flag is specified, the
other fields (other than uscsi_flags) in the
uscsi_cmd are ignored. The
uscsi_cdblen field
must be
set to zero.USCSI_RQENABLE
USCSI_RENEGOT
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 uscsi_xfer_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.
The
ioctl
()
supported by drivers providing the uscsi
interface
is:
USCSICMD
USCSIMAXXFER
USCSICMD
ioctl for the current device will be
returned in the uscsi_xfer_t.
Not all devices which support the
USCSICMD
ioctl also support the
USCSIMAXXFER
ioctl.
EINVAL
EIO
EPERM
USCSICMD
or USCSIMAXXFER
ioctl.EFAULT
Committed
ioctl(2), sd(4D), st(4D), attributes(7)
ANSI Small Computer System Interface-2 (SCSI-2).
The uscsi
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
uscsi
commands can change the state of the device
and confuse the device driver. It is best to use
uscsi
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 uscsi
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
struct uscsi_cmd with a device by using an open file
descriptor to the device. Other APIs might provide the same
struct uscsi_cmd programming interface, but perform
device association in some other manner.
March 13, 2022 | OmniOS |