============================================================ C E N T R A L D A T A ============================================================ scsiServer(TM) Firmware Reference Manual Copyright (C) 1992-1994 Central Data Corporation 1602 Newton Drive Champaign, IL 61821-1098 (217) 359-8010 (800) 482-0315 Additional copies of this manual can be obtained through your local sales office or by contacting: Central Data Corporation 1602 Newton Drive Champaign, IL 61821-1098 (217) 359-8010 (800) 482-0315 The information in this document is subject to change without notice. Central Data Corporation makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Central Data Corporation makes no commitment to update nor to keep current the information contained in this document. The information in this manual is believed to be accurate in all respects. However, Central Data Corporation assumes no responsibility for any errors or consequences resulting from any errors in this manual. Central Data Corporation assumes no responsibility for the use of any circuitry other than the circuitry entirely embodied in a Central Data Corporation product. No part of this document may be copied or reproduced in any form or by any means without prior written consent of Central Data Corporation. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement. Central Data Corporation, 1602 Newton Drive, Champaign, Illinois 61821. scsiServer(TM) is a trademark of Central Data Corporation. UNIX(R) is a registered trademark of UNIX Systems Laboratories. Copyright (C) 1992-1994, Central Data Corporation, All Rights Reserved. This version of the scsiServer Firmware Reference Manual was published on November 9, 1994. Contents ============================================================ About This Manual . . . . . . . . . . . . . . . . . . . . iv Related Documentation . . . . . . . . . . . . . . . . . . v scsiServer Firmware Overview . . . . . . . . . . . . . . 1 Overview . . . . . . . . . . . . . . . . . . . . . . 1 SCSI Implementation . . . . . . . . . . . . . . 1 Formats for the FAS Layer . . . . . . . . . . . 3 SCSI Packet Protocols . . . . . . . . . . . . . . . 6 FAS Command Protocols . . . . . . . . . . . . . . . 7 FAS Command Descriptions . . . . . . . . . . . . . . . . 9 FAS_DISABLE . . . . . . . . . . . . . . . . . . . . 12 FAS_ENABLE . . . . . . . . . . . . . . . . . . . . . 13 FAS_FLOW_CTL . . . . . . . . . . . . . . . . . . . . 15 FAS_GLOBAL . . . . . . . . . . . . . . . . . . . . . 18 FAS_IN_TIMERS . . . . . . . . . . . . . . . . . . . 20 FAS_INPUT_CTL . . . . . . . . . . . . . . . . . . . 22 FAS_OUTPUT_CTL . . . . . . . . . . . . . . . . . . . 23 FAS_RECV . . . . . . . . . . . . . . . . . . . . . . 25 FAS_RELEASE . . . . . . . . . . . . . . . . . . . . 27 FAS_RESERVE . . . . . . . . . . . . . . . . . . . . 28 FAS_SEND . . . . . . . . . . . . . . . . . . . . . . 29 FAS_SEND_BRK . . . . . . . . . . . . . . . . . . . . 30 FAS_SET_MODEM . . . . . . . . . . . . . . . . . . . 31 FAS_SET_PARAMS . . . . . . . . . . . . . . . . . . . 32 FAS_STAT_CHG . . . . . . . . . . . . . . . . . . . . 36 About This Manual ============================================================ This manual provides details on the software interface to Central Data's scsiServer product family. It is intended for those users writing device drivers for an operating system which Central Data doesn't support. Central Data offers a variety of operating system drivers for various UNIX-type platforms. When a scsiServer is used with one of Central Data's standard device drivers, the device's software interface described here is hidden by the device driver. In those cases, the ports on a scsiServer will operate just like other serial or parallel ports on the system. This manual assumes that readers are familiar with the SCSI Common Command Set and the particular operating system they are using. Related Documentation ============================================================ Hardware Installation Guides are packaged with each Central Data scsiServer. Software Installation Guides are provided with each operating system device driver. These guides should be used when installing scsiServers on systems supported by Central Data. For further information about the SCSI interface and its protocols, refer to the following texts and standards: ANSI Draft Proposal. X3.131-198x. (SCSI-2 working draft, Revision 7 most recent at this time) ANSI SCSI Standard. X3.131-1986. Both ANSI specifications can be ordered from: Global Engineering Documents 2805 McGaw Irvine, CA 92714 (800) 854-7179 (714) 261-1455 SCSI Guidebook. 2nd ed. Pomona, CA: Adaptive Data Systems, 1985. Available from: Adaptive Data Systems, Inc. 2627 Pomona Boulevard Pomona, CA 91768 (714) 594-5858 Chapter 1 scsiServer Firmware Overview ============================================================ This chapter provides an overview of the FastAsync (FAS) firmware and its command set for those who want to develop custom device drivers for scsiServers. All references to terminals in this document apply to any devices that connect through either the serial or parallel ports. (Chapter 2 covers the extensions to FastAsync that provide parallel printer support.) If you intend to develop your own software drivers for the SCSI FastAsync products, it will be very helpful to obtain the source code to one of Central Data's UNIX operating system drivers, along with Central Data's device driver porting guide. Drivers using either clist or streams tty protocols are available. These items will provide valuable implementation details that supplement the material covered in this chapter. Contact Central Data for further information on how you can obtain source code to a driver. A license agreement and non-disclosure agreement must be signed to receive this information. 1.1 Overview ------------------------------------------------------------ The FastAsync firmware interacts with host computers solely through a standard SCSI bus interface. Although the SCSI bus is more traditionally thought of only as a mass storage bus, it may also be viewed as a more general purpose message-passing extension of the main system bus. The SCSI bus is used to pass data back and forth, including packetized commands, responses, and data for all the asynchronous lines. The packetized nature of the transactions serves to keep overhead low at both the SCSI bus and the host. The protocol used to communicate between the host and the FastAsync firmware can be viewed as two distinct layers: the SCSI layer and the FAS layer. The traffic for the FAS layer is carried by the SCSI layer in the data portions of standard SCSI commands. The next sections describe first the SCSI implementation, then the FAS layer and how it is conveyed by the SCSI layer. 1.1.1 SCSI Implementation The SCSI implementation for the FAS firmware conforms to the SCSI-2 Common Command Set specification for a communications device. The communications device interface is a general interface that supports a wide variety of communications needs. As such, the common command set for this type of device is minimal. The definition of specific functions is wisely left to the discretion of the implementers of the particular communications device. The standard SCSI commands Inquiry, Test Unit Ready, Send Diagnostic, and Request Sense are supported to allow FastAsync units to be located, checked for operability, and diagnosed. The bulk of the work, however, is performed by just two commands: Send Message and Get Message. These commands are analogous to the SCSI direct access commands Read and Write, and in fact use the same opcodes. They provide the means whereby all commands and data are transferred to/from the FastAsync terminal handling kernel. The Send Message command passes a FAS data packet to the terminal-handling kernel, while the Get Message command receives a FAS data packet from the terminal-handling kernel. The format of these packets is designed to suit the specific needs of controlling terminals. A packet contains one or more subcommands, which are part of the FAS command set. FastAsync does not initiate synchronous negotiation because Central Data hardware usually transfers data more quickly in asynchronous mode. However, if the host initiates the negotiation, FAS will proceed to negotiate, either setting a synchronous transfer rate appropriate for the specific hardware or refusing synchronous transfers on hardware that will not support them. Although this SCSI implementation conforms to the SCSI-2 specification, no features unique to SCSI-2 are used. Refer to the SCSI-2 specification for details about SCSI protocols and the individual SCSI commands for a communications device. 1.1.1.1 Dual-LUN Mode. The FastAsync firmware by default requires that two logical unit numbers (LUNs) be used to provide full duplex communication with FastAsync. Since only one command can be outstanding per LUN at a time, a single LUN should not be used to service outgoing traffic while simultaneously waiting for incoming traffic. Typically, you would use LUN 0 for all SCSI Send Message commands, while posting all SCSI Get Message commands to LUN 1. This assignment is arbitrary and could be reversed, as long as one method is used consistently. This dual-LUN interface allows a SCSI Get Message to be posted and a disconnect to occur if no data is present. In the meantime, SCSI Send Message commands can be sent to maintain the outgoing traffic. Note that the SCSI host bus adapter must support disconnect/reselect operation for FastAsync to function properly. 1.1.1.2 Single-LUN Mode. Some SCSI implementations do not correctly support multiple LUNs at a SCSI device, so a second mode of operation is provided. This single-LUN interface may be selected via an option flag in the FAS_GLOBAL command. If this mode is desired, the FAS_GLOBAL command should be the first command sent to the unit, and the GLOBAL_ONE_LUN_MODE flag should be set. Refer to the command description of FAS_GLOBAL in Chapter 2 for more information. Single-LUN mode operation maintains full duplex communication by forcing a SCSI Get Message command to time out after a short period of time if nothing has been posted for return to the host. This frees up the channel so that a Send Message may be posted. In essence, this mode uses polling to monitor receive traffic at the unit, interspersing the polling message with outgoing traffic as needed. The polling rate is automatically adjusted by firmware based on the level of activity at the unit. Although this polling method results in some excess SCSI overhead during periods of light loading, it breaks even in terms of overhead during periods of heavy loading since the maximum transaction rate is the same in both modes. When using single-LUN mode, both Send Message commands and Get Message commands are sent to LUN zero at the STS unit. 1.1.2 Formats for the FAS Layer The FAS layer consists of the FAS command set described in Chapter 2. These FAS commands are transported by the SCSI layer via two SCSI commands: SCSI Send Message and SCSI Get Message. These are the only two SCSI commands associated with the FAS layer, which imposes form and function upon SCSI Send Message and SCSI Get Message. The SCSI Send Message command is composed of two parts: the 6-byte command descriptor block (CDB) and an accompanying outgoing (away from the host) data portion. Refer to the SCSI specification for the format of the Send Message CDB. The length of the data portion may vary, but its length must be entered in the length field of the CDB. The SCSI Get Message command is similar. It is also composed of a 6-byte CDB, but with an incoming (towards the host) data portion. In this case, the length specification in the CDB specifies the maximum length data portion that can be received. The data portion may be any length less than or equal to this maximum. The following sections describe the data portions for SCSI Send Message and SCSI Get Message. 1.1.2.1 Send Packet Format for SCSI Send Message. The data portion of the SCSI Send Message command could simply be called a send packet. The firmware expects that the length of this send packet will not exceed 2048 bytes. The send packet can contain one or more FAS commands. If any of these commands have, in turn, an associated data portion, this FAS command-specific data portion will immediately follow the FAS command block. Send Packet Format SCSI Send Message Command Descriptor Block (6 bytes) Data Portion (n bytes) FAS_SET_PARAMS cmd. (line #1) 8 bytes FAS_ENABLE command (line #5) 8 bytes FAS_SEND command (line #3) 8 bytes Data portion for FAS_SEND x bytes FAS_SEND command (line #13) 8 bytes Data portion for FAS_SEND y bytes FAS_RECV command (line #1) 8 bytes PKT_END (packet end code) 1 byte Figure 1-1 SCSI Send Message with Send Packet All FastAsync command blocks are 8 bytes in length. Associated data portions may be any length, as long as the 2048 maximum packet length is not exceeded. To help you visualize the format of the SCSI Send Message along with a typical data portion/send packet, see Figure 1-1. The first two commands do not have any data portion associated with them. The next two commands do have data portions, and the last command again has no data portion. (A representative group of actual FAS commands is shown to demonstrate how multiple lines may be serviced within a single packet.) The packet is always terminated with a packet end code. Note that FastAsync commands with an associated data portion have a field in the command block describing the length of the data. This allows the starting location within the byte stream of the next command block to be determined. 1.1.2.2 Receive Packet Format for SCSI Get Message. The format of the data portion returned by the SCSI Get Message command is very similar. This data portion will be referred to as a receive packet. It consists of interleaved response blocks and response-specific data portions. Response blocks are also always 8 bytes in length. In all respects the receive packet resembles a send packet, except that it is transferred towards the host (instead of away from), and contains responses instead of commands. The data portion is also terminated by the packet end code, and it will never exceed 2048 bytes in total length. Receive Packet Format SCSI Get Message Command Descriptor Block (6 bytes) Data Portion (n bytes) FAS_ENABLE response (line #7) 8 bytes FAS_SET_MODEM resp. (line #3) 8 bytes FAS_RECV response (line #6) 8 bytes Data portion for FAS_RECV x bytes FAS_DISABLE response (line #11) 8 bytes FAS_RECV response (line #11) y bytes Data portion for FAS_RECV 8 bytes PKT_END (packet end code) 1 byte Figure 1-2 SCSI Get Message with Receive Packet An example receive packet is shown in Figure 1-2. It again includes a representative group of actual FAS commands. (No relationship between these commands and the ones shown in Figure 1-1 is implied.) Note that many lines can be serviced in a single packet. Receive packets lengths will always be evenly divisible by four, in order to avoid problems with certain types of SCSI hardware that have difficulty with odd bytes. No such requirement exists for send packets, however; Central Data's hardware and software correctly handles odd bytes. 1.2 SCSI Packet Protocols ------------------------------------------------------------ Some very simple rules apply to the handling of the send and receive packets. These rules can be viewed logically as being a layer above the rules that apply to the individual FAS commands. In fact, most of these rules are dictated by the SCSI specification. The SCSI specification allows only one transaction to be active between a given host and a given target LUN at a time. (SCSI-2 does allow for queued commands, but these are not needed by our FastAsync implementation). Thus, you should wait until the response is returned from a SCSI Send Message command before issuing another one. Likewise, the response to a SCSI Get Message command must be returned before another one is dispatched. It is good practice to send another SCSI Get Message command immediately after you receive a response from the previous one. This is necessary to keep the incoming data stream flowing. To help promote efficient packetization of FAS commands, the FastAsync kernel may disconnect from a SCSI command, introduce a short delay, and then reselect. This is analogous to a disk drive that disconnects during a seek. This pacing action keeps overhead low, both at the SCSI bus and at the host. Otherwise, the multitude of individual transactions at all the async lines would tend to overload the SCSI bus and thus tax the host with excessive SCSI processing. When the unit is lightly loaded, SCSI responses will be almost immediate. As the unit becomes more highly loaded, a throttling behavior will tend to limit the SCSI message rate to some maximum number per second. The default allows approximately 30 SCSI sends and 30 SCSI receives per second. This provides good echoback response, while limiting SCSI bus loading and processing to an amount comparable to a single SCSI disk drive. This maximum transaction rate is programmable in software via the FAS_GLOBAL command. This approach makes the pacing and throttling action invisible to the host. The host itself need not deal with timeout issues or otherwise generate delays. It simply follows standard SCSI protocols and lets the FastAsync firmware provide the pacing action. Also, all aspects of the SCSI protocols are very normal and place no undue expectations on the SCSI protocol drivers or host bus adapters. However, as mentioned above, some host implementations do not correctly support multiple LUNs. If this is the case, single-LUN mode can be used. The same basic rules apply, but Send Message commands should be interleaved with the Get Message commands to maintain full duplex communication. 1.3 FAS Command Protocols ------------------------------------------------------------ As mentioned previously, all FAS commands and responses are 8 bytes in length. Any additional data associated with a command or response immediately follows the associated FAS command block in the SCSI packet. A response is defined for every FAS command, and a response is always returned for every command. Multiple FAS commands for a given line can be placed in a single packet. For instance, you might send both a FAS_SET_PARAMS and a FAS_FLOW_CTRL in the same packet. However, certain commands depend on the completion of other prior commands and thus should not be placed in the same packet. An example of a situation where the commands could not be sent in the same packet would be after a FAS_ENABLE is sent to open a line, you must wait for the response to the FAS_ENABLE to come back before issuing further commands to the line. Also, some FAS commands cannot be reissued until a response to a previous one is returned. A FAS_SEND cannot be repeated until a previous FAS_SEND has returned its response. Command-specific protocols such as these are discussed further as the individual commands are described in the next chapter. Chapter 2 FAS Command Descriptions ============================================================ This chapter describes the FAS commands in alphabetical order, based on mnemonics that are consistent with Central Data's UNIX drivers. Some STS products provide parallel printer ports as well as serial ports. These parallel ports use the same commands as the serial ports and are in most respects identical. Certain commands, however, have no effect on parallel ports and are simply ignored (e.g., baud rate settings and flow control options have no effect). Implications for parallel ports are noted within the descriptions for individual commands. Some of the commands use 16-bit values; these are ordered least significant byte first. Fields that are defined Unused need not be initialized to any known value. Fields defined as Reserved should be set to zero for compatibility with future software releases. Tables 2-1 and 2-2 provide a listing of all FAS commands and FAS status codes, respectively. NOTE: All commands except FAS_GLOBAL affect only a single, specified line. Table 2-1 FAS Commands and Opcodes Command Opcode Description FAS_DISABLE 02H Disables specific async line, turning off interrupts, etc. FAS_ENABLE 01H Enables specific async line, initializing to defaults; must be issued before any other command to a line FAS_FLOW_CTL 0CH Sets firmware flow control parameters FAS_GLOBAL 00H Sets global firmware options for all lines FAS_IN_TIMERS 05H Sets custom block transfer parameters (used for communications lines) FAS_INPUT_CTL 07H Flushes, suspends, or resumes input at a line FAS_OUTPUT_CTL 06H Flushes, suspends, or resumes output at a line FAS_RECV 04H Receives input data FAS_RELEASE 0EH Releases private use of a line FAS_RESERVE 0DH Requests private use of a line FAS_SEND 03H Sends data for output FAS_SEND_BRK 0AH Issues break indication FAS_SET_MODEM 08H Controls modem output signals FAS_SET_PARAMS 0BH Sets line parameters (e.g., baud rate, bits per character, stop bits) FAS_STAT_CHG 09H Monitors modem input signals PKT_END 64H Termination code for end of packet Table 2-2 FAS Status Codes Error Code Opcode Description OK 00H Successful completion ERR_FAIL 80H ORed with other error codes to indicate a serious condition ERR_MULT_CMD 01H Extra command received for command type that only allows one in progress at a time ERR_BAD_PARAM 02H Command parameter out of range ERR_NOT_PRESENT 03H Specific line number out of range not present ERR_PARITY 04H Input characters(s) received with parity errors ERR_OVERRUN 05H Overrun(s) during input ERR_FRAMING 06H Input characters(s) received with framing errors ERR_UNKNOWN 07H Possibly multiple errors on received character(s) ERR_INITD 08H Command issued on uninitialized line or attempt made to reinitialize a line ERR_BAD_CMD 09H Command code not valid ERR_ABORTED 0AH Commands aborted by a flush ERR_BREAK 0BH Break condition at a line ERR_OVERFLOW 0CH Input buffers overflowed at STS, some input has been lost Every response message contains a status code. A number of status conditions are not actual errors, but simply provide behavioral information. If there is a serious error, the high bit of the status code is set (ERR_FAIL). FAS_DISABLE ------------------------------------------------------------ This command is the counterpart to the FAS_ENABLE command. FAS_DISABLE disables a line by clearing all modem signals and releasing any buffers associated with the line. A FAS_DISABLE is issued when a line is to be closed. It restores a line to an inactive state with input interrupts disabled, modem signals released, and any local buffers and data structures cleaned up. The FAS_DISABLE disables input immediately. It then waits until any pending output at the line has completed or has been flushed, before finishing its duties and returning a response message. Although it is not good practice to issue commands to a line that has not been enabled, commands must sometimes be issued after a FAS_DISABLE command and before the next FAS_ENABLE. If the FAS_DISABLE has completed, these commands will be ignored, and a benign ERR_INITD or ERR_ABORTED status will be returned. If the FAS_DISABLE is pending on output completion, these commands will be processed. This is necessary, for instance, when a UNIX line discipline issues a close, immediately followed by input and output flush/resume indications. Request Format Offset Function 0 Command Opcode (02H) 1 Line Number 2-7 Unused Response Format Offset Function 0 Command Opcode (02H) 1 Line Number 2 Status 3-7 Unused FAS_ENABLE ------------------------------------------------------------ This command should generally be the first command issued to a line, although the FAS_RESERVE command could be used to resolve any possible contention between multiple hosts prior to issuing the FAS_ENABLE. The FAS_ENABLE first checks for any pending FAS_DISABLE in progress. It blocks until the FAS_DISABLE completes. Then it initializes the line to certain defaults. These defaults, along with the FAS commands that can be used to modify them, are listed below. Default Setting To Modify, Use 9600 baud FAS_SET_PARAMS 1 stop bit FAS_SET_PARAMS No parity FAS_SET_PARAMS Receiver enabled FAS_SET_PARAMS No local loopback FAS_SET_PARAMS Modem signals cleared FAS_SET_MODEM No flow control FAS_FLOW_CTL High watermark = 128 FAS_FLOW_CTL Input timer = 0 FAS_IN_TIMERS (Refer to the appropriate FAS command description for more information regarding each setting.) If the line is actually a parallel port, and this is the first FAS_ENABLE, the printer's SEL line is asserted and the INIT line is strobed for 15 ms. After FAS_ENABLE has completed its duties, a response is returned. The host should wait until this response is returned before issuing any further commands to the line. Request Format Offset Function 0 Command Opcode (01H) 1 Line Number 2-7 Unused Response Format Offset Function 0 Command Opcode (01H) 1 Line Number 2 Status 3-7 Unused FAS_FLOW_CTL ------------------------------------------------------------ FAS_FLOW_CTL selects various flow control parameters for a line. The FastAsync firmware is capable of offloading all flow control processing from the host. This makes character handling much more efficient at the host. The flow control options provided are well-matched to the common UNIX asynchronous line disciplines. Request Format Offset Function 0 Command Opcode (0CH) 1 Line Number 2 Input Flow Control Mode 3 Output Flow Control Mode 4 XON (CSTART) Character 5 XOFF (CSTOP) Character 6-7 High Watermark Response Format Offset Function 0 Command Opcode (0CH) 1 Line Number 2 Status 3-7 Unused The Input Flow Control Mode field sets the input flow control into one of two basic modes listed below, plus a hardware handshaking mode (using RTS) that can be enabled with either mode. FC_NONE No automatic flow control action is used. (00H) FC_XON_XOFF1 If the input high watermark is exceeded, an (01H) XOFF character (sometimes also called a CSTOP character) will be sent out. An XON (CSTART) character will be sent when the host has retrieved enough input that the count of characters buffered has fallen below the low watermark (i.e., half of the high watermark). FC_RTS_CTS This flag may be Ored with either basic mode. (80H) This mode uses the RTS signal to indicate whether the agent on the other end is allowed to continue sending. RTS asserted means go, while RTS released means stop. The Output Flow Control Mode field sets the output flow control mode. Output flow control can be set to one of four basic modes listed below. A hardware handshaking mode is provided for use with any of the other modes. FC_NONE No flow control is present; output cannot be (00H) stopped by the agent on the other end of the line. FC_XON_XOFF1 The agent on the other end can stop output by (01H) sending an XOFF (CSTOP) character and can restart output by sending an XON (CSTART) character. The XON and XOFF characters are not passed in to the host, so flow control is transparent to the host. FC_XON_XOFF2 This mode is identical to FC_XON_XOFF1 except (02H) that, in addition to swallowing the XOFF and XOFF characters, any characters received in between an XOFF-XON pair will also be swallowed. Although it is not very UNIX-compatible, this mode may be useful in some situations. FC_IXANY The agent on the other end can stop output (03H) with the XOFF (CSTOP) character, but any subsequent character restarts it. XON and XOFF characters are not passed in to the host, but other characters used to restart are passed in. This conforms to common UNIX flow control conventions for this mode. FC_RTS_CTS This flag value can be ORed with any other (80H) basic mode. The CTS signal must be asserted for output to proceed. Thus, the agent on the other end may control output by selectively toggling the CTS signal to indicate an ability to process further characters. The XON Character field sets the character that will be recognized as the XON (or CSTART) character. Almost universally this will be CONTROL-Q (11H). The XOFF Character field sets the character that will be recognized as the XOFF (or CSTOP) character. This will usually be CONTROL-S (13H). The High Watermark field sets the number of characters at which flow control actions take place. A low watermark is also calculated from this, which is equal to one half of the high watermark. Even if no flow control modes are enabled, this watermark is still used by the FAS_SEND command. See the FAS_SEND command description for more information. If the line is actually a parallel port, the only significant field is the High Watermark; all other fields are ignored. The High Watermark field should probably be set in the range of 2000 to 3000, because a parallel port can transfer data faster than a serial line. See the FAS_SEND command for more information about the use of this field. FAS_GLOBAL ------------------------------------------------------------ FAS_GLOBAL controls certain features of the firmware that affect all lines. It should be the first command sent to the unit, and it should not be sent again unless the unit can be guaranteed inactive. Request Format Offset Function 0 Command Opcode (00H) 1 Version 2-3 Interrupt Rate 4-5 Buffer Size 6 Option Flags 7 Full Error-Checking Flag Response Format Offset Function 0 Command Opcode (00H) 1 Version 2 Status 3-7 Unused The Version field may be used in the future to provide backward compatibility. It should be set to the firmware version for which your driver was developed. This version may be discovered by examining the response to this command. The default value for this field is zero. The Interrupt Rate field sets the maximum interaction rate between the host and the FAS firmware. This affects SCSI bus loading, host processing overheads, and on-board FAS processing overheads. The default value of 30 allows up to 30 SCSI Send Message and 30 SCSI Get Message packets per second. This approximates the SCSI loading of one fast disk drive. It provides both low overhead and reasonable response times. Higher interrupt rates will provide faster response times, but at the expense of increased loading. Legal values are in the range 10-300, but 100 is the recommended practical upper limit. The Buffer Size field should always be set to zero, which in turn sets the default buffer size. This field is used only for firmware testing. The Option Flags field contains several flags which select various firmware option modes. The option flags are bit flags defined as follows: Bit Mnemonic Function (when set) 7-4 -- Reserved for future use 3 GLOBAL_ONE_LUN_MODE Select single-LUN SCSI interface mode 2 GLOBAL_DEBUG_MODE Enables port 0 as special debug port 1 GLOBAL_IGNORE RESET Firmware ignores SCSI resets 0 GLOBAL_LED_BLINK Enables blinking power LED as loading indicator (blinks more slowly during heavy loading) The Full Error-Checking Flag enables a more stringent level of error checking in the firmware. This is useful during driver development to help catch certain protocol errors. However, this flag should be disabled after the driver is fully debugged because it adversely affects firmware performance during periods of heavy loading. A non-zero value enables full error-checking. FAS_IN_TIMERS ------------------------------------------------------------ FAS_IN_TIMERS specifies a timeout value that governs response generation for FAS_RECV commands. A packetizing feature can be enabled for input, which can reduce the overhead of handling large blocks of fast input. In addition, an input timeout value can be specified that will cause a response to a FAS_RECV to be held off during a burst of input until either the burst subsides or the currently posted FAS_RECV byte count can be fully satisfied. The timeout value specifies how long the burst must abate before the response is returned. It is specified in ticks (approx. 1/30 of a second) and is only approximate. The following table provides values that yield good packetizing of burst input, assuming steady traffic at the particular baud rate. Baud Rate Timeout Value No packetizing at any baud rate 0 2400 baud and above 1 1200 baud 2 600 baud 3 300 baud 4 The default value is 0, which indicates no packetizing. A very large timeout value will effectively cause the response to be delayed until the specified number of characters in the FAS_RECV has been received. Request Format Offset Function 0 Command Opcode (05H) 1 Line Number 2 Timeout Value 3-7 Unused Response Format Offset Function 0 Command Opcode (05H) 1 Line Number 2 Status 3-7 Unused FAS_INPUT_CTL ------------------------------------------------------------ FAS_INPUT_CTL allows the host to explicitly flush, suspend, or resume input. Request Format Offset Function 0 Command Opcode (07H) 1 Line Number 2 Flush Flag 3 Suspend Flag 4 Resume Flag 5-7 Unused Response Format Offset Function 0 Command Opcode (07H) 1 Line Number 2 Status 3-7 Unused If the Flush Flag field is non-zero, any pending input buffered at the unit is cleared. If the Suspend Flag field is non-zero and an XON/XOFF input flow control mode is enabled (see the FAS_FLOW_CTL command), an XOFF (CSTOP) character is sent to try to stop the other agent from sending. If the Resume Flag field is non-zero and an XON/XOFF input flow control mode is enabled, an XON (CSTART) character is sent to attempt to tell the other agent to continue sending. More than one flag may be set. For instance, a Flush with Resume indication would be quite common. However, you obviously should not try to suspend and resume at the same time. FAS_OUTPUT_CTL ------------------------------------------------------------ FAS_OUTPUT_CTL allows the host to explicitly flush, suspend, or resume output. Request Format Offset Function 0 Command Opcode (06H) 1 Line Number 2 Flush Flag 3 Suspend Flag 4 Resume Flag 5-7 Unused Response Format Offset Function 0 Command Opcode (06H) 1 Line Number 2 Status 3-7 Unused If the Flush Flag field is non-zero, then any pending output buffered for the line will be cleared. Any FAS_SEND message that is blocked, waiting for output to drain below the low watermark, will immediately return a response. Any FAS_DISABLE command that is blocked, pending completion of output at that line, will unblock and return a response. If the Suspend Flag field is non-zero, output at the unit will be halted. This works in conjunction with any flow control modes that are enabled. If the Resume Flag field is non-zero and output has been halted at the unit, either by a prior FAS_OUTPUT_CTL with suspend indication or by the other agent issuing an XOFF, then output will be restarted. If output is currently in progress, the Resume Flag has no effect. More than one flag may be set. For instance, a Flush with Resume indication would be quite common. However, you obviously should not try to suspend and resume at the same time. FAS_RECV ------------------------------------------------------------ FAS_RECV returns characters to the host. All incoming data from the serial lines is returned using this command. A FAS_RECV should be posted to a line as soon as it is opened. As soon as a FAS_RECV completes, another should be sent, but only after the response from a previous one is returned. Only one Receive can be pending per enabled line. The returned data immediately follows the 8-byte response message in the data portion of the SCSI Get Message packet. The actual byte count being returned is provided in the response message. The data is simply a stream of bytes and may be of any length less than or equal to the maximum receive size specified in the original command message. A response will not be returned until at least one byte has been received. If the FAS_IN_TIMERS command has been used to specify a timeout interval, it may delay returning a response during a steady flow of characters until either the character flow pauses or the specified maximum byte count is reached. For more information, see the FAS_IN_TIMERS command description. The response can return a number of status codes indicating break, parity, overrun, and framing error conditions in addition to the standard protocol violation codes. When one of these character-related error status messages is returned, it is assumed to apply to all characters returned within that data portion if there are more than one. The Maximum Byte Count field can be any value within the constraints of the maximum total packet size of 2048. If a FAS_RECV is pending when a line is disabled, a response will be returned with a byte count of zero and a status of ERR_ABORTED. If the line is actually a parallel port, the FAS_RECV command will have no effect because parallel port input is not currently supported. Request Format Offset Function 0 Command Opcode (04H) 1 Line Number 2-3 Maximum Byte Count 4-7 Unused Response Format Offset Function 0 Command Opcode (04H) 1 Line Number 2 Status 3 Unused 4-5 Returned Byte Count 6-7 Unused FAS_RELEASE ------------------------------------------------------------ This command releases access to a line, and it is the counterpart to the FAS_RESERVE command. A FAS_RELEASE is issued by the host after it is through using a line. For an explanation of the Reserve/Release procedure, see the FAS_RESERVE command description. Request Format Offset Function 0 Command Opcode (0EH) 1 Line Number 2-7 Unused Response Format Offset Function 0 Command Opcode (0EH) 1 Line Number 2 Status 3-7 Unused FAS_RESERVE ------------------------------------------------------------ FAS_RESERVE reserves a line for a given host. This command is necessary only in an environment where two or more hosts share the services of a scsiServer on the same SCSI bus. This command serves to provide exclusion at the individual line level. NOTE: There is no relationship between FAS_RESERVE and FAS_RELEASE and the SCSI Reserve and SCSI Release commands. A response will not be returned until the host has been granted access to the specified line or until a FAS_RELEASE is issued to cancel the Reserve request. Unless a response has been returned, no commands (except for FAS_RELEASE) should be issued to a line after FAS_RESERVE. Request Format Offset Function 0 Command Opcode (0DH) 1 Line Number 2-7 Unused Response Format Offset Function 0 Command Opcode (0DH) 1 Line Number 2 Status 3-7 Unused FAS_SEND ------------------------------------------------------------ FAS_SEND carries outgoing data that is bound for a line. The data portion immediately follows the 8-byte command block within the SCSI Send Message data packet. Only one FAS_SEND command can be in progress at a time. The response must be returned before another FAS_SEND can be issued. This serves to provide flow control between the host and the FAS firmware. If the number of characters buffered at that line exceeds the high watermark (set with the FAS_FLOW_CTL command), then the response to a FAS_SEND will be delayed until the character count drains to the low watermark. Request Format Offset Function 0 Command Opcode (03H) 1 Line Number 2-3 Byte Count 4-7 Unused Response Format Offset Function 0 Command Opcode (03H) 1 Line Number 2 Status 3-7 Unused The Byte Count field should be set to the length of the accompanying data portion. This count can be any non-zero value within the limits of the total overall packet size of 2048. FAS_SEND_BRK ------------------------------------------------------------ FAS_SEND_BRK is used to initiate a break condition on a line. It will generate a 250ms or greater break indication, returning a response after the break condition is released. Only one FAS_SEND_BRK can be in progress at a time per line. If the line is actually a parallel port, this command is ignored. Request Format Offset Function 0 Command Opcode (0AH) 1 Line Number 2-7 Unused Response Format Offset Function 0 Command Opcode (0AH) 1 Line Number 2 Status 3-7 Unused FAS_SET_MODEM ------------------------------------------------------------ FAS_SET_MODEM provides explicit control over the RS-232 control outputs, commonly referred to as modem control signals. When a line is initialized via FAS_ENABLE, modem control signals are driven inactive. If the line is actually a parallel port, this command is ignored. Request Format Offset Function 0 Command Opcode (08H) 1 Line Number 2 RTS Control 3 DTR Control 4-7 Unused Response Format Offset Function 0 Command Opcode (08H) 1 Line Number 2 Status 3-7 Unused Both the RTS Control and DTR Control fields accept the same commands: Value Meaning 0 No change 1 Assert 2 Release FAS_SET_PARAMS ------------------------------------------------------------ FAS_SET_PARAMS allows the host to individually configure each channel's transfer parameters and provides control over serial line characteristics. It allows the baud rate, the number of bits per character, parity options, and the number of stop bits to be specified. In addition, the receiver may be selectively enabled and a diagnostic loopback mode can be enabled. If the line is actually a parallel port, this command is ignored. Request Format Offset Function 0 Command Opcode (0BH) 1 Line Number 2 Bits per Character 3 Framing 4 Parity Options 5 Flags 6 Baud Rate 7 Unused Response Format Offset Function 0 Command Opcode (0BH) 1 Line Number 2 Status 3-7 Unused The Bits per Character field is coded as follows: Value Bits Per Character 0 5 1 6 2 7 3 8 The Framing field sets the number of stop bits and is coded as follows: Value Stop Bits 0 1 1 1.5 2 2 The Parity Options field is coded as follows: Value Parity Mode 0 No parity 1 Odd parity 2 Even parity The Flags field consists of bits flags that control the receiver and the special loopback diagnostic mode. The bit flags are defined as follows: Data BitsFunction 7 Loopback enabled (when set) 6-3Reserved 2-1Input stripping mode: Bit Bit Meaning 2 1 0 0 Characters are stripped to the size selected at the line. 0 1 No stripping. Characters are returned to the host exactly as read from the serial hardware. 1 0 Seven bit stripping. The high bit is masked before returning the character to the host. 1 1 Reserved. 0 Receiver enable (when set) The Baud Rate field consists of two nibbles. The lower nibble controls the output baud rate, and the upper nibble controls the input baud rate. The field is coded as follows: Data Function Bits 7-4 Input baud rate 3-0 Output baud rate Code (4 bits) Baud Rate 0H 75 1H 110 2H 150 3H 300 4H 600 5H 1200 6H 1800 7H 2000 8H 2400 9H 4800 AH 9600 BH 19200 CH 38400 DH 57600 FAS_STAT_CHG ------------------------------------------------------------ FAS_STAT_CHG allows the host to monitor the state of certain RS-232 control signals, also known as modem control signals. Request Format Offset Function 0 Command Opcode (09H) 1 Line Number 2 Flags 3-7 Unused Response Format Offset Function 0 Command Opcode (09H) 1 Line Number 2 Status 3 Flags 4-7 Unused The Flags field provides bit flags that indicate the signals the host is interested in monitoring. A response message will generally not be returned unless one of the signals of interest changes state. However, a bit flag is provided which indicates that an immediate response is desired. This would typically be used once, when the line was opened to determine the initial state of the signals. It might also be used to specifically check on the state of a signal which is not normally monitored. The Flags field for serial lines is defined as follows: Data Bit Function (when set) 7 Immediate response desired 6-4 Unused 3 Reserved 2 Monitor DCD 1 Monitor DSR 0 Monitor CTS If the line is a parallel port, the Flags field is defined as follows: Data Printer Bit Signal Function (when set) 7 -- Immediate response desired 6-4 -- Unused 3 PE Paper empty at printer 2 BSY Printer busy 1 ERR Error condition at printer 0 SEL Printer is on line The Flags field in the response message is identical, except the immediate response bit will never be set. If a FAS_STAT_CHG is pending when a line is disabled, it returns a response with an ERR_ABORTED status. Only one non-immediate FAS_STAT_CHG command should be pending at a time. However, any number of immediate mode FAS_STAT_CHG commands may be posted even while a non-immediate mode command is pending. This allows low overhead monitoring of the most important signals, while still permitting the occasional polling of less frequently used signals.