ds - User Mode SCSI driver for devices accessed using the
SGI linux-xscsi subsystem.
SYNOPSIS
/dev/xscsi/pci*/target*/lun*/ds - the generic 'ds' scsi
driver device
DESCRIPTION
The ds interface provides user-mode access to the SCSI
bus. It supports the programming interfaces described in
dslib(8) and below.
All of the ds devices support the same general interface.
The program calls open, gaining exclusive use of a speci
fied SCSI device (that is, two processes may not both have
the same device open at the same time via this driver).
Additionally, when the O_EXCL open flag set, exclusive use
of the target will be acquired. No other SCSI driver will
be able to use the target until it is closed. If some
other process has the target device open from another SCSI
driver, the open will fail with errno set to EBUSY. More
than one process may in fact have the same target open via
this driver, if one is a descendent of the other (via
sproc(2) or fork(2). In this case, it is the responsibil
ity of the program(s) to ensure that both processes do not
both attempt to do commands at the same time.
After opening, ioctl calls can be made. They will either
be performed directly or turned into SCSI transactions.
Finally, the close call releases the device for further
use.
The critical interface definitions (request structure and
codes, return codes, etc.) are defined in <xscsids.h>. In
particular, most SCSI transactions are performed using the
dsreq structure:
typedef struct dsreq { /* DEVSCSI ioctl structure */
/* devscsi prefix ........... */
uint ds_flags; /* see DSRQ_* flags below */
uint ds_time; /* timeout in milliseconds
(1 HZ used if zero) */
__psint_t ds_private; /* private use by caller */
/* SCSI request ............. */
caddr_t ds_cmdbuf; /* command buffer */
uchar_t ds_cmdlen; /* command buffer length */
caddr_t ds_databuf; /* data buffer start */
uint ds_datalen; /* total data length */
caddr_t ds_sensebuf; /* sense buffer */
uchar_t ds_senselen; /* sense buffer length */
dsiovec_t *ds_iovbuf; /* scatter-gather dma control */
ushort ds_iovlen; /* length of scatter-gather */
struct dsreq *ds_link; /* for linked requests */
ushort ds_synch; /* synchronous transfer control */
uchar_t ds_revcode; /* devscsi version code */
/* return portion ........... */
uchar_t ds_ret; /* devscsi return code */
uchar_t ds_status; /* status byte value */
uchar_t ds_msg; /* message byte value */
uchar_t ds_cmdsent; /* actual length command */
uint ds_datasent; /* actual length user data */
uchar_t ds_sensesent; /* actual length sense data */
} dsreq_t;
The first two parts of the structure (devscsi prefix, SCSI
request) must be filled in by the calling program. The
third part (scatter-gather, etc.) is largely optional, and
the last part (return portion) is used only for returned
information.
Normally, the ds_data* fields are used to control data
transmission. In this mode, all sent (received) data uses
a single I/O buffer. If desired, however, the ds_iov*
fields may be used (see DSRQ_IOV) to support a set of I/O
buffers. The number of scatter gather entries supported
is given by the V_MAX define, and is currently 1. The
scatter-gather structure, dsiovec_t, is defined as fol
lows:
typedef struct dsiovec { /* DEVSCSI scatter-gather control */
caddr_t iov_base; /* i/o base */
int iov_len; /* i/o length */
} dsiovec_t;
Different /dev/xscsi/pci*/target*/lun*/ds implementations
will support different subsets of the specification.
Items in the following tables are therefore marked to
indicate the likelihood of support:
! required (must be supported)
. normal (usually supported)
? unusual (seldom supported)
IOCTLS, ETC.
Several ioctls are supported by the /dev/xscsi/pci*/tar
get*/lun*/ds interface
DS_ENTER struct dsreq ! enter a request
DS_CANCEL struct dsreq ? cancel a request
DS_POLL struct dsreq ? sample a request
DS_RESET uint . obsolete
DS_SET uint ! set permanent flags
DS_CLEAR uint ! clear permanent flags
DS_GET uint ! get permanent flags
DS_CONF struct dsconf ! get configuration data
DS_ABORT uint . send abort message
The DS_ENTER ioctl is the basis for most interaction with
the driver. The user program prepares a request struc
ture, issues the ioctl, and examines the returned status
information.
Other ioctls help to fill out the interface, however. The
polled I/O ioctls (DS_CANCEL, DS_POLL, DS_CONTIN) are for
support asynchronous /dev/xscsi operations (not in the
SCSI sense, but in the I/O sense); these are not supported
under the SGI-Linux XSCSI subsystem. The DS_ABORT ioctl,
provides the ability to send an abort message; it is not
implemented for all host adapter types. The abort message
will be sent only when the target has no commands pending,
and is therefore useful only to abort immediate mode com
mands, or target specific functions.
The permanent flag ioctls (DS_SET, DS_GET, DS_CLEAR) allow
access to internal driver flag bits. These are undefined,
implementation specific, and should be avoided if portable
code is desired. The DS_GET ioctl returns bits whose def
initions begin with DSG_ (from xscsids.h) under the SGI-
Linux XSCSI subsystem. Not all of the low level host
adapter drivers support all (or even any) of these bits.
The DS_CONF ioctl, by contrast, allows a user program to
detect (and perhaps handle) implementation-specific con
figuration parameters:
typedef struct dsconf { /* DEVSCSI configuration structure */
uint dsc_flags; /* DSRQ flags honored by driver */
uint dsc_preset; /* DSRQ flag preset values */
u_char dsc_bus; /* # of this SCSI bus */
u_char dsc_imax; /* maximum # of ID's per bus on system */
u_char dsc_lmax; /* maximum # of LUN's per ID on system */
uint dsc_iomax; /* maximum length of an I/O on this system */
uint dsc_biomax /* maximum length of buffered I/O's */
} dsconf_t;
Most of the dsconf members ( dsc_bus, dsc_*max) have obvi
ous meanings. The dsc_iomax parameter is equivalent to
the kernel tunable parameter maxdmasz, except that
dsc_iomax is in bytes, rather than pages. The dsc_flags
together to indicate how the driver will interpret the
DSRQ_* flag bits.
These bits are ORed by the driver with the ds_flags word
in dsreq, request specific driver actions. The implemen
tation is then free to reject, honor, or ignore them.
Specifically, options will not be turned off, but may be
rejected via the DSRT_UNIMPL return code. Options may be
turned on without any notice whatsoever.
The dsc_flags member of dsconf indicates which flags the
implementation promises to honor. The dsc_preset word
indicates, for each flag not honored, the value defined by
the implementation. By appropriate logical operations, an
application may determine which DSRQ_* options are actu
ally available. The action in parentheses is taken when
the flag is not set.
Note that the DSRQ_SYNXFR and DSRQ_ASYNXFR flags should
not be used in all commands, only when strictly necessary,
as such negotiations are relatively expensive. Not all
host adapter drivers will honor these flags.
devscsi options:
DSRQ_ASYNC ? no (yes) sleep until request done
DSRQ_SENSE . yes (no) auto get sense on status
DSRQ_TARGET ? target (initiator) role
select options:
DSRQ_SELATN . select with (without) atn
DSRQ_DISC . identify disconnect (not) allowed
DSRQ_SYNXFR . attempt SCSI synchronous transfer negotiation
DSRQ_ASYNXFR . attempt SCSI asynchronous transfer negotiation
DSRQ_SELMSG . send supplied (generate) message
data transfer options:
DSRQ_IOV . scatter-gather (not) specified
DSRQ_READ ! input from SCSI bus
DSRQ_WRITE ! output toSCSI bus
DSRQ_BUF . buffered (direct) data transfer
progress/continuation callbacks:
DSRQ_CALL ? notify progress (completion-only)
DSRQ_ACKH ? (don't) hold ACK asserted
DSRQ_ATNH ? (don't) hold ATN asserted
DSRQ_ABORT ? abort msg until bus clear
host options (non-portable):
DSRQ_TRACE . trace (no) this request
DSRQ_CTRL1 . request with host control bit 1
DSRQ_CTRL2 . enable driver debug printfs during ioctl
(if program has superuser privileges)
additional flags:
DSRQ_MIXRDWR ? request can both read and write
RETURN CODES
The driver has a number of possible return codes, signify
ing failures on the part of the driver, the host SCSI
software, or the protocol. Some return codes may be
mapped to more generic return codes (DSRT_DEVSCSI,
DSRT_HOST, DSRT_PROTO). Note that the ds_status field
contains valid completion status only when the command
completed 'normally'. On timeouts and some other errors,
this field is set to 0xff on return to indicate that is
not valid. The ds_ret may be non-zero even if the command
completed successfully; i.e. on partial i/o completion,
and when a request sense has been done.
devscsi software returns:
DSRT_DEVSCSI ! general devscsi failure
DSRT_MULT ! request rejected
DSRT_CANCEL ! lower request cancelled
DSRT_REVCODE ! software obsolete, must recompile
DSRT_AGAIN ! try again, recoverable bus error
DSRT_UNIMPL ! unimplemented request option
host SCSI software returns:
DSRT_HOST ! general host failure
DSRT_NOSEL . no unit responded to select
DSRT_SHORT ! incomplete transfer (not an error)
DSRT_OK ! completetransfer (no error status)
DSRT_SENSE ! cmd w/ status, sense data gotten
DSRT_NOSENSE ! cmd w/ status, error getting sense
DSRT_TIMEOUT ! request idle longer than requested
DSRT_LONG ! target overran data bounds
protocol failures:
DSRT_PROTO ! misc. protocol failure
DSRT_EBSY . busy dropped unexpectedly
DSRT_REJECT . message reject
DSRT_PARITY . parity error on SCSI bus
DSRT_MEMORY . host memory error
DSRT_CMDO . error during command phase
DSRT_STAI . error during statusphase
SUPPORT CODE
A number of ancillary macros, functions, and data
necessary, these should facilitate the task of programming
SCSI control programs.
ADDITIONAL INFORMATION
Consult the SCSI standards documents, and the manuals for
the device you are working with for more information. The
"SCSI 1" specification document is called SCSI Specifica
tion, ANSI X3T9.2/86-109. Also of interest is the Common
Command Set specification document SCSI CCS Specification,
ANSI X3T9.2/85-3
NOTES
The ds programming interface contains a number of optional
features. The control program must therefore be able to
react properly, should a desired function be unavailable.
The peculiarities of any given SCSI device are the respon
sibility of the control program. The /dev/xscsi/pci*/tar
get*/lun*/ds interface merely allows communication to take
place.
Since the driver provides direct access to the SCSI bus,
the system administrator must be very careful in setting
up the permissions on the device files, lest security
holes occur.
No kernel read/write interface is provided, due to the
variety of forms these commands take in terms of both size
and field definitions.
No support currently exists for target mode or asyn
chronous (polled) I/O.
No checking is currently performed for potentially danger
ous actions (Copy, ID and code downloading, etc.).
NOTE
The device for each controller, id, lun trio is exclusive
open, in that once that combination is opened via this
interface or the 'normal' system interfaces, it may not be
opened again, until released by the other user. The nor
mal error returned in this case is EBUSY. The driver is
semaphored such that multiple copies of the file descrip
tor may be used, either by the same program, or its chil
dren via fork, etc.
FILES
/dev/xscsi/pci*/target*/lun*/ds - the generic 'ds' scsi driver device
SEE ALSO
dslib(8) for discussion of routines to simplify the use of
the driver.
xscsicontrol(8) for a program that uses this driver to
Man(1) output converted with
man2html