VxWorks Reference Manual : Libraries
scsi2Lib - Small Computer System Interface (SCSI) library (SCSI-2)
scsi2IfInit( ) - initialize the SCSI-2 interface to scsiLib
scsiTargetOptionsSet( ) - set options for one or all SCSI targets
scsiTargetOptionsGet( ) - get options for one or all SCSI targets
scsiPhysDevShow( ) - show status information for a physical device
scsiCacheSynchronize( ) - synchronize the caches for data coherency
scsiIdentMsgBuild( ) - build an identification message
scsiIdentMsgParse( ) - parse an identification message
scsiMsgOutComplete( ) - perform post-processing after a SCSI message is sent
scsiMsgOutReject( ) - perform post-processing when an outgoing message is rejected
scsiMsgInComplete( ) - handle a complete SCSI message received from the target
scsiSyncXferNegotiate( ) - initiate or continue negotiating transfer parameters
scsiWideXferNegotiate( ) - initiate or continue negotiating wide parameters
scsiThreadInit( ) - perform generic SCSI thread initialization
scsiCacheSnoopEnable( ) - inform SCSI that hardware snooping of caches is enabled
scsiCacheSnoopDisable( ) - inform SCSI that hardware snooping of caches is disabled
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.
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).
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).
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).
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( ).
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( ).
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( ).
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.
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:
xxCtrlCreate (...); /* parameters are controller specific */ xxCtrlInit (...); /* parameters are controller specific */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.
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.
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 */ )Several of these parameters can be left unspecified, as follows:
- reqSenseLength
- If 0, issue a REQUEST_SENSE to determine a request sense length.
- devType
- This parameter is ignored: an INQUIRY command is used to ascertain the device type. A value of NONE (-1) is the recommended placeholder.
- numBlocks, blockSize
- If 0, issue a READ_CAPACITY to determine the number of blocks.
The above values are recommended, unless the device does not support the required commands, or other non-standard conditions prevail.
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.
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 */ )Note that if numBlocks is 0, the rest of the device is used.
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.
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.
SEQ_DEV *scsiSeqDevCreate ( SCSI_PHYS_DEV *pScsiPhysDev /* ptr to SCSI physical device info */ )
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:
STATUS myScsiCommand ( SCSI_PHYS_DEV * pScsiPhysDev, /* ptr to SCSI physical device */ char * buffer, /* ptr to data buffer */ int bufLength, /* length of buffer in bytes */ int someParam /* param. specifiable in cmd block */ ) { SCSI_COMMAND myScsiCmdBlock; /* SCSI command byte array */ SCSI_TRANSACTION myScsiXaction; /* info on a SCSI transaction */ /* fill in fields of SCSI_COMMAND structure */ myScsiCmdBlock [0] = MY_COMMAND_OPCODE; /* the required opcode */ . myScsiCmdBlock [X] = (UINT8) someParam; /* for example */ . myScsiCmdBlock [N-1] = MY_CONTROL_BYTE; /* typically == 0 */ /* fill in fields of SCSI_TRANSACTION structure */ myScsiXaction.cmdAddress = myScsiCmdBlock; myScsiXaction.cmdLength = <# of valid bytes in myScsiCmdBlock>; myScsiXaction.dataAddress = (UINT8 *) buffer; myScsiXaction.dataDirection = <O_RDONLY (0) or O_WRONLY (1)>; myScsiXaction.dataLength = bufLength; myScsiXaction.addLengthByte = 0; /* no longer used */ myScsiXaction.cmdTimeout = <timeout in usec>; myScsiXaction.tagType = SCSI_TAG_{DEFAULT,UNTAGGED, SIMPLE,ORDERED,HEAD_OF_Q}; myScsiXaction.priority = [ 0 (highest) to 255 (lowest) ]; if (scsiIoctl (pScsiPhysDev, FIOSCSICOMMAND, &myScsiXaction) == OK) return (OK); else /* optionally perform retry or other action based on value of * myScsiXaction.statusByte */ return (ERROR); }
scsiLib.h, scsi2Lib.h
scsi2Lib, dosFsLib, rt11FsLib, rawFsLib, tapeFsLib, scsiLib, scsiCommonLib, scsiDirectLib, scsiSeqLib, scsiMgrLib, scsiCtrlLib, < >American National Standard for Information Systems - Small Computer" < >System Interface (SCSI-2), ANSI X3T9, " VxWorks Programmer's Guide: I/O System, Local File Systems
scsi2IfInit( ) - initialize the SCSI-2 interface to scsiLib
void scsi2IfInit ()
This routine initializes the SCSI-2 function interface by adding all the routines in scsi2Lib plus those in scsiDirectLib and scsiCommonLib. It is invoked by usrConfig.c if the macro INCLUDE_SCSI2 is defined in config.h. The calling interface remains the same between SCSI-1 and SCSI-2; this routine simply sets the calling interface function pointers to the SCSI-2 functions.
N/A
scsiTargetOptionsSet( ) - set options for one or all SCSI targets
STATUS scsiTargetOptionsSet ( SCSI_CTRL * pScsiCtrl, /* ptr to SCSI controller info */ int devBusId, /* target to affect, or all */ SCSI_OPTIONS * pOptions, /* buffer containing new options */ UINT which /* which options to change */ )
This routine sets the options defined by the bitmask which for the specified target (or all targets if devBusId is SCSI_SET_OPT_ALL_TARGETS).
The bitmask which can be any combination of the following, bitwise OR'd together (corresponding fields in the SCSI_OPTIONS structure are shown in parentheses):
SCSI_SET_OPT_TIMEOUT selTimeOut select timeout period, microseconds SCSI_SET_OPT_MESSAGES messages FALSE to disable SCSI messages SCSI_SET_OPT_DISCONNECT disconnect FALSE to disable discon/recon SCSI_SET_OPT_XFER_PARAMS maxOffset, max sync xfer offset, 0=>async minPeriod min sync xfer period, x 4 nsec. SCSI_SET_OPT_TAG_PARAMS tagType, default tag type (SCSI_TAG_*) maxTags max cmd tags available SCSI_SET_OPT_WIDE_PARAMS xferWidth data transfer width in bits
This routine can be used after the target device has already been used; in this case, however, it is not possible to change the tag parameters. This routine must not be used while there is any SCSI activity on the specified target(s).
OK, or ERROR if the bus ID or options are invalid.
scsiTargetOptionsGet( ) - get options for one or all SCSI targets
STATUS scsiTargetOptionsGet ( SCSI_CTRL * pScsiCtrl, /* ptr to SCSI controller info */ int devBusId, /* target to interrogate */ SCSI_OPTIONS * pOptions /* buffer to return options */ )
This routine copies the current options for the specified target into the caller's buffer.
OK, or ERROR if the bus ID is invalid.
scsiPhysDevShow( ) - show status information for a physical device
void scsiPhysDevShow ( SCSI_PHYS_DEV * pScsiPhysDev, /* physical device to be displayed */ BOOL showThreads, /* show IDs of associated threads */ BOOL noHeader /* do not print title line */ )
This routine shows the state, the current nexus type, the current tag number, the number of tagged commands in progress, and the number of waiting and active threads for a SCSI physical device. Optionally, it shows the IDs of waiting and active threads, if any. This routine may be called at any time, but note that all of the information displayed is volatile.
N/A
scsiCacheSynchronize( ) - synchronize the caches for data coherency
void scsiCacheSynchronize ( SCSI_THREAD * pThread, /* ptr to thread info */ SCSI_CACHE_ACTION action /* cache action required */ )
This routine performs whatever cache action is necessary to ensure cache coherency with respect to the various buffers involved in a SCSI command.
The process is as follows:
- 1.
- The buffers for command, identification, and write data, which are simply written to SCSI, are flushed before the command.
- 2.
- The status buffer, which is written and then read, is cleared (flushed and invalidated) before the command.
- 3.
- The data buffer for a read command, which is only read, is cleared before the command.
The data buffer for a read command is cleared before the command rather than invalidated after it because it may share dirty cache lines with data outside the read buffer. DMA drivers for older versions of the SCSI library have flushed the first and last bytes of the data buffer before the command. However, this approach is not sufficient with the enhanced SCSI library because the amount of data transferred into the buffer may not fill it, which would cause dirty cache lines which contain correct data for the un-filled part of the buffer to be lost when the buffer is invalidated after the command.
To optimize the performance of the driver in supporting different caching policies, the routine uses the CACHE_USER_FLUSH macro when flushing the cache. In the absence of a CACHE_USER_CLEAR macro, the following steps are taken:
- 1.
- If there is a non-NULL flush routine in the cacheUserFuncs structure, the cache is cleared.
- 2.
- If there is a non-NULL invalidate routine, the cache is invalidated.
- 3.
- Otherwise nothing is done; the cache is assumed to be coherent without any software intervention.
Finally, since flushing (clearing) cache line entries for a large data buffer can be time-consuming, if the data buffer is larger than a preset (run-time configurable) size, the entire cache is flushed.
N/A
scsiIdentMsgBuild( ) - build an identification message
int scsiIdentMsgBuild ( UINT8 * msg, SCSI_PHYS_DEV * pScsiPhysDev, SCSI_TAG_TYPE tagType, UINT tagNumber )
This routine builds an identification message in the caller's buffer, based on the specified physical device, tag type, and tag number.
If the target device does not support messages, there is no identification message to build.
Otherwise, the identification message consists of an IDENTIFY byte plus an optional QUEUE TAG message (two bytes), depending on the type of tag used.
This function is not intended for use by application programs.
The length of the resulting identification message in bytes or -1 for ERROR.
scsiIdentMsgParse( ) - parse an identification message
SCSI_IDENT_STATUS scsiIdentMsgParse ( SCSI_CTRL * pScsiCtrl, UINT8 * msg, int msgLength, SCSI_PHYS_DEV * * ppScsiPhysDev, SCSI_TAG * pTagNum )
This routine scans a (possibly incomplete) identification message, validating it in the process. If there is an IDENTIFY message, it identifies the corresponding physical device.
If the physical device is currently processing an untagged (ITL) nexus, identification is complete. Otherwise, the identification is complete only if there is a complete QUEUE TAG message.
If there is no physical device corresponding to the IDENTIFY message, or if the device is processing tagged (ITLQ) nexuses and the tag does not correspond to an active thread (it may have been aborted by a timeout, for example), then the identification sequence fails.
The caller's buffers for physical device and tag number (the results of the identification process) are always updated. This is required by the thread event handler (see scsiMgrThreadEvent( ).)
This function is not intended for use by application programs.
The identification status (incomplete, complete, or rejected).
scsiMsgOutComplete( ) - perform post-processing after a SCSI message is sent
STATUS scsiMsgOutComplete ( SCSI_CTRL * pScsiCtrl, /* ptr to SCSI controller info */ SCSI_THREAD * pThread /* ptr to thread info */ )
This routine parses the complete message and takes any necessary action.
This function is intended for use only by SCSI controller drivers.
OK, or ERROR if the message is not supported.
scsiMsgOutReject( ) - perform post-processing when an outgoing message is rejected
void scsiMsgOutReject ( SCSI_CTRL * pScsiCtrl, /* ptr to SCSI controller info */ SCSI_THREAD * pThread /* ptr to thread info */ )
This function is intended for use only by SCSI controller drivers.
OK, or ERROR if the message is not supported.
scsiMsgInComplete( ) - handle a complete SCSI message received from the target
STATUS scsiMsgInComplete ( SCSI_CTRL * pScsiCtrl, /* ptr to SCSI controller info */ SCSI_THREAD * pThread /* ptr to thread info */ )
This routine parses the complete message and takes any necessary action, which may include setting up an outgoing message in reply. If the message is not understood, the routine rejects it and returns an ERROR status.
This function is intended for use only by SCSI controller drivers.
OK, or ERROR if the message is not supported.
scsiSyncXferNegotiate( ) - initiate or continue negotiating transfer parameters
void scsiSyncXferNegotiate ( SCSI_CTRL * pScsiCtrl, /* ptr to SCSI controller info */ SCSI_TARGET * pScsiTarget, /* ptr to SCSI target info */ SCSI_SYNC_XFER_EVENT eventType /* tells what has just happened */ )
This routine manages negotiation by means of a finite-state machine which is driven by "significant events" such as incoming and outgoing messages. Each SCSI target has its own independent state machine.
If the controller does not support synchronous transfer or if the target's maximum REQ/ACK offset is zero, attempts to initiate a round of negotiation are ignored.
This function is intended for use only by SCSI controller drivers.
N/A
scsiWideXferNegotiate( ) - initiate or continue negotiating wide parameters
void scsiWideXferNegotiate ( SCSI_CTRL * pScsiCtrl, /* ptr to SCSI controller info */ SCSI_TARGET * pScsiTarget, /* ptr to SCSI target info */ SCSI_WIDE_XFER_EVENT eventType /* tells what has just happened */ )
This routine manages negotiation means of a finite-state machine which is driven by "significant events" such as incoming and outgoing messages. Each SCSI target has its own independent state machine.
If the controller does not support wide transfers or the target's transfer width is zero, attempts to initiate a round of negotiation are ignored; this is because zero is the default narrow transfer.
This function is intended for use only by SCSI controller drivers.
N/A
scsiThreadInit( ) - perform generic SCSI thread initialization
STATUS scsiThreadInit ( SCSI_THREAD * pThread )
This routine initializes the controller-independent parts of a thread structure, which are specific to the SCSI manager.
This function should not be called by application programs. It is intended to be used by SCSI controller drivers.
OK, or ERROR if the thread cannot be initialized.
scsiCacheSnoopEnable( ) - inform SCSI that hardware snooping of caches is enabled
void scsiCacheSnoopEnable ( SCSI_CTRL * pScsiCtrl /* pointer to a SCSI_CTRL structure */ )
This routine informs the SCSI library that hardware snooping is enabled and that scsi2Lib need not execute any cache coherency code. In order to make scsi2Lib aware that hardware snooping is enabled, this routine should be called after all SCSI-2 initializations, especially after scsi2CtrlInit( ).
N/A
scsiCacheSnoopDisable( ) - inform SCSI that hardware snooping of caches is disabled
void scsiCacheSnoopDisable ( SCSI_CTRL * pScsiCtrl /* pointer to a SCSI_CTRL structure */ )
This routine informs the SCSI library that hardware snooping is disabled and that scsi2Lib should execute any neccessary cache coherency code. In order to make scsi2Lib aware that hardware snooping is disabled, this routine should be called after all SCSI-2 initializations, especially after scsi2CtrlInit( ).
N/A