Equinox SuperSerial Driver for OS/2 ----------------------------------- INTRODUCTION ============ The driver accompanying this documentation is designed for use with the Equinox SuperSerial family of high-performance RS-232 boards within an OS/2 environment. The product line ranges from 2 ports per slot to 128 per slot. Target machines for this version is for (ISA {Plug & Play}, PCI,EISA or Micro Channel) computers. Target OS/2 versions include 1.2x, 1.3x, 2.0x, 3.0 Warp as well as Citrix Multiuser version 1.xx and Citrix A+ Server version 2.x. This driver contains several deviations from the async driver specification for OS/2 as published by IBM in "I/O Subsystems and Device Support, Volume 1". Most deviations involve the use of control signals. (Please refer to the following section.) This document attempts to document those differences. OVERVIEW ======== Equinox SuperSerial boards are unlike other multiport boards in that there are no UARTs being driven by a programmable microprocessor. Instead, a custom ASIC processor called the SSP (SuperSerial Communications Processor), handles a group of up to 64 channels. There is at least one SSP on every Equinox board. The SSP has the ability to receive and transmit data without processor involvement. All communication with the processor is via a memory buffer and a set of registers. The ability of the SSP to manage RS-232 lines with very little host processor involvement, ensures maximum throughput and efficiency at speeds up to 921,600 baud. INSTALLATION ============ ISA Systems ----------- A single Equinox board can be installed in any PC slot. Regardless of the number of boards installed, place the following line in CONFIG.SYS. DEVICE=C:\SST.SYS (assuming you place SST.SYS in C:\, however you may place it anywhere as long as the correct path is specified) If there are no parameters following "SST.SYS", the driver will attempt to map the board near the top of the 16 Megabyte address range of the AT bus. If you have 16 Meg of RAM installed in your system, the default will not work and you must inform SST.SYS where to load within the first Megabyte. Please read on to understand the memory requirements. Due to the capabilities of the SSP to manage the RS-232 channels, SuperSerial boards use no processor interrupts and therefore no IRQ's. SuperSerial does share a portion of the processor address space. The OS/2 driver requires 16k bytes for the board. This address space must contain no physical system RAM or devices such as video boards. To help locate unused RAM areas use the supplied utility MEGAMEM.EXE. When you run MEGAMEM from a DOS prompt, a "map" of the first Megabyte of RAM will be displayed. Some of the 16k blocks will typically be noted as "empty", meaning SuperSerial boards can be mapped at those locations. There is one "block" of RAM required for SuperSerial boards. The length is 16k and is used as a "window" into the on-board memory. This block of memory is similar in concept to an EMS page frame in DOS. To set the buffer location, add " /BUFFERS=xxxxxx" to the end of the "DEVICE=" statement in CONFIG.SYS. "xxxxxx" must be the hexadecimal representation of the origin of the block SST.SYS should use. One additional requirement: the address spaces for SuperSerial must NOT BE CACHED! If SuperSerial attempts to load in a region of cached memory, it will abort the install and OS/2 will report that "No SuperSerial boards found" and the driver will not install. You must determine an "empty" region of memory with the aid of MEGAMEM. Then you must add appropriate parameters to the "DEVICE=" line. For example, if "cc000", "d0000", "d4000", "d8000" and "dc000" are reported "empty" by MEGAMEM, you could use the following line: DEVICE=C:\SST.SYS /BUFFERS=D0000 If the driver reports "No SuperSerial boards found" and you are reasonably certain that there are no memory or cache conflicts, then you should check the I/O base address switch. PCI Systems ----------- A single Equinox SST board can be installed in any PCI slot. The parameter "/BUFFER=XXXXX" is not needed for PCI based boards, the memory information is determined by PCI. EISA Systems ------------ A single Equinox board can be installed in any PC slot. The parameter "/BUFFER=xxxxx" is not needed for EISA based boards, since all memory information is read from CMOS. This requires that the EISA configuration has been performed. If this step is not done the board will be ignored. Micro Channel Systems --------------------- A single Equinox board can be installed in any PC slot. The parameter "/BUFFER=xxxxx" is not needed for Micro Channel based boards, since all memory information is read from CMOS. This requires that the Micro Channel Setup has been performed. If this step is not done the board will be ignored. Write Time outs =============== By default, Equinox devices are designed to handle data as defined by the O/S 2 I/O designed specification. Specifically, data writes to our devices can potentially timeout if the system has configured the device to do so. The OS/2 spool facilities configure serial devices to timeout after some duration( limited from 10 milliseconds to 11 minutes). Recent observations were made which uncover the following problem. We configured a Relisys TR-170 terminal and created a queue to redirect print jobs to the transparent printer. We discovered that if the printer was placed off line for more than five minutes, part or all of the print job would be lost. The problem turned out to be "write time outs". For this particular configuration, the timeout value was set for approximately 5 minutes. The following command line option is provided to remedy this. /TIMEOFF This flag disables timeouts on writes. This flag may fix problems caused when printers are out of paper for a very long time or other extended flow control states. Optional Port Naming ==================== By default the Port names are the following: EQN001 - first port on the first board . EQN064 - last port on the first board (64 port board) The user can override the default port name, by using the following command line: /NAME=ccccc:nnn where ccccc = up 5 character name is given followed by an optional colon ":" and a numeric port base if no numeric number is given the first port starts a 1 Example (1) /NAME=COM The first port will start at COM1 Example (2) /NAME=:3 The first port will be EQN3 Example (3) /NAME=XYZ:003 The first port wll be XYZ003 (note: 2 leading zeros) Example (4) /NAME=XYZ:03 The first port wll be XYZ03 (note: 1 leading zeros) ACCESSING THE PORTS - OS/2 Equinox ports install as a contiguous block of ports ranging from "EQN001" for the lowest port on the first board to "EQNxxx" where xxx is the last port on the board. EQN001 - first port on the first board . EQN064 - last port on the first board (64 port board) Once you have set the baud, parity, etc., you may... * use any OS/2 command, utility or redirection function to send/receive data to/from the port * perform normal file I/O on the "EQNxxx" device names from an OS/2 program you write * perform device IOCtl calls from any program you write This driver does NOT support "DOS box" utilization. You may only access EQN ports from OS/2 software. Use of the "DOS box" in no way interferes with the operation of OS/2 software. ACCESSING THE PORTS - Citrix A+ Server ====================================== With Citrix, follow the steps under "Installation" above. Additionally, you must inform Citrix that terminals are attached to particular "EQNxxx" device names. 1) first copy EQXSST.SSB to c:\sysctx\term (System must be in Maint Mode.) 2) config the new subsystem (EQXSST) config at the os/2 prompt select number 2 (Terminals) select profile select add subsystem select Equninox SuperSerial Technology 3) config devices under this subsystem Refer to the Citrix "System Administrator's Guide" for details. For Citrix A+ Server version 2.01 and later, the Equinox ports appear as a "subsystem". Simply select a port from the displayed list of Equinox ports. (In earlier versions, Citrix categorizes the Equinox driver under the title "async device driver", not as a "subsystem".) Hints for Citrix terminal configuration. ****** Recommendation: Use inband flow control (xon/xoff/xpc) for all terminals. This allows DTR from the terminal to function as the connect/disconnect signal to Citrix. When configured in this way, the terminal session is "secure". If the terminal is turned off, the session will be suspended until the terminal is turned on. The new user will have to enter (re-enter) his password to resume any previous session. ***) To use inband flow control (xon/xoff/xpc) with a control signal, use 6-wire accessories and specify: Connection Type: Connect on DSR Flow Control: XON/XOFF transmit enable RTS/CTS enable DTR/DSR enable XPC Protocol (only for original version) This is the terminal default for Citrix! You should use 10-wire accessories for full modem control. Use the Citrix defaults listed above. If you wish to use 8-wire accessories, you must turn off "Connect on DSR" and turn on "Connect on DCD". (This is required so that the "RTS/CTS" pair is available for hardware flow control with high-speed modems.) Connection Type: Connect on first character Disconnect on break Flow Control: RTS/CTS enable DTR/DSR enable DSR output handshaking ***) To use a high-speed modem with Equinox 8-wire accessories, specify: Connection Type: Connect on DCD Flow Control: XON/XOFF transmit enable RTS/CTS enable DTR/DSR enable CTS output handshaking CURRENT LIMITATIONS ==================== This version of the driver supports only one board. The host adapter cable must be attached to the SuperSerial SST-64I or SST-128I or SST-64E or SST-128E or SST-64M or SST-128M board, as well as to the required Port Modules prior to loading the driver. Note: A one-to-one replacement of Port Modules is supported after the driver has been loaded. if additional Port Modules are required you must reboot the system. SST-128X - Port Modules must be cable in proper order, first to the lower host adapter (see hardware manual). This driver does NOT support "DOS box" implementation of OS/2 version 1.x. You may only access EQN ports from OS/2 software. While the EQN ports may not be used by DOS software, use of the "DOS box" in no way interferes with the operation of OS/2 software. "Break replacement" is not implemented as a programmable character. Normally a "null" character is present in the buffer at the location of the break. "Break detection" works correctly. You may use "disconnect on break" with Citrix. Error detection and replacement is not implemented but OS/2 is notified if a parity error occurs. (Parity errors are not reported for "mark" parity.) Buffer overflow is not returned as a comm event. Certain terminals have very small input buffers which can be "overrun" if the computer does not stop sending characters soon enough after the xoff character OR the control signal is dropped. ** The Wyse-60 terminal will be overrun if DTR flow control is enabled AND the data rate is 38400. To use a Wyse-60 at 38400 you must configure it for "XON/XOFF" AND "XPC protocol" both in the terminal and in Citrix. ** Wyse-150 and Wyse-160 can be overrun under extreme conditions if DTR flow control is enabled. If the data rate is 38400 and if data is being continuously output during a Citrix session switch, overrun will eventually occur. Messages ========= Normal Messages ================ Equinox Systems - SuperSerial OS/2 driver [xxx.xx] installed. In an ISA System In an EISA System In a Micro Channel System Serial devices EQN001 through EQNXXX are available. Equinox SuperSerial DRAM memory Test Ok! Equinox SuperSerial PRAM memory range Test Ok! Equinox SuperSerial PRAM memory Test Ok! Error Messages =============== Equinox Systems - SuperSerial OS/2 driver [xxx.xx] NOT installed. In an Unknown System Type *Error* 1, A memory conflict has been detected. The reason is: *Error* 2, The memory ranges used by the board are in use by another device, *Error* 3, The memory ranges used by the board are being hardware cached. *Error* 4, Equinox SuperSerial EISA board in slot( xx), ignored. Invalid EISA configuration. *Error* 5, No channels Found, Check Port Module/Adapter Cable, for board in slot/port xxxx *Error* 6, Equinox SuperSerial Micro Channel board in slot( ), ignored. Invalid Micro Channel configuration. *Error* 7, No SuperSerial boards were found. *Error* 8, Equinox SSP DRAM memory test failure page(xxx) offset(xxx) *Error* 9, PRAM memory range appears to be cached. SSP(x) *Error* 10, Equinox PRAM memory test failure. SSP(x) .