📄 scsi2lib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/scsi2Lib.html - generated by refgen from scsi2Lib.c --> <title> scsi2Lib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.htm"><i>VxWorks API Reference : OS Libraries</i></a></p></blockquote><h1>scsi2Lib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>scsi2Lib</strong> - Small Computer System Interface (SCSI) library (SCSI-2) </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><a href="./scsi2Lib.html#scsi2IfInit">scsi2IfInit</a>( )</b> - initialize the SCSI-2 interface to <b><a href="./scsiLib.html#top">scsiLib</a></b><br><b><a href="./scsi2Lib.html#scsiTargetOptionsSet">scsiTargetOptionsSet</a>( )</b> - set options for one or all SCSI targets<br><b><a href="./scsi2Lib.html#scsiTargetOptionsGet">scsiTargetOptionsGet</a>( )</b> - get options for one or all SCSI targets<br><b><a href="./scsi2Lib.html#scsiTargetOptionsShow">scsiTargetOptionsShow</a>( )</b> - display options for specified SCSI target<br><b><a href="./scsi2Lib.html#scsiPhysDevShow">scsiPhysDevShow</a>( )</b> - show status information for a physical device<br><b><a href="./scsi2Lib.html#scsiCacheSynchronize">scsiCacheSynchronize</a>( )</b> - synchronize the caches for data coherency<br><b><a href="./scsi2Lib.html#scsiIdentMsgBuild">scsiIdentMsgBuild</a>( )</b> - build an identification message<br><b><a href="./scsi2Lib.html#scsiIdentMsgParse">scsiIdentMsgParse</a>( )</b> - parse an identification message<br><b><a href="./scsi2Lib.html#scsiMsgOutComplete">scsiMsgOutComplete</a>( )</b> - perform post-processing after a SCSI message is sent<br><b><a href="./scsi2Lib.html#scsiMsgOutReject">scsiMsgOutReject</a>( )</b> - perform post-processing when an outgoing message is rejected<br><b><a href="./scsi2Lib.html#scsiMsgInComplete">scsiMsgInComplete</a>( )</b> - handle a complete SCSI message received from the target<br><b><a href="./scsi2Lib.html#scsiSyncXferNegotiate">scsiSyncXferNegotiate</a>( )</b> - initiate or continue negotiating transfer parameters<br><b><a href="./scsi2Lib.html#scsiWideXferNegotiate">scsiWideXferNegotiate</a>( )</b> - initiate or continue negotiating wide parameters<br><b><a href="./scsi2Lib.html#scsiThreadInit">scsiThreadInit</a>( )</b> - perform generic SCSI thread initialization<br><b><a href="./scsi2Lib.html#scsiCacheSnoopEnable">scsiCacheSnoopEnable</a>( )</b> - inform SCSI that hardware snooping of caches is enabled<br><b><a href="./scsi2Lib.html#scsiCacheSnoopDisable">scsiCacheSnoopDisable</a>( )</b> - inform SCSI that hardware snooping of caches is disabled<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This library implements the Small Computer System Interface (SCSI)protocol in a controller-independent manner. It implements only the SCSIinitiator function as defined in the SCSI-2 ANSI specification. This library does not support a VxWorks target acting as a SCSI target.<p>The implementation is transaction based. A transaction is defined as theselection of a SCSI device by the initiator, the issuance of a SCSI command,and the sequence of data, status, and message phases necessary to performthe command. A transaction normally completes with a "Command Complete"message from the target, followed by disconnection from the SCSI bus. Ifthe status from the target is "Check Condition," the transactioncontinues; the initiator issues a "Request Sense" command to gain moreinformation on the exception condition reported.<p>Many of the subroutines in <b><a href="./scsi2Lib.html#top">scsi2Lib</a></b> facilitate the transaction offrequently used SCSI commands. Individual command fields are passed asarguments from which SCSI Command Descriptor Blocks are constructed, andfields of a <b>SCSI_TRANSACTION</b> structure are filled in appropriately. Thisstructure, along with the <b>SCSI_PHYS_DEV</b> structure associated with thetarget SCSI device, is passed to the routine whose address is indicated bythe <b>scsiTransact</b> field of the <b>SCSI_CTRL</b> structure associated with therelevant SCSI controller. The above mentioned structures are defined in <b>scsi2Lib.h</b>.<p>The function variable <b>scsiTransact</b> is set by the individual SCSIcontroller driver. For off-board SCSI controllers, thisroutine rearranges the fields of the <b>SCSI_TRANSACTION</b> structure intothe appropriate structure for the specified hardware, which then carries outthe transaction through firmware control. Drivers for an on-boardSCSI-controller chip can use the <b>scsiTransact( )</b> routine in <b><a href="./scsiLib.html#top">scsiLib</a></b> (whichinvokes the <b>scsi2Transact( )</b> routine in <b><a href="./scsi2Lib.html#top">scsi2Lib</a></b>), as long as they provide the other functions specified in the <b>SCSI_CTRL</b> structure.<p></blockquote><h4>SCSI TRANSACTION TIMEOUT</h4><blockquote><p>Associated with each transaction is a time limit (specified in microseconds,but measured with the resolution of the system clock). If the transactionhas not completed within this time limit, the SCSI library aborts it; thecalled routine fails with a corresponding error code. The timeout periodincludes time spent waiting for the target device to become free to acceptthe command.<p>The semantics of the timeout should guarantee that the caller waits no longer than the transaction timeout period, but in practice thismay depend on the state of the SCSI bus and the connected target device whenthe timeout occurs. If the target behaves correctly according to the SCSIspecification, proper timeout behavior results. However, in certainunusual 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.<p>If the transaction timeout causes problems in your system, you can set thevalue of either or both the global variables "scsi{Min,Max}Timeout". Thesespecify (in microseconds) the global minimum and maximum timeout periods,which override (clip) the value specified for a transaction. They may bechanged at any time and affect all transactions issued after the newvalues are set. The range of both these variable is 0 to 0xffffffff (zero toabout 4295 seconds).<p></blockquote><h4>SCSI TRANSACTION PRIORITY</h4><blockquote><p>Each transaction also has an associated priority used by the SCSIlibrary when selecting the next command to issue when the SCSI system isidle. It chooses the highest priority transaction that can be dispatchedon an available physical device. If there are several equal-prioritytransactions available, the SCSI library uses a simple round-robinscheme to avoid favoring the same physical device.<p>Priorities range from 0 (highest) to 255 (lowest), which is the same as taskpriorities. The priority <b>SCSI_THREAD_TASK_PRIORITY</b> can be used to give thetransaction the same priority as the calling task (this is the method usedinternally by this SCSI-2 library).<p></blockquote><h4>SUPPORTED SCSI DEVICES</h4><blockquote><p>This library requires peripherals that conform to the SCSI-2 ANSIstandard; in particular, the INQUIRY, REQUEST SENSE, andTEST UNIT READY commands must be supported as specified by this standard.In general, the SCSI library is self-configuring to work with any devicethat meets these requirements.<p>Peripherals that support identification and the SCSI message protocol arestrongly recommended as these provide maximum performance.<p>In theory, all classes of SCSI devices are supported. The <b><a href="./scsiLib.html#top">scsiLib</a></b> libraryprovides the capability to transact any SCSI command on any SCSI devicethrough the FIOSCSICOMMAND function of the <b><a href="./scsiLib.html#scsiIoctl">scsiIoctl</a>( )</b> routine (which invokes the <b>scsi2Ioctl( )</b> routine in <b><a href="./scsi2Lib.html#top">scsi2Lib</a></b>).<p>Only direct-access devices (disks) are supported by file systems like dosFs, rt11Fs and rawFs. These file systems employ routines in <b><a href="./scsiDirectLib.html#top">scsiDirectLib</a></b> (most of which are described in <b><a href="./scsiLib.html#top">scsiLib</a></b> but defined in <b><a href="./scsiDirectLib.html#top">scsiDirectLib</a></b>). In the case of sequential-access devices (tapes), higher-leveltape file systems, like tapeFs, make use of <b><a href="./scsiSeqLib.html#top">scsiSeqLib</a></b>. For other types of devices, additional, higher-level software is necessary to map user-levelcommands to SCSI transactions.<p>DISCONNECT/RECONNECT SUPPORTThe target device can be disconnected from the SCSI bus while it carriesout a SCSI command; in this way, commands to multiple SCSI devices canbe overlapped to improve overall SCSI throughput. There are norestrictions on the number of pending, disconnected commands or theorder in which they are resumed. The SCSI library serializes access to thedevice according to the capabilities and status of the device (see thefollowing section).<p>Use of the disconnect/reconnect mechanism is invisible to users of the SCSIlibrary. It can be enabled and disabled separately for each target device(see <b><a href="./scsi2Lib.html#scsiTargetOptionsSet">scsiTargetOptionsSet</a>( )</b>). Note that support for disconnect/reconnectdepends on the capabilities of the controller and its driver (see below).<p></blockquote><h4>TAGGED COMMAND QUEUEING SUPPORT</h4><blockquote><p>If the target device conforms to the ANSI SCSI-2 standard and indicates(using the INQUIRY command) that it supports command queuing, the SCSIlibrary allows new commands to be started on the device whenever the SCSIbus is idle. That is, it executes multiple commands concurrently on thetarget device. By default, commands are tagged with a SIMPLE QUEUE TAGmessage. Up to 256 commands can be executing concurrently.<p>The SCSI library correctly handles contingent allegiance conditions thatarise while a device is executing tagged commands. (A contingentallegiance condition exists when a target device is maintaining sense data thatthe initiator should use to correctly recover from an error condition.) Itissues an untagged REQUEST SENSE command, and stops issuing tagged commandsuntil the sense recovery command has completed.<p>For devices that do not support command queuing, the SCSI library onlyissues a new command when the previous one has completed. These devicescan only execute a single command at once.<p>Use of tagged command queuing is normally invisible to users of the SCSIlibrary. If necessary, the default tag type and maximum number of tags maybe changed on a per-target basis, using <b><a href="./scsi2Lib.html#scsiTargetOptionsSet">scsiTargetOptionsSet</a>( )</b>.<p></blockquote><h4>SYNCHRONOUS TRANSFER PROTOCOL SUPPORT</h4><blockquote><p>If the SCSI controller hardware supports the synchronous transferprotocol, <b><a href="./scsiLib.html#top">scsiLib</a></b> negotiates with the target device to determinewhether to use synchronous or asynchronous transfers. Either VxWorksor the target device may start a round of negotiation. Depending on thecontroller hardware, synchronous transfer rates up to the maximum allowedby the SCSI-2 standard (10 Mtransfers/second) can be used.<p>Again, this is normally invisible to users of the SCSI library, butsynchronous transfer parameters may be set or disabled on a per-target basisby using <b><a href="./scsi2Lib.html#scsiTargetOptionsSet">scsiTargetOptionsSet</a>( )</b>.<p></blockquote><h4>WIDE DATA TRANSFER SUPPORT</h4><blockquote><p>If the SCSI controller supports the wide data transfer protocol, <b><a href="./scsiLib.html#top">scsiLib</a></b>negotiates wide data transfer parameters with the target device, ifthat device also supports wide transfers. Either VxWorks or the target devicemay 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 withsynchronous transfer, up to a maximum of 20MB/sec. can be attained.<p>Wide data transfer negotiation is invisible to users of this library,but it is possible to enable or disable wide data transfers and theparameters on a per-target basis by using <b><a href="./scsi2Lib.html#scsiTargetOptionsSet">scsiTargetOptionsSet</a>( )</b>.<p></blockquote><h4>SCSI BUS RESET</h4><blockquote><p>The SCSI library implements the ANSI "hard reset" option. Any transactionsin progress when a SCSI bus reset is detected fail with an error codeindicating termination due to bus reset. Any transactions waiting to startexecuting are then started normally.<p></blockquote><h4>CONFIGURING SCSI CONTROLLERS</h4><blockquote><p>The routines to create and initialize a specific SCSI controller areparticular to the controller and normally are found in its librarymodule. The normal calling sequence is:<p><pre> xxCtrlCreate (...); /* parameters are controller specific */ xxCtrlInit (...); /* parameters are controller specific */</pre>The conceptual difference between the two routines is that <b>xxCtrlCreate( )</b>calloc's memory for the <b>xx_SCSI_CTRL</b> data structure and initializesinformation that is never expected to change (for example, clock rate). Theremaining fields in the <b>xx_SCSI_CTRL</b> structure are initialized by<b>xxCtrlInit( )</b> and any necessary registers are written on the SCSIcontroller to effect the desired initialization. This routine can becalled multiple times, although this is rarely required. For example, thebus ID of the SCSI controller can be changed without rebooting the VxWorkssystem.<p></blockquote><h4>CONFIGURING PHYSICAL SCSI DEVICES</h4><blockquote><p>Before a device can be used, it must be "created," that is, declared.This is done with <b><a href="./scsiLib.html#scsiPhysDevCreate">scsiPhysDevCreate</a>( )</b> and can only be done after a<b>SCSI_CTRL</b> structure exists and has been properly initialized.<p><pre>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 */ )</pre>Several of these parameters can be left unspecified, as follows:<dl><dt><i>reqSenseLength</i><dd>If 0, issue a <b>REQUEST_SENSE</b> to determine a request sense length.<dt><i>devType</i><dd>This parameter is ignored: an INQUIRY command is used to ascertain thedevice type. A value of NONE (-1) is the recommended placeholder.<dt><i>numBlocks</i>, <i>blockSize</i><dd>If 0, issue a <b>READ_CAPACITY</b> to determine the number of blocks.</dl><p>The above values are recommended, unless the device does not support therequired commands, or other non-standard conditions prevail.<p></blockquote><h4>LOGICAL PARTITIONS ON DIRECT-ACCESS BLOCK DEVICES</h4><blockquote><p>It is possible to have more than one logical partition on a SCSI blockdevice. This capability is currently not supported for removable mediadevices. A partition is an array of contiguously addressed blockswith a specified starting block address and specified number of blocks.The <b><a href="./scsiLib.html#scsiBlkDevCreate">scsiBlkDevCreate</a>( )</b> routine is called once for each block devicepartition. Under normal usage, logical partitions should not overlap.<p><pre>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 */ )</pre>Note that if <i>numBlocks</i> is 0, the rest of the device is used.<p></blockquote><h4>ATTACHING DISK FILE SYSTEMS TO LOGICAL PARTITIONS</h4><blockquote><p>Files cannot be read or written to a disk partition until a file system (forexample, dosFs, rt11Fs, or rawFs) has been initialized on the partition.For more information, see the relevant documentation in <b><a href="./dosFsLib.html#top">dosFsLib</a></b>,<b><a href="./rt11FsLib.html#top">rt11FsLib</a></b>, or <b><a href="./rawFsLib.html#top">rawFsLib</a></b>.<p></blockquote><h4>USING A SEQUENTIAL-ACCESS BLOCK DEVICE</h4><blockquote><p>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 layerslike tapeFs by the <b><a href="./scsiSeqLib.html#scsiSeqDevCreate">scsiSeqDevCreate</a>( )</b> routine, described in <b><a href="./scsiSeqLib.html#top">scsiSeqLib</a></b>. The<b><a href="./scsiSeqLib.html#scsiSeqDevCreate">scsiSeqDevCreate</a>( )</b> routine is called once for a given SCSI physical device.<pre>SEQ_DEV *scsiSeqDevCreate ( SCSI_PHYS_DEV *pScsiPhysDev /* ptr to SCSI physical device info */ )</pre></blockquote><h4>TRANSMITTING ARBITRARY COMMANDS TO SCSI DEVICES</h4><blockquote><p>The <b><a href="./scsi2Lib.html#top">scsi2Lib</a></b>, <b><a href="./scsiCommonLib.html#top">scsiCommonLib</a></b>, <b><a href="./scsiDirectLib.html#top">scsiDirectLib</a></b>, and <b><a href="./scsiSeqLib.html#top">scsiSeqLib</a></b> libraries collectively provide routines that implement all mandatory SCSI-2 direct-access and sequential-access commands. Still, there are situations thatrequire 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<b><a href="./scsiLib.html#scsiIoctl">scsiIoctl</a>( )</b>. The <i>arg</i> parameter for FIOSCSICOMMAND is a pointer to avalid <b>SCSI_TRANSACTION</b> structure. Typically, a call to <b><a href="./scsiLib.html#scsiIoctl">scsiIoctl</a>( )</b> is writtenas a subroutine of the form:<pre>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 */ .⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -