scsi2lib.c

VxWorks操作系统内核源代码

/* scsi2Lib.c - Small Computer System Interface (SCSI) library (SCSI-2) */

/* Copyright 1989-2002 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
04l,07mar02,pmr  SPR 73383: no division-by-zero in scsiTargetOptionsShow().
04k,16oct01,pmr  SPR 67310: turning off message-using options when messaging
                 is turned off in scsiTargetOptionsSet().
04j,08oct01,rcs  tested for removable and medium not present in 
                 scsiPhysDevCreate() SPR# 32203
04i,05oct01,rcs  added display of ASCQ (Additional Sense Code Qualifier) to 
                 scsi2Transact() SCSI_DEBUG_MSGs. SPR# 29269  
04h,03oct01,rcs  clarified description of xferWidth in scsiTargetOptionsSet()
                 SPR# 69003 
04g,26sep01,rcs  fixed scsi2PhysDevCreate() to use user specified `numBlocks' 
                 or `blockSize' SPR# 22635
04f,26sep01,rcs  fixed scsiTargetOptionsSet() to allow for narrow width
                 to be explicitly set for a narrow target. SPR# 28262 
04e,25sep01,rcs  added routine scsiTargetOptionsShow() SPR# 69223
04d,24sep01,rcs  set errno for MEDIUM ERROR, HARDWARE ERROR, ILLEGAL REQUEST, 
                 BLANK CHECK, ABORTED COMMAND, and VOLUME OVERFLOW in switch
                 statement in scsi2Transact(). SPR# 21236 
04c,05oct98,jmp  doc: cleanup.
04b,28aug97,dds  SPR 3425: "scsiFormatUnit" command, times out for disks which 
                 take a long time to format.
04a,14aug97,dds  Rework of SPR 8219.
03z,28jul97,dds  SPR 8219: switching from synch to async mode cause target
                 to hang.
03y,24jul97,dds  SPR 8323 / 7838: scsiTargetOptionsGet returns "xferWidth"
03x,10jul97,dds  added library support for adaptec chips.
03w,09jul97,dgp  doc: correct fonts per SPR 7853
03v,28mar97,dds  SPR 8220: added check for parity errors.
03u,28oct96,dgp  doc: editing for newly published SCSI libraries
03t,21oct96,dds  removed NOMANUAL for functions called from the 
                 driver interface.
03s,14sep96,dds  removed the scsiMgr and scsiCtrl functions. These 
                 functions are found in scsiMgrLib.c and scsiCtrlLib.c
03r,30jul96,jds  fixed scsiCacheSynchronize() to act on cache lines only
03q,29jul96,jds  added support for hardware snooping 
03p,06may96,jds  more doc tweaks
03o,01may96,jds  doc tweaks
03n,22apr96,jds  doc tweaks to describe WIDE transfers
03m,20apr96,jds  added WIDE data transfer support
03l,25jan96,jds  added scsiCtrl routine modifications based on SPARC/5390
03k,13nov95,jds  minor document changes
03j,08nov95,jds  more doc cleanup
03i,20sep95,jdi  doc cleanup.
03h,30aug95,jds  bug fixes and cleanup. Bugs include several instances where
		 function was returning with semaphore taken.
03g,26jul95,jds  added scsiReadBlockLimits in scsiPhysDevCreate for SEQ devs
03f,25jul95,jds  added support in scsiTransact for sequential devices. Created
                 chkMedChangeAndWP (). Made appropriate changes in other
		 routines as well.e.g scsiPhysDevCreate ()
03e,19jul95,jds  removed all SCSI direct access commands and put them in 
                 scsiDirectLib, also moved blkDev routines.
03d,21mar95,ihw  minor bug fixes in "scsiCtrl*()" routines
03c,07oct94,ihw  errno now set if sense data is unrecognised
		 error message logged if max number of threads is reached
03b,27may94,ihw  documented prior to release
03a,30mar94,ihw  modified for enhanced SCSI library: tagged command queueing
                    major architectural changes ...
                 ABORT rather than REJECT used to reject invalid reselection
		 removed redundant code for additional length in data in xfer
		 fixed incorrect handling of ext msg in with zero length byte
02b,25feb94,ihw  fixed synchronous transfer message-in diagnostics
02a,14jan94,ihw  modified for enhanced SCSI library: multiple initiators,
    	    	    disconnect/reconnect and synchronous transfer supported
		 "scsiSyncXferNegotiate()" made non-local for NCR driver
01w,27nov92,jdi  documentation cleanup, including SPR 1415.
01v,15sep92,ccc  reworked select timeout, fixed extended message to work
		 with new drive, documentation changes.
01u,10aug92,ccc  added timeouts to scsiXaction for each scsi command.
01t,28jul92,rrr  fixed decl of scsiSyncTarget
01s,22jul92,gae  added correct number of parameters to logMsg().
01r,20jul92,eve  Remove conditional INCLUDE_SYNC_SCSI compilation.
01q,18jul92,smb  Changed errno.h to errnoLib.h.
01p,13jul92,eve  added init of the current pScsiXaction in scsiPhaseSequence().
01o,08jul92,eve  supplies a reqSense buffer if there is no user buffer 
		 in scsiTransact routine.
01n,03jul92,eve  added new sync feature with NOMANUAL
01m,26may92,rrr  the tree shuffle
01l,16dec91,gae  added includes for ANSI; added parameters to logMsg() calls.
01k,19nov91,rrr  shut up some ansi warnings.
01j,04oct91,rrr  passed through the ansification filter
                  -changed functions to ansi style
		  -changed READ, WRITE and UPDATE to O_RDONLY O_WRONLY and ...
		  -changed VOID to void
		  -changed copyright notice
01i,13mar91,jcc  misc. clean-up and enhancements.
01h,25oct90,jcc  lint.
01g,18oct90,jcc  removed call to printErrno() in scsiAutoConfig().
01f,02oct90,jcc  UTINY became UINT8; added scsiAutoConfig(), scsiPhysDevIdGet(),
		 and scsiIoctl() option FIODISKFORMAT;
		 changed all malloc()'s to calloc()'s in xxCreate() routines;
		 made changes associated with SEM_ID's becoming SEMAPHORE's
		 in created structures;
		 enhanced scsiPhysDevCreate() to determine amount and type
		 of REQUEST SENSE data returned by the device; miscellaneous.
01e,10aug90,dnw  fixed warnings caused by changing scsiBusReset to VOIDFUNCPTR.
01d,18jul90,jcc  made semTake() calls 5.0 compatible; clean-up.
01c,08jun90,jcc  modified incoming message handling; generalized scsiTransact
		 calls to a procedure variable to allow off-board SCSI
		 controller drivers; documentation.
01b,23mar90,jcc  lint.
01a,05may89,jcc  written.
*/

/*
DESCRIPTION
This library implements the Small Computer System Interface (SCSI)
protocol in a controller-independent manner.  It implements only the SCSI
initiator function as defined in the SCSI-2 ANSI specification. This library 
does not support a VxWorks target acting as a SCSI target.

The implementation is transaction based.  A transaction is defined as the
selection of a SCSI device by the initiator, the issuance of a SCSI command,
and the sequence of data, status, and message phases necessary to perform
the command.  A transaction normally completes with a "Command Complete"
message from the target, followed by disconnection from the SCSI bus.  If
the status from the target is "Check Condition," the transaction
continues; the initiator issues a "Request Sense" command to gain more
information on the exception condition reported.

Many of the subroutines in scsi2Lib facilitate the transaction of
frequently used SCSI commands.  Individual command fields are passed as
arguments from which SCSI Command Descriptor Blocks are constructed, and
fields of a SCSI_TRANSACTION structure are filled in appropriately.  This
structure, along with the SCSI_PHYS_DEV structure associated with the
target SCSI device, is passed to the routine whose address is indicated by
the 'scsiTransact' field of the SCSI_CTRL structure associated with the
relevant SCSI controller. The above mentioned structures are defined in 
scsi2Lib.h.

The function variable 'scsiTransact' is set by the individual SCSI
controller driver.  For off-board SCSI controllers, this
routine rearranges the fields of the SCSI_TRANSACTION structure into
the appropriate structure for the specified hardware, which then carries out
the transaction through firmware control.  Drivers for an on-board
SCSI-controller chip can use the scsiTransact() routine in scsiLib (which
invokes the scsi2Transact() routine in scsi2Lib), as long as they provide the 
other functions specified in the SCSI_CTRL structure.

SCSI TRANSACTION TIMEOUT
Associated with each transaction is a time limit (specified in microseconds,
but measured with the resolution of the system clock).  If the transaction
has not completed within this time limit, the SCSI library aborts it; the
called routine fails with a corresponding error code.  The timeout period
includes time spent waiting for the target device to become free to accept
the command.

The semantics of the timeout should guarantee that the caller waits no 
longer than the transaction timeout period, but in practice this
may depend on the state of the SCSI bus and the connected target device when
the timeout occurs.  If the target behaves correctly according to the SCSI
specification, proper timeout behavior results.  However, in certain
unusual cases--for example, when the target does not respond to an asserted 
ATN signal--the caller may remain blocked for longer than the timeout period.

If the transaction timeout causes problems in your system, you can set the
value of either or both the global variables "scsi{Min,Max}Timeout".  These
specify (in microseconds) the global minimum and maximum timeout periods,
which override (clip) the value specified for a transaction.  They may be
changed at any time and affect all transactions issued after the new
values are set.  The range of both these variable is 0 to 0xffffffff (zero to
about 4295 seconds).

SCSI TRANSACTION PRIORITY
Each transaction also has an associated priority used by the SCSI
library when selecting the next command to issue when the SCSI system is
idle.  It chooses the highest priority transaction that can be dispatched
on an available physical device.  If there are several equal-priority
transactions available, the SCSI library uses a simple round-robin
scheme to avoid favoring the same physical device.

Priorities range from 0 (highest) to 255 (lowest), which is the same as task
priorities.  The priority SCSI_THREAD_TASK_PRIORITY can be used to give the
transaction the same priority as the calling task (this is the method used
internally by this SCSI-2 library).

SUPPORTED SCSI DEVICES
This library requires peripherals that conform to the SCSI-2 ANSI
standard; in particular, the INQUIRY, REQUEST SENSE, and
TEST UNIT READY commands must be supported as specified by this standard.
In general, the SCSI library is self-configuring to work with any device
that meets these requirements.

Peripherals that support identification and the SCSI message protocol are
strongly recommended as these provide maximum performance.

In theory, all classes of SCSI devices are supported.  The scsiLib library
provides the capability to transact any SCSI command on any SCSI device
through the FIOSCSICOMMAND function of the scsiIoctl() routine (which 
invokes the scsi2Ioctl() routine in scsi2Lib).

Only direct-access devices (disks) are supported by file systems like dosFs, 
rt11Fs and rawFs. These file systems employ routines in 
scsiDirectLib (most of which are described in scsiLib but defined in 
scsiDirectLib). In the case of sequential-access devices (tapes), higher-level
tape file systems, like tapeFs,  make use of scsiSeqLib. For other types of 
devices, additional, higher-level software is necessary to map user-level
commands to SCSI transactions.

DISCONNECT/RECONNECT SUPPORT
The target device can be disconnected from the SCSI bus while it carries
out a SCSI command; in this way, commands to multiple SCSI devices can
be overlapped to improve overall SCSI throughput.  There are no
restrictions on the number of pending, disconnected commands or the
order in which they are resumed.  The SCSI library serializes access to the
device according to the capabilities and status of the device (see the
following section).

Use of the disconnect/reconnect mechanism is invisible to users of the SCSI
library. It can be enabled and disabled separately for each target device
(see scsiTargetOptionsSet()).  Note that support for disconnect/reconnect
depends on the capabilities of the controller and its driver (see below).

TAGGED COMMAND QUEUEING SUPPORT
If the target device conforms to the ANSI SCSI-2 standard and indicates
(using the INQUIRY command) that it supports command queuing, the SCSI
library allows new commands to be started on the device whenever the SCSI
bus is idle.  That is, it executes multiple commands concurrently on the
target device.  By default, commands are tagged with a SIMPLE QUEUE TAG
message.  Up to 256 commands can be executing concurrently.

The SCSI library correctly handles contingent allegiance conditions that
arise while a device is executing tagged commands.  (A contingent
allegiance condition exists when a target device is maintaining sense data that
the initiator should use to correctly recover from an error condition.)  It
issues an untagged REQUEST SENSE command, and stops issuing tagged commands
until the sense recovery command has completed.

For devices that do not support command queuing, the SCSI library only
issues a new command when the previous one has completed.  These devices
can only execute a single command at once.

Use of tagged command queuing is normally invisible to users of the SCSI
library.  If necessary, the default tag type and maximum number of tags may
be changed on a per-target basis, using scsiTargetOptionsSet().

SYNCHRONOUS TRANSFER PROTOCOL SUPPORT
If the SCSI controller hardware supports the synchronous transfer
protocol, scsiLib negotiates with the target device to determine
whether to use synchronous or asynchronous transfers.  Either VxWorks
or the target device may start a round of negotiation.  Depending on the
controller hardware, synchronous transfer rates up to the maximum allowed
by the SCSI-2 standard (10 Mtransfers/second) can be used.

Again, this is normally invisible to users of the SCSI library, but
synchronous transfer parameters may be set or disabled on a per-target basis
by using scsiTargetOptionsSet().

WIDE DATA TRANSFER SUPPORT
If the SCSI controller supports the wide data transfer protocol, scsiLib
negotiates wide data transfer parameters with the target device, if
that device also supports wide transfers. Either VxWorks or the target device
may start a round of negotiation. Wide data transfer parameters are 
negotiated prior to the synchronous data transfer parameters, as 
specified by the SCSI-2 ANSI specification. In conjunction with
synchronous transfer, up to a maximum of 20MB/sec. can be attained.

Wide data transfer negotiation is invisible to users of this library,
but it is possible to enable or disable wide data transfers and the
parameters on a per-target basis by using scsiTargetOptionsSet().

SCSI BUS RESET
The SCSI library implements the ANSI "hard reset" option.  Any transactions
in progress when a SCSI bus reset is detected fail with an error code
indicating termination due to bus reset.  Any transactions waiting to start
executing are then started normally.

CONFIGURING SCSI CONTROLLERS
The routines to create and initialize a specific SCSI controller are
particular to the controller and normally are found in its library
module.  The normal calling sequence is:
.ne 4
.CS
    xxCtrlCreate (...);	/@ parameters are controller specific @/
    xxCtrlInit (...);	/@ parameters are controller specific @/
.CE
The conceptual difference between the two routines is that xxCtrlCreate()
calloc's memory for the xx_SCSI_CTRL data structure and initializes
information that is never expected to change (for example, clock rate).  The
remaining fields in the xx_SCSI_CTRL structure are initialized by
xxCtrlInit() and any necessary registers are written on the SCSI
controller to effect the desired initialization.  This routine can be
called multiple times, although this is rarely required.  For example, the
bus ID of the SCSI controller can be changed without rebooting the VxWorks
system.

CONFIGURING PHYSICAL SCSI DEVICES
Before a device can be used, it must be "created," that is, declared.
This is done with scsiPhysDevCreate() and can only be done after a
SCSI_CTRL structure exists and has been properly initialized.

.CS
SCSI_PHYS_DEV *scsiPhysDevCreate
    (
    SCSI_CTRL * pScsiCtrl,/@ ptr to SCSI controller info @/
    int  devBusId,	  /@ device's SCSI bus ID @/
    int  devLUN,	  /@ device's logical unit number @/
    int  reqSenseLength,  /@ length of REQUEST SENSE data dev returns @/
    int  devType,	  /@ type of SCSI device @/
    BOOL removable,	  /@ whether medium is removable @/
    int  numBlocks,	  /@ number of blocks on device @/
    int  blockSize	  /@ size of a block in bytes @/
    )
.CE

Several of these parameters can be left unspecified, as follows:
.iP <reqSenseLength>
If 0, issue a REQUEST_SENSE to determine a request sense length.
.iP <devType>
This parameter is ignored: an INQUIRY command is used to ascertain the
device type.  A value of NONE (-1) is the recommended placeholder.
.iP "<numBlocks>, <blockSize>"
If 0, issue a READ_CAPACITY to determine the number of blocks.
.LP

The above values are recommended, unless the device does not support the
required commands, or other non-standard conditions prevail.

LOGICAL PARTITIONS ON DIRECT-ACCESS BLOCK DEVICES
It is possible to have more than one logical partition on a SCSI block
device.  This capability is currently not supported for removable media
devices.  A partition is an array of contiguously addressed blocks
with a specified starting block address and specified number of blocks.
The scsiBlkDevCreate() routine is called once for each block device
partition.  Under normal usage, logical partitions should not overlap.
.ne 8
.CS
SCSI_BLK_DEV *scsiBlkDevCreate
    (
    SCSI_PHYS_DEV *  pScsiPhysDev,  /@ ptr to SCSI physical device info @/
    int              numBlocks,	    /@ number of blocks in block device @/
    int              blockOffset    /@ address of first block in volume @/
    )
.CE

Note that if <numBlocks> is 0, the rest of the device is used.

ATTACHING DISK FILE SYSTEMS TO LOGICAL PARTITIONS
Files cannot be read or written to a disk partition until a file system (for
example, dosFs, rt11Fs, or rawFs) has been initialized on the partition.
For more information, see the relevant documentation in dosFsLib,
rt11FsLib, or rawFsLib.

USING A SEQUENTIAL-ACCESS BLOCK DEVICE
The entire volume (tape) on a sequential-access block device is treated as 
a single raw file. This raw file is made available to higher-level layers
like tapeFs by the scsiSeqDevCreate() routine, described in scsiSeqLib. The
scsiSeqDevCreate() routine is called once for a given SCSI physical 
device.
.CS
SEQ_DEV *scsiSeqDevCreate
    (
    SCSI_PHYS_DEV *pScsiPhysDev  /@ ptr to SCSI physical device info @/
    )
.CE

TRANSMITTING ARBITRARY COMMANDS TO SCSI DEVICES
The scsi2Lib, scsiCommonLib, scsiDirectLib, and scsiSeqLib libraries 
collectively provide routines that implement all mandatory SCSI-2 
direct-access and sequential-access commands. Still, there are situations that
require commands that are not supported by these libraries (for example, 
writing software that needs to use an optional SCSI-2 command).
Arbitrary commands are handled with the FIOSCSICOMMAND option to
scsiIoctl().  The <arg> parameter for FIOSCSICOMMAND is a pointer to a
valid SCSI_TRANSACTION structure.  Typically, a call to scsiIoctl() is written
as a subroutine of the form:
.CS