Ioctl Requests uscsi(7I)
NAME
uscsi - user SCSI command interface
SYNOPSIS
#include
ioctl(int fildes, int request, struct uscsicmd *cmd);
DESCRIPTION
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 driver for SCSI disks and ATAPI CD-ROM drives, and
by the st 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 com-
mand, 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 USCSIRQENABLE flag below for this Request Sense
processing. The uscsicmd structure is defined in
and includes the following members:
int uscsiflags; /* read, write, etc. see below */
short uscsistatus; /* resulting status */
short uscsitimeout; /* Command Timeout */
caddrt uscsicdb /* CDB to send to target */
caddrt uscsibufaddr; /* i/o source/destination */
sizet uscsibuflen; /* size of i/o to take place*/
sizet uscsiresid; /* resid from i/o operation */
uchart uscsicdblen; /* # of valid CDB bytes */
uchart uscsirqlen; /* size of uscsirqbuf */
uchart uscsirqstatus; /* status of request sense cmd */
uchart uscsirqresid; /* resid of request sense cmd */
caddrt uscsirqbuf; /* request sense buffer */
void *uscsireserved5; /* Reserved for future use */
SunOS 5.11 Last change: 29 May 2007 1
Ioctl Requests uscsi(7I)
The fields of the uscsicmd structure have the following
meanings:
uscsiflags The I/O direction and other details of
how to carry out the SCSI command. Pos-
sible values are described below.
uscsistatus The SCSI status byte returned by the
device is returned in this field.
uscsitimeout Time in seconds to allow for completion
of the command.
uscsicdb A pointer to the SCSI CDB (command
descriptor block) to be transferred to
the device in command phase.
uscsibufaddr The user buffer containing the data to
be read from or written to the device.
uscsibuflen The length of uscsibufaddr.
uscsiresid If a data transfer terminates without
transferring the entire requested
amount, the remainder, or residue, is
returned in this field.
uscsicdblen The length of the SCSI CDB to be
transferred to the device in command
phase.
uscsirqlen The length of uscsirqbuf, the
application's Request Sense buffer.
uscsirqstatus The SCSI status byte returned for the
Request Sense command executed automati-
cally by the driver in response to a
Check Condition status return.
uscsirqresid The residue, or untransferred data
length, of the Request Sense data
transfer (the number of bytes, less than
SunOS 5.11 Last change: 29 May 2007 2
Ioctl Requests uscsi(7I)
or equal to uscsirqlen, which were not
filled with sense data).
uscsirqbuf Points to a buffer in application
address space to which the results of an
automatic Request Sense command are
written.
uscsireserved5 Reserved for future use.
The uscsiflags field defines the following:
USCSIWRITE /* send data to device */
USCSISILENT /* no error messages */
USCSIDIAGNOSE /* fail if any error occurs */
USCSISOLATE /* isolate from normal commands */
USCSIREAD /* get data from device */
USCSIASYNC /* set bus to asynchronous mode */
USCSISYNC /* return bus to sync mode if possible */
USCSIRESET /* reset target */
USCSIRESETARGET /* reset target */
USCSIRESETLUN /* reset logical unit */
USCSIRESETAL /* reset all targets */
USCSIRQENABLE /* enable request sense extensions */
USCSIRENEGOT /* renegotiate wide/sync on next I/O */
The uscsiflags bits have the following interpretation:
USCSIWRITE Data will be written from the initia-
tor to the target.
USCSISILENT The driver should not print any con-
sole error messages or warnings
regarding failures associated with
this SCSI command.
USCSIDIAGNOSE The driver should not attempt any
retries or other recovery mechanisms
if this SCSI command terminates abnor-
mally in any way.
USCSISOLATE This SCSI command should not be exe-
cuted with other commands.
SunOS 5.11 Last change: 29 May 2007 3
Ioctl Requests uscsi(7I)
USCSIREAD Data will be read from the target to
the initiator.
USCSIASYNC Set the SCSI bus to asynchronous mode
before running this command.
USCSISYNC Set the SCSI bus to synchronous mode
before running this command.
USCSIRESET Send a SCSI bus device reset message
to this target.
USCSIRESETARGET Same as USCSIRESET. Use this flag to
request TARGET RESET. (USCSIRESET is
maintained only for compatibility with
old applications).
USCSIRESETLUN Send a SCSI logical unit reset message
to this target.
USCSIRESETAL USCSIRESETAL,
USCSIRESET/USCSIRESETARGET and
USCSIRESETLUN are mutually exclusive
options and issuing them in any simul-
taneous combination will result in
implementation-dependent behavior
When a USCSI reset request is combined
with other SCSI commands, the follow-
ing semantics take effect:
If the USCSI RESET flag is specified,
the other fields (other than
uscsiflags) in the uscsicmd are
ignored. The uscsicdblen must be set
to zero.
USCSIRQENABLE Enable Request Sense extensions. If
the user application is prepared to
receive sense data, this bit must be
set, the fields uscsirqbuf and
uscsirqbuflen must be non-zero, and
the uscsirqbuf must point to memory
writable by the application.
SunOS 5.11 Last change: 29 May 2007 4
Ioctl Requests uscsi(7I)
USCSIRENEGOT Tells USCSI to renegotiate wide mode
and synchronous transfer speed before
the transmitted SCSI command is exe-
cuted. This flag in effects tells the
target driver to pass the
FLAGRENEGOTIATEWIDESYNC flag in the
SCSI packet before passing the command
to an adapter driver for transport.
See the scsipkt(9S) flag
FLAGRENEGOTIATEWIDESYNC for more
information.
IOCTLS
The ioctl supported by drivers providing the uscsi interface
is:
USCSICMD The argument is a pointer to a uscsicmd struc-
ture. The SCSI device addressed by that driver
is selected, and given the SCSI command
addressed by uscsicdb. If this command requires
a data phase, the uscsibuflen and uscsibufaddr
fields must be set appropriately; if data phase
occurs, the uscsiresid is returned as the
number of bytes not transferred. The status of
the command, as returned by the device, is
returned in the uscsistatus field. If the com-
mand terminates with Check Condition status, and
Request Sense is enabled, the sense data itself
is returned in uscsirqbuf. The uscsirqresid
provides the residue of the Request Sense data
transfer.
ERORS
EINVAL A parameter has an incorrect, or unsupported,
value.
EIO An error occurred during the execution of the com-
mand.
EPERM A process without root credentials tried to exe-
cute the USCSICMD ioctl.
EFAULT The uscsicmd itself, the uscsicdb, the
uscsibuf, or the uscsirqbuf point to an invalid
address.
SunOS 5.11 Last change: 29 May 2007 5
Ioctl Requests uscsi(7I)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWhea
Interface Stability Committed
SEE ALSO
ioctl(2), attributes(5), sd(7D), st(7D)
ANSI Small Computer System Interface-2 (SCSI-2)
WARNINGS
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 con-
fuse 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 USCSICMD ioctl associates a struct uscsicmd with a dev-
ice by using an open file descriptor to the device. Other
APIs might provide the same struct uscsicmd programming
interface, but perform device association in some other
manner.
SunOS 5.11 Last change: 29 May 2007 6
|
