The USCSICMD request, issued via
the ioctl(2)size="3" face="Arial"> call, passes a user-constructed SCSI
command block directly to a SCSI device. This feature enables the
user to utilize the full SCSI command set appropriate for a
particular device.

The following code fragment
demonstrates the use of USCSI. With a simple example of rewinding
a tape, we'll compare how this is accomplished with the standard
mtio(7)size="3" face="Arial"> and then with the USCSI size="3" face="Courier">ioctl commands. size="3" face="Courier">mtio(7) describes
the general magnetic tape interface supported by drivers for tape
devices (e.g. st(7)size="3" face="Arial">) and used by commands such as size="3" face="Courier">mt(1).Here's a
short routine using the mtio
ioctl:

#include
<sys/types.h>

#include
<sys/mtio.h>

int mt_rewind(fd)

int fd;

{

struct mtop
mtop;

mtop.mt_op =
(short) MTREW;

mtop.mt_op =
(short) MTREW;

mtop.mt_count =
1;

 

if (ioctl(fd,
MTIOCTOP, &mtop) == -1) {

printf("ERROR:
mt_rewind\n");

return(-1);>

}

return(0);

}

The two fields of the mtop
structure are set to the desired operation (face="Courier">MTREW) and a count of how
many to do (just 1). ioctl size="3" face="Arial">is called with the le descriptor for the
device, the MTIOCTOPsize="3" face="Arial"> (do a mag tape op) again, and a pointer to
the mtop structure. Within a SCSI driver, the command is
translated into a SCSI command which is issued to the device. The
USCSI ioctl size="3">lets the user pass his or her own SCSI rewind command to
the device. First, the command must be built. The size="3" face="Courier">uscsi_cmdface="Arial"> structure (scsi/impl/uscsi.h<
/font>size="3">) and command description block, face="Courier">scsi_cdb union
(scsi/general/comands.hsize="3">), are zeroed using memset(3c)nt>size="3">. The scc_cmdsize="3"> field in the command block is set to size="3" face="Courier">SCMD_REWINDface="Arial">.

The face="Courier">uscsi_cmd struct is pointed
at the command block and its size is entered in the size="3" face="Courier">uscsi_cdblen field.
uscsi_flagssize="3"> is set to USCSI_SILENTt
size="3"> to turn off error messages (for demonstration
purposes).

#include
<sys/scsi/scsi.h>

int uscsi_rewind(fd)

int fd;

{

struct uscsi_cmd
ucmd;

union scsi_cdb cdb;

int status;

(void) memset((char
*)&ucmd, 0, sizeof(ucmd));

(void) memset((char
*)&cdb, 0, sizeof(union scsi_cdb));

cdb.scc_cmd =
SCMD_REWIND;

ucmd.uscsi_cdb =
(caddr_t) &cdb;

ucmd.uscsi_cdblen =
CDB_GROUP0;

ucmd.uscsi_flags |=
USCSI_SILENT;

 

status = ioctl(fd,
USCSICMD, &ucmd);

 

if (status == 0
&& ucmd.uscsi_status == 0)

return (0);

else {

printf(ERROR:
uscsi_rewind\n);

return(-1);

}

}

Obviously, the USCSI version
requires more effort, but is much more flexible. Any appropriate
SCSI command can be built and issued (see the SCSI include files
in the /usr/include/sys/scsi). For our tape example, quite a
variety of commands are available. For test unit ready we would
simply set cdb.scc_cmd = SCMD_TEST_UNIT_READY in the above code.
Likewise for erase (SCMD_ERASE). A SCSI inquiry command (
scsi/general/inquiry.h) requires a buffer to receive information.
So, we add:

FORMG0COUNT(&cdb,
sizeof (buf));

ucmd.uscsi_bufaddr =
(caddr_t) buf;

ucmd.uscsi_buflen = sizeof
(buf);

which specifies the buffers size
and address. FORMG0COUNTsize="3" face="Arial"> is a macro (face="Courier">scsi/general/commands.h)
which sets the g0size="3"> count in the cdb structure. Mode sense (size="3" face="Courier">SCMD_MODE_SENSEface="Arial">) is implemented this way, too. Reads and writes (size="3" face="Courier">SCMD_READ/SCMD_WRITEface="Arial">) to the device are similar, but they also use the
tag (t_codesize="3" face="Arial">) field of the cdb structure. Quite a few
other tape specific commands can be issued including mode select,
mode sense, request sense, and write file mark

The flexibility of the USCSIsize="3" face="Courier"> ioctl allows
the device driver writer to fully exercise a SCSI device. The
feature is useful for rapid prototyping of algorithms for SCSI
devices and for diagnostic programs. The associated risks (system
panics, unusable devices, future obsolescence of the USCSI
feature) make the feature inappropriate for other uses. In
particular, users should be aware of the following:

Issuing a command to a device
simultaneously in use by a system driver may put that device in a
state such that the system driver may no longer work with that
device correctly (e.g., mode-selecting a disk to 1k sector size).

Third-party devices will not
necessarily respond correctly to any SCSI-2 command.

An arbitrary SCSI-2 command issued
to a device may cause that device to misbehave on the SCSI bus in
some fashion that may interfere with the correct operation of
other devices on the same bus in use by the system.

USCSI Man page.

Name

uscsi user SCSI command
interface

SYNOPSIS

#include
<sys/scsi/impl/uscsi.h>

ioctl(int fildes,int
request, struct uscsi_cmd *cmd);

DESCRIPTION

Drivers supporting this ioctl
provide a general interface allowing user-level applications
to cause individual SCSI commands to be directed to a
particular SCSI device under control of that driver. 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, and,
optionally, the sense data returned by the device if the
status returned is Check Condition.

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_tuscsi_cdb ; /*
cdb to send to target */

caddr_tuscsi_bufaddr;
/* i/o source/destination */

u_int uscsi_buflen ; /*
size of i/o to take place */

u_int uscsi_resid ; /*
resid from i/o operation */

u_char uscsi_cdblen; /*
# of valid cdb bytes */

u_char uscsi_rqlen; /*
size of uscsi_rqbuf */

u_char uscsi_rqstatus ;
/* status of request sense cmd */

u_char uscsi_rqresid;
/* resid of request sense cmd */

caddr_tuscsi_rqbuf; /*
request sense buffer */

void *uscsi_reserved_5;
/* Reserved for future use */

The fields of the size="3" face="Courier">uscsi_cmd face="Arial"> structure have the following meaning:

uscsi_flags size="3" face="Arial">This field defines the I/O
direction, if any, and other SCSI bus operations. The
possible values are described below.

uscsi_status size="3" face="Arial">The SCSI status byte returned by
the device is returned by the driver to the user
application here.

uscsi_timeout The driver
will fail the command if the command does not complete
with the specified timeout period, in seconds.

uscsi_cdb size="3" face="Arial">This field must point to the SCSI
cdb to be transferred to the device in command phase.

uscsi_bufaddr If a data
transfer is to occur, this field must point to the user
buffer to be transferred to the device, or to which the
data sent by the device is to be written.

uscsi_buflen size="3" face="Arial">If a data transfer is to occur,
this field should specify the maximum length of transfe
possible.

uscsi_resid size="3" face="Arial">If a data transfer occurs as part
of executing a uscsi size="3" face="Arial"> command, the driver returns the
residue of the transfer.

uscsi_cdblen size="3"> This field
must contain the length of the SCSI cdbt
size="3" face="Arial"> to be transferred to the device in
command phase.

uscsi_rqlen size="3" face="Arial">If the user application wishes to
receive any Request Sense data returned by the device in
the event of an error, this field should be set to the
length of the applications Request Sense buffer.

uscsi_rqstatus "Arial">If the user
application is prepared to receive Request Sense data,
and the driver executes a Request Sense command in
response to the user command terminating with Check
Condition, the driver will return the status of the
Request Sense command itself here.

uscsi_rqresid If the user
application is prepared to receive Request Sense data,
and the driver executes a Request Sense command in
response to the user command terminating with Check
Condition, the driver will return the residue of the
Request Sense data transfer here.

uscsi_rqbuf size="3" face="Arial">If the user application wishes to
receive any Request Sense data returned by the device in
the event of an error, this should point to a buffer in
the applica tions address space to which this data will
be written.

uscsi_reserved_5 size="3"> Not available

The face="Courier">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_ALL /*
reset all targets */

USCSI_RQENABLE /*
enable request sense extensions */

The uscsi_flags bits have the
following interpretation:

USCSI_WRITE ="Arial">If a
data transfer is to occur, the transfer is to occur
as a write from the initiator to the target.

USCSI_SILENT e="Arial">The
driver should not print any console error messages or
warnings regarding failures associated with this SCSI
command.

USCSI_DIAGNOSE ace="Arial">The
driver should not attempt any retries or other
recovery mechanisms, should this SCSI command
terminate abnormally in any way.

USCSI_ISOLATE size="3" face="Arial">This SCSI command should not be
executed with other commands.

USCSI_READ "Arial">If a
data transfer is to occur, the transfer is to occur
as a read from the target to the initiator.

USCSI_ASYNC size="3" face="Arial"> Set the SCSI bus to
asynchronous mode before running this command.

USCSI_SYNC "Arial">Set the
SCSI bus to synchronous mode before runing this
command.

USCSI_RESET ="Arial">Send a
SCSI Reset Message to this target.

USCSI_RESET_ALL size="3" face="Arial">Cause a SCSI Bus Reset on the
bus associated with this target.

USCSI_RQENABLE ace="Arial">Enable
Request Sense extensions. If the user application is
prepared to receive sense data, this bit must be set,
and the fields uscsit
size="3" face="Arial">_rqbuf and size="3" face="Courier">uscsi_rqbuflen
must be non-zero,
and the uscsi size="3" face="Arial">_rqbuf must point to memory
writable by the application.

ERRORS

EINVAL size="3" face="Arial">some parameter has an incorrect, or
unsupported, value.

EIO face="Arial"> an error occurred during the execution of
the command.

EFAULT size="3" face="Arial">the face="Courier">uscsi_cmd size="3" face="Arial">itself, the size="3" face="Courier">uscsi_cdb face="Arial">, the uscsi_buf,> size="3" face="Arial"> or the face="Courier">uscsi_rqbuf size="3" face="Arial">point to an invalid address.

IOCTLS

The ioctl supported by drivers
providing the uscsi interface is:

USCSICMD The argument is a
pointer to a uscsi_cmd size="3" face="Arial"> structure. The SCSI device addressed
by that driver is selected, and given the SCSI command
addressed by uscsi_cdb. If this command requires a data
phase, the uscsi_buflen size="3" face="Arial"> and face="Courier">uscsi_bufaddr f size="3" face="Arial">ields must be set appropriately; if
data phase occurs, the uscsi_residt> is returned as
the number of bytes not transferred. The status of the
command, as returned by the device, is returned in the size="3" face="Courier">uscsi_status face="Arial"> field. If the command terminates with Check
Condition status, and Request Sense is enabled, the sense
data itself is returned in face="Courier">usc-scsi_rqbuf. size="3" face="Arial">The size="3" face="Courier">uscsi_rqresid size="3" face="Arial">provides the residue of the Request
Sense data transfer.

SEE ALSO

sd(7),st(7),ioctl(2), size="3" face="Arial">ANSI Small Computer System Interface-2
(SCSI-2)