'\" te
.\" Copyright (c) 2007 by Sun Microsystems, Inc.  All rights reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH USCSI 7I "May 29, 2007"
.SH NAME
uscsi \- user SCSI command interface
.SH SYNOPSIS
.LP
.nf
#include <sys/scsi/impl/uscsi.h>

\fB\fR\fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIrequest\fR, \fBstruct uscsi_cmd *\fR\fIcmd\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBuscsi\fR command is very powerful and somewhat dangerous; therefore it
has some permission restrictions. See \fBWARNINGS\fR for more details.
.sp
.LP
Drivers supporting this \fBioctl\fR(2) provide a general interface allowing
user-level applications to cause individual \fBSCSI\fR commands to be directed
to a particular \fBSCSI\fR or \fBATAPI\fR device under control of that driver.
The \fBuscsi\fR command is supported by the \fBsd\fR driver for \fBSCSI\fR
disks and \fBATAPI\fR CD-ROM drives, and by the \fBst\fR driver for \fBSCSI\fR
tape drives. \fBuscsi\fR may also be supported by other device drivers; see the
specific device driver manual page for complete information.
.sp
.LP
Applications must not assume that all Solaris disk device drivers support the
\fBuscsi\fR ioctl command. The \fBSCSI\fR 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
\fBUSCSI_RQENABLE\fR flag below for this Request Sense processing. The
\fBuscsi_cmd\fR structure is defined in \fB<sys/scsi/impl/uscsi.h>\fR and
includes the following members:
.sp
.in +2
.nf
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 */
.fi
.in -2

.sp
.LP
The fields of the \fBuscsi_cmd\fR structure have the following meanings:
.sp
.ne 2
.na
\fB\fBuscsi_flags\fR\fR
.ad
.RS 20n
The \fBI/O\fR direction and other details of how to carry out the \fBSCSI\fR
command. Possible values are described below.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_status\fR\fR
.ad
.RS 20n
The \fBSCSI\fR status byte returned by the device is returned in this field.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_timeout\fR\fR
.ad
.RS 20n
Time in seconds to allow for completion of the command.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_cdb\fR\fR
.ad
.RS 20n
A pointer to the \fBSCSI\fR CDB (command descriptor block) to be transferred to
the device in command phase.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_bufaddr\fR\fR
.ad
.RS 20n
The user buffer containing the data to be read from or written to the device.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_buflen\fR\fR
.ad
.RS 20n
The length of \fBuscsi_bufaddr\fR.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_resid\fR\fR
.ad
.RS 20n
If a data transfer terminates without transferring the entire requested amount,
the remainder, or residue, is returned in this field.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_cdblen\fR\fR
.ad
.RS 20n
The length of the \fBSCSI\fR CDB to be transferred to the device in command
phase.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_rqlen\fR\fR
.ad
.RS 20n
The length of \fBuscsi_rqbuf\fR, the application's Request Sense buffer.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_rqstatus\fR\fR
.ad
.RS 20n
The \fBSCSI\fR status byte returned for the Request Sense command executed
automatically by the driver in response to a Check Condition status return.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_rqresid\fR\fR
.ad
.RS 20n
The residue, or untransferred data length, of the Request Sense data transfer
(the number of bytes, less than or equal to \fBuscsi_rqlen\fR, which were not
filled with sense data).
.RE

.sp
.ne 2
.na
\fB\fBuscsi_rqbuf\fR\fR
.ad
.RS 20n
Points to a buffer in application address space to which the results of an
automatic Request Sense command are written.
.RE

.sp
.ne 2
.na
\fB\fBuscsi_reserved_5\fR\fR
.ad
.RS 20n
Reserved for future use.
.RE

.sp
.LP
The \fBuscsi_flags\fR field defines the following:
.sp
.in +2
.nf
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 */
.fi
.in -2

.sp
.LP
The \fBuscsi_flags\fR bits have the following interpretation:
.sp
.ne 2
.na
\fB\fBUSCSI_WRITE\fR\fR
.ad
.RS 22n
Data will be written from the initiator to the target.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_SILENT\fR\fR
.ad
.RS 22n
The driver should not print any console error messages or warnings regarding
failures associated with this \fBSCSI\fR command.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_DIAGNOSE\fR\fR
.ad
.RS 22n
The driver should not attempt any retries or other recovery mechanisms if this
\fBSCSI\fR command terminates abnormally in any way.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_ISOLATE\fR\fR
.ad
.RS 22n
This \fBSCSI\fR command should not be executed with other commands.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_READ\fR\fR
.ad
.RS 22n
Data will be read from the target to the initiator.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_ASYNC\fR\fR
.ad
.RS 22n
Set the \fBSCSI\fR bus to asynchronous mode before running this command.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_SYNC\fR\fR
.ad
.RS 22n
Set the \fBSCSI\fR bus to synchronous mode before running this command.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_RESET\fR\fR
.ad
.RS 22n
Send a \fBSCSI\fR bus device reset message to this target.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_RESET_TARGET\fR\fR
.ad
.RS 22n
Same as USCSI_RESET. Use this flag to request TARGET RESET. (USCSI_RESET is
maintained only for compatibility with old applications).
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_RESET_LUN\fR\fR
.ad
.RS 22n
Send a \fBSCSI\fR logical unit reset message to this target.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_RESET_ALL\fR\fR
.ad
.RS 22n
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
.sp
When a USCSI reset request is combined with other \fBSCSI\fR commands, the
following semantics take effect:
.sp
If the USCSI RESET flag is specified, the other fields (other than uscsi_flags)
in the uscsi_cmd are ignored. The uscsi_cdblen \fBmust\fR be set to zero.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_RQENABLE\fR\fR
.ad
.RS 22n
Enable Request Sense extensions. If the user application is prepared to receive
sense data, this bit must be set, the fields \fBuscsi_rqbuf\fR and
\fBuscsi_rqbuflen\fR must be non-zero, and the \fBuscsi_rqbuf\fR must point to
memory writable by the application.
.RE

.sp
.ne 2
.na
\fB\fBUSCSI_RENEGOT\fR\fR
.ad
.RS 22n
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 \fBFLAG_RENEGOTIATE_WIDE_SYNC\fR flag in the SCSI packet
before passing the command to an adapter driver for transport.
.sp
See the \fBscsi_pkt\fR(9S) flag \fBFLAG_RENEGOTIATE_WIDE_SYNC\fR for more
information.
.RE

.SH IOCTLS
.sp
.LP
The \fBioctl\fR supported by drivers providing the \fBuscsi\fR interface is:
.sp
.ne 2
.na
\fB\fBUSCSICMD\fR\fR
.ad
.RS 12n
The argument is a pointer to a \fBuscsi_cmd\fR structure. The \fBSCSI\fR device
addressed by that driver is selected, and given the \fBSCSI\fR command
addressed by \fBuscsi_cdb\fR. If this command requires a data phase, the
\fBuscsi_buflen\fR and \fBuscsi_bufaddr\fR fields must be set appropriately; if
data phase occurs, the \fBuscsi_resid\fR is returned as the number of bytes not
transferred. The status of the command, as returned by the device, is returned
in the \fBuscsi_status\fR field. If the command terminates with Check Condition
status, and Request Sense is enabled, the sense data itself is returned in
\fBuscsi_rqbuf\fR. The \fBuscsi_rqresid\fR provides the residue of the Request
Sense data transfer.
.RE

.SH ERRORS
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
A parameter has an incorrect, or unsupported, value.
.RE

.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 10n
An error occurred during the execution of the command.
.RE

.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 10n
A process without root credentials tried to execute the \fBUSCSICMD\fR ioctl.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
The \fBuscsi_cmd\fR itself, the \fBuscsi_cdb\fR, the \fBuscsi_buf\fR, or the
\fBuscsi_rqbuf\fR point to an invalid address.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability 	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBioctl\fR(2), \fBattributes\fR(5), \fBsd\fR(7D), \fBst\fR(7D)
.sp
.LP
\fIANSI Small Computer System Interface-2 (SCSI-2)\fR
.SH WARNINGS
.sp
.LP
The \fBuscsi\fR 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 \fBuscsi\fR commands can change the state of the device and
confuse the device driver. It is best to use \fBuscsi\fR 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.
.sp
.LP
The \fBuscsi\fR 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.
.sp
.LP
The \fBUSCSICMD\fR ioctl associates a \fBstruct uscsi_cmd\fR with a device by
using an open file descriptor to the device. Other APIs might provide the same
\fBstruct uscsi_cmd\fR programming interface, but perform device association in
some other manner.