3/2/94 -- INSTALL.DOC--xall.sys V1.4.6 6400 Flying Cloud Drive Eden Prairie, MN 55344 (612) 943-9020 DigiBoard, GmbH Schmittgasse 64 5000 Cologne 90 Germany 49-2203-81083 Installation Guide Reference Manual for Universal OS/2 Device Driver for DigiCHANNEL Intelligent Communications Boards 92000100C DigiBoard, DigiCHANNEL, PC/Xi, PC/16i, PC/8i, PC/Xe, PC/16e, PC/8e, PC/4e, PC/2e, Xem, PC/Xem, MC/Xem, EISA/Xem, COM/Xi, COM/8i, COM/4i, MC/Xi, MC/16i, MC/8i, MC/4i and C/X are trademarks of DigiBoard. All other brand and product names are the trademarks of their respective holders. Digi International, Inc. All Rights Reserved Information in this document is subject to change without notice and does not represent a commitment on the part of DigiBoard. DigiBoard provides this document as is, without warranty of any kind, either expressed or implied, including, but not limited to, the particular purpose. DigiBoard may make improvements and/or changes in this manual or in the product(s) and/or the program(s) described in this manual at any time. This product could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes may be incorporated in new editions of the publication. RESTRICTED RIGHTS: For non-U. S. Government use: These programs are supplied under a license. They may be used, disclosed, and/or copied only as permitted under such license agreement. Any copy must contain the above copyright notice and this restricted rights notice. Use, copying, and/or disclosure of the programs is strictly prohibited unless otherwise provided in the license agreement. For U.S. Government use: Use, duplication, or disclosure by the Government is subject to restrictions as set forth in sub-paragraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause of DFARS 52.227-7013. Table of Contents 3 Introduction 4 The Distribution Diskette 6 Installing the Device Driver 7 Global Parameters 7 Per-Card Parameters 10 Examples 13 Testing the Ports 15 Troubleshooting 16 Error Messages 18 DMODE I/O Port Configuration Utility 19 Examples 23 Appendix Synchronous Communications Modes 25 Introduction This release of the DigiWARE device driver for OS/2 supports the entire line of DigiCHANNEL intelligent asynchronous serial communications controllers: Micro Channel (MCA) bus: DigiCHANNEL MC/Xi 4, 8 and 16 port boards DigiCHANNEL MC C/X cluster controller system DigiCHANNEL MC/Xem PC/AT (ISA) bus: DigiCHANNEL PC/Xe 2, 4, 8 and 16 port boards DigiCHANNEL PC/Xi 8 and 16 port boards DigiCHANNEL COM/Xi 4 and 8 port boards DigiCHANNEL ISA C/X cluster controller system DigiCHANNEL PC/Xem EISA bus: DigiCHANNEL EISA C/X cluster controller system DigiCHANNEL EISA/Xem The device driver software supports multiple boards and multiple board types in a single machine, and can handle up to 256 ports from any combination of the boards listed above. As new products are introduced, the driver will be upgraded to include those devices as well. The driver takes all its configuration information from the device= command line in CONFIG.SYS, and all DigiCHANNEL intelligent boards in a system are configured from a single command line. In addition to the device driver, the configuration utility DMODE.EXE is provided to change communication parameters for individual ports without rebooting. DMODE.EXE is similar to the OS/2 MODE command, but has some added features, and supports communications devices beyond OS/2s range of COM1 to COM8. Before installing this device driver software, complete the installation of the DigiCHANNEL intelligent communications board(s) in your system, according to the hardware installation manual provided with the board(s), and write down your configuration! The driver supports all legal I/O and memory address settings, but must be informed of these settings in the device driver command line. The Distribution Diskette The diskette accompanying this manual contains all of the files and documentation needed to install the DigiWARE OS/2 Universal Intelligent Device Driver in your system. A list of these files follows: XALL.SYS The installable device driver. DMODE.EXE A MODE work-alike program for configuring I/O ports beyond COM8 INSTALL.DOC Installation instructions for the current release of the driver. RELNOTES.DOC Release notes. DMODE.DOC Instructions for the DMODE program. XALL.DOC Programmers information about the driver and applicable system calls. DGOS2UD.EXE User Diagnostics. *.bin Miscellaneous binary files used by the driver. Installing the Device Driver Copy all of the files from the distribution diskette to a single directory on your hard drive. By default, driver and data files are expected to be in \DIGI. The device driver is invoked by placing its name and configuration arguments into the systems CONFIG.SYS file. All DigiCHANNEL intelligent asynchronous serial communications boards must be installed from a single command line, which contains complete set-up information for each board. The format of the command line is: device=\digi\xall.sys [/n:names] [/b:baud] [/d:dtype] [/f:digipath] [/v:messagepath] /t:card /p:port /m:mem [, /t:card /p:port /m:mem] [, ...] Note that the path for XALL.SYS is \DIGI. This is the default path. If an alternative path is specified with the /f:digipath option, substitute that path for \DIGI. The above command line must appear on a single command line in the CONFIG.SYS file. This line may be up to 255 characters long. Global Parameters The first six parameters in the command line above are global parameters, and affect all boards installed. These parameters are optional, and may be omitted. If omitted, default values will be used. /n:names Defines the naming convention to be use for the DigiCHANNEL ports. names consists of an optional stem followed by the starting device number. The new stem must be enclosed in double-quotes (""). If the stem is omitted, COM will be used. If the number is omitted, 3 will be assumed. If the /n parameter is not specified, the default name COM3 will be assigned to the first port. /n:"digi"0 DIGI0, DIGI1, DIGI2, ... DIGIn /n:4 COM4, COM5, COM6, ... COMn /n:"qdev" QDEV3, QDEV4, QDEV5, ... QDEVn /b:baud Sets the default baud rate to be used for all ports. If this parameter is not specified, all ports will be set to the OS/2 default of 1200 baud. Baud rates of up to 38,400 are supported. Use the DMODE.EXE command to set baud rates of individual ports. /b:9600 Initializes all ports to 9600 baud. /d:dtype Sets the initial data type (parity, character length and number of stop bits). If this parameter is omitted, the OS/2 default data type of even parity, 7 data bits and 1 stop bit is used. The syntax is [pds], where p is E, O or N; d is 8, 7, 6 or 5; and s is 1 or 2. All three values must be supplied, in the correct order. /d:N81 No parity, 8 data bits, 1 stop bit. /d:m Displays debug messages to the screen or disk file during driver load to facilitate troubleshooting driver load problems. /f:digipath Defines an alternative directory path for the driver and data files. If this option is present, all files from the distribution diskette must be present in this directory. /f:d:\drvr\digi All data files are in D:\DRVR\DIGI. /v:messagefile Forces the driver to direct all verbose messages to the file named. If /v: is given without a filename, messages will be placed in \XALL.MSG. This flag prevents any information from being displayed on the console; useful in some situations as when the machine is a headless server, where calls to Standard Output will cause problems. Without this flag, all messages will appear on the system console. The message file is overwritten each time the system is started. /v:errmsg Writes banner and other info to file \ERRMSG. /v: Writes banner and other info to file \XALL.MSG. /a:a Enable the alternate pin assignment of Data Carrier Detect (DCD) for all ports (see discussion of Alt-Pin processing. Per-Card Parameters The remaining three parameters are per-card parameters, and are used to inform the driver of the type of board and where it is to be addressed in the hosts I/O and memory buses. These parameters are mandatory, and must be given for each board! The per-card parameters must be given in complete sets, and the sets must be separated by commas. /t:card Defines the card type to the driver. Legal values for card are: i for the ISA C/X, e for the EISA C/X, m for the MC C/X, p for Xem (PC/Xem, MC/Xem or EISA/Xem) x for COM/Xi boards. This parameter must be omitted for PC/Xe, PC/Xi and MC/Xi boards. The designators i, e, and m must be followed by an additional two digits defining the number and arrangement of DigiCHANNEL C/CON-16 or C/CON-16e concentrators on each host adapter channel. If the concentrator(s) are connected to the host adapter via a dial-up or leased line (remote concentrators), each of the two digits must be followed by a parameter, enclosed in parentheses, specifying the synchronous communications mode to be used for that line. See the Appendix for a list of available synchronous communications modes. /t:i10 ISA C/X, one local concentrator on line 1 only. /t:e11 EISA C/X, one local concentrator on each of lines 1 and 2. /t:m21 MC C/X, two local concentrators on line 1 and 1 on line 2. /t:e12 EISA C/X, one local concentrator on line 1, and two on line 2. /t:i22 ISA C/X, two local concentrators on each of lines 1 and 2. /t:i2(21)3(27) ISA C/X, two remote concentrators on line 1, and two remote concentrators on line 2. The concentrators on line 1 will use mode #21 (76,800 baud, 8-wire, external clock) to communicate with the host adapter, and the concentrators on line 2 will use mode #27 (614,400 baud, 8-wire, internal clock). See the Appendix for a list of synchronous communications modes. /t:x COM/Xi (4 or 8 channels) /t:p PC/Xem, MC/Xem or EISA Xem /t:u This switch forces the driver to accept the computer as a PS/2 MicroChannel. /p:port Defines the I/O port address for the card. /p:300 Board is addressed at I/O port 300h. /p:2005 EISA board (EISA C/X or EISA/Xem host adapter) is in slot 2 (EISA I/O addresses are 4 digits : the slot number, followed by 005). When plugging an ISA board (PC/Xe, ISA C/X host adapter, etc.) into an EISA machine, the /p parameter must contain the 3-digit I/O address as set by the DIP switches on the board, and not the 4-digit address based on the EISA slot number. /m:mem Dual-ported memory starting address. This is the full 32-bit hexadecimal address of the beginning of the boards dual-ported memory. /m:d0000 Sets dual-ported memory start address to 0D0000h (in the BIOS expansion area between 640K and 1 megabyte). /m:e80000 Sets start address of E80000h (in the fifteenth megabyte). EISA and ISA boards (except the COM/Xi), may all share the same memory starting address. COM/Xi and all Micro Channel boards must each have unique memory addresses. Examples The following examples start out with just the minimum to install a DigiCHANNEL board. After locating an example for your type of board, read the rest of the examples for optional situations that may be appropriate to your application. Default options will be altered by your application program(s) when you configure the application. -------- Example 1: COM/Xi One COM/Xi at I/O port 300h, memory start address D8000h; devices to be named COM5 COM6, etc. All data files are in the directory \DIGI: device=c:\digi\xall.sys /n:5 /p:300 /m:d8000 /t:x (Note that the above must all appear on one line in CONFIG.SYS) -------- Example 2: PC/Xe, PC/Xi One PC/Xe (or PC/Xi) at I/O port 220h, memory address D0000h Ports will be named COM3, COM4, etc. (default names). All data files are in the directory \MISC\DIGI: device=c:\misc\digi\xall.sys /f:\misc\digi /p:220 /m:d0000 (Note that the above must all appear on one line in CONFIG.SYS) -------- Example 3: MC/Xi One MC/Xi at I/O port F1F0h, memory address FC0000h. Devices will be named DIGI1, DIGI2, etc. and will have an initial baud rate of 38,400. All data files are in the default directory \DIGI: device=c:\digi\xall.sys /n:"digi"1 /b:38400 /p:F1F0 /m:FC0000 (Note that the above must all appear on one line in CONFIG.SYS) -------- Example 4: Two board installation with optional global parameters. Two PC/Xi (or PC/Xe) boards at I/O ports 320h and 300h, with dual-ported memory of both starting at D0000h. Ports will be named COM0, COM1, etc., and will be initialized to 38,400 baud, no parity, 8 data bits and 1 stop bit; messages will be contained in the file MESSAGES.MSG located in the \DIGI directory. All data files are in the default directory \DIGI: device=c:\digi\xall.sys /n:0 /b:38400 /v:\digi\messages.msg /d:N81 /p:320 /m:D0000, /p:300 /m:D0000 (Note that the above must all appear on one line in CONFIG.SYS) --------- Example 5: PC/Xem One PC/Xem at I/O port 224h, memory start address C8000h; devices to be named COM3 COM4, etc. All data files are in the default directory \DIGI: device=c:\digi\xall.sys /p:224 /m:C8000 /t:p (Note that the above must all appear on one line in CONFIG.SYS) --------- Example 6: ISA C/X One ISA C/X host adapter at I/O port 228h, memory address D0000h, with one concentrator on line 1 and two on line 2. Devices to be named DCX1, DCX2, etc. and will have an initial baud rate of 38,400. All data files are in the default directory \DIGI: device=c:\digi\xall.sys /n:"dcx"1 /b:38400 /p:228 /m:d0000 /t:i12 (Note that the above must all appear on one line in CONFIG.SYS) ----------- Example 7: EISA C/X with a remote concentrator via an RS-232 synchronous modem. One EISA C/X host adapter in slot 3, memory address D8000h, with two local concentrators on line 1 and one remote concentrator at 9600 baud and external clocking on line 2. Devices to be named COM5, COM6, etc. and will have an initial baud rate of 19,200. All data files are in the directory \OS2\DIGI: device=c:\os2\digi\xall.sys /n:5 /b:19200 /f:c:\os2\digi /p:3005 /m:d8000 /t:e21(17) (Note that the above must all appear on one line in CONFIG.SYS) ---------- Example 8: MC C/X and MC/Xem One MC C/X host adapter at I/O port 228h, memory address D8000h, with one concentrator on line 1 and one concentrator on line 2; one MC/Xem at I/O Port 304h, memory address D0000h. Devices will be named DIGI1, DIGI2, etc. and will have an initial baud rate of 38,400, Alt-Pin enabled, no parity, 8 data bits, and 1 stop bit. All data files are in the default directory \DIGI: device=c:\digi\xall.sys /n:"digi"1 /b:38400 /a:a /d:N81 /p:228 /m:d8000 /t:m11, /p:304 /m:d0000 /t:p (Note that the above must all appear on one line in CONFIG.SYS) (Note that for MC C/X and MC/Xem, the addresses 104 and 108 should not be used to avoid possible conflicts) ---------- ---------- Testing the Ports The simplest (and probably the best) way to check the driver and I/O connections is to connect an ASCII terminal to one of the ports and redirect some output to that port. If the terminal is connected to COM3, try something like the following: dmode com3 (this will verify that the driver can find the portthe ports parameters will be displayed.) dmode com3 octs=off odsr=off (this insures that the hardware handshaking signals CTS and DSR will not prevent outputwe are not concerned with flow control at this time.) dir > com3 (this redirects the current directory to COM3.) The console should simply respond by repeating the C:\> prompt, and the current directory (in this case, C:\) will appear on the terminal. Troubleshooting If the C:\> prompt doesn't reappear, and the system seems to be hung, you probably used a memory start address that is being used by some other device, or the board is not set for the address specified in CONFIG.SYS. Try a different address. If it still hangs, try a different I/O port. If your computer has a memory cache and the boards memory start address is above 1 megabyte, try either disabling the cache or moving the board to a low-memory address (D0000 is usually a good choice). It is also possible that a conflict exists with another device driver which has been loaded via CONFIG.SYS. The XALL.SYS line should be placed near the end of the CONFIG.SYS, and must not be placed before the DEVICE=TESTCFG.SYS line. Due to potential device naming conflicts, the pair of lines DEVICE=\OS2\COM.SYS and DEVICE=\OS2\VCOM.SYS may cause problems. Be sure that the XALL.SYS line is placed before these lines in CONFIG.SYS. If the XALL.SYS driver generates an error message, try temporarily putting REM in front of the above two lines. If this works, there is probably a naming conflict. You may need to add a /n: command line flag to the XALL.SYS line to force the driver to use a different base name or start numbering the COM devices at 5 or above. If the C:\> prompt does reappear, but there is no output on the terminal screen, there is probably a cabling problem. Make sure that all cable plugs are securely seated in receptacles, and that they are configured correctly (see the appropriate section of the hardware installation guide for your board). If the terminal displays output, but the data on the screen is garbled, the terminal is probably not set with the same baud rate and data type as specified in CONFIG.SYS (or the defaults, if not specified). Verify these settings. If everything checks out and you still have problems, there could be a problem with your board. Contact your distributor or DigiBoard Technical Support for further assistance. Error Messages If, when the driver is loaded, it cannot find the board(s), or if they fail to respond properly to commands, certain error messages may be sent to the console. These error messages are defined in the following table: Could not find BIOS file Could not find FEP file Could not find data file One or more files were missing from the digipath directory. The default digipath directory is /digi. If you have loaded the driver and data files into a different directory, that directory must be specified in the xall command line with the /f:digipath parameter. IO Port Not Responding I/O port address set incorrectly, or conflicting with some other device. Verify setting, or try a different address. DigiBoard BIOS Will Not Boot DigiBoard BIOS Will Not Respond DigiBoard FEPOS Will Not DigiCHANNEL board will not respond to commands from the driver. Typically due to a memory conflict, or a memory cache conflict. Driver Failed to Hook Timer System Cannot Allocate Memory A system call to OS/2 has failed. Invalid Command Line Arguments Syntax error in the command line in CONFIG.SYS. Double-check your entries. ======== DMODE I/O Port Configuration Utility DMODE is DigiBoards I/O channel configuration utility. DMODE functions like the OS/2 MODE command, but is more flexible, and provides some added features. -Supports communications device names other than COM1-COM8. -Any single parameter may be changed without causing all others to be reset to default values. -Can be used to enable or disable the Alt-Pin feature on individual ports. -Maintains the familiar MODE syntax. DMODE arguments may be entered in any order, and in many cases may be abbreviated. For example, a baud rate of 19,200 may be entered simply as 19, since within the context of the DMODE command, 19 cannot be interpreted as anything else. Arguments may be separated by spaces or commas, and unspecified parameters are left unchanged. DMODE returns the settings of all parameters after any requested changes have been made. If no parameters are given, DMODE simply returns the current settings. The syntax of DMODE is: dmode port_name [parameters] Port names and parameters are not case sensitive, so upper and lower case letters may be freely mixed without effect on the operation of the DMODE command. The following parameters are accepted: Baud Rate Baud rates can be specified with 2 to 5 digit designations, according to the following table: Accepted Values Baud Rate 11 110 110 15 150 150 30 300 300 60 600 600 12 120 1200 1200 24 240 2400 2400 48 480 4800 4800 96 960 9600 9600 19 192 1920 19200 19200 38 384 3840 38400 38400 56 567 5670 56700 56700 Character Length Characters may be 5, 6, 7 or 8 bits long. Enter the appropriate number in the DMODE arguments. Parity: Enter the desired parity checking method with a single letter E, O, N, M or S for Even, Odd, None, Mark or Space, respectively. Stop Bits: Enter the desired number of stop bits. Recognized values are 1, 2 and 1.5. Flags : DMODE supports the following flags in the same way as the OS/2 MODE command. Refer to your OS/2 documentation for explanations of the flags. To set a flag, enter the mnemonic for the flag, followed by an equals sign (=), and the desired value (ON, OFF, etc.). TO=ON Write timeout in effect. TO=OFF No timeout (infinite write timeout) XON=ON XON/XOFF handshaking enabled. XON=OFF XON/XOFF handshaking disabled. IDSR=ON Enables Input DSR Sensitivity. IDSR=OFF Disables Input DSR Sensitivity. ODSR=ON Enables Output DSR Sensitivity. ODSR=OFF Disables Output DSR Sensitivity. OCTS=ON Enables CTS output flow control. OCTS=OFF Disables CTS output flow control. DTR=ON Sets DTR to ON or HIGH. DTR=OFF Sets DTR to OFF or LOW. DTR=HS DTR used for input flow control. RTS Signal Control RTS=ON Sets RTS to ON or HIGH. RTS=OFF Sets RTS to OFF or LOW. RTS=HS RTS used for input flow control. RTS=TOG Toggles RTS on every transmit request. (Not supported) ALT=ON Internally swaps DSR and DCD signals (see explanation below). ALT=OFF DSR and DCD are not swapped. DigiCHANNEL products use 10-pin RJ-45 connectors in order to support all of the signals normally available on a 9-wire RS-232 connection. However, many commercially available RJ-45 connectors have only 8 pins. 8-pin RJ-45 plugs will fit in a 10-pin jack, but the first and last pins (numbers 1 and 10) are not connected. DigiBoard uses these pins for the modem control signals RI (Ring Indicator, pin 1) and DCD (Data Carrier Detect, pin 10). While Ring Indicator is rarely a concern (since most modems have auto-answer capability), Data Carrier Detect is often monitored to insure that the modem has established, and is maintaining, a valid connection with a remote modem. To facilitate the use of 8-pin RJ-45 connectors in modem applications, a special DMODE flag, ALT, has been provided. ALT instructs the device driver to monitor pin 1 of an 8-pin RJ-45 for DCD. See the Hardware Installation guide for your board for cabling diagrams and pin assignment charts for DB-25 and RJ-45 connectors. Examples dmode digi12 (Returns the current settings of device digi12. No changes are made.) dmode com5 2 (Configures COM5 for 2 stop bits. All other parameters remain unaffected.) dmode com5:38 rts=on (Configures COM5 for a baud rate of 38,400 and sets RTS to ON or HIGH.) dmode com5 8 (Configures COM5 for 8 data bits. No other parameters are affected. ) dmode comdv83 idsr=off, to=off e 7 12 (Sets COMDV83 to disable Input DSR Sensitivity, disable output timeout, select even parity, 7 data bits and a baud rate of 1200. ) dmode com5 38 alt=on (Sets up COM5 for a baud rate of 38,400, and enables Alt-Pin Processing.) dmode com5 e alt=off (Sets COM5 for even parity checking and disables Alt-Pin processing.) dmode com3 odsr=off octs=off (Disables sensing of output flow control signals Clear To Send (CTS) and Data Set Ready (DSR). ) =========== Appendix Synchronous Communications Modes The DigiCHANNEL C/X host adapter communicates with attached C/CON-16 concentrators via two RS-422 synchronous channels (newer concentrators and host adapters also support RS-232 synchronous communicationsee your hardware Installation Guide). The default operating mode for these channels is 1.2 megabaud, 8-wire, internally clocked. This provides the fastest possible communication between the host adapter and locally connected concentrators (in this context, local indicates that concentrators are connected directly, via a 4 or 8 wire cable, to the host adapter; remote refers to concentrators that are connected to the host adapter via data communications devices such as modems or DSUs). Local concentrators always communicate with the host adapter in either an eight wire internally clocked mode or a four wire self-clocked mode (in the four wire modes the clock is encoded with the data instead of being carried on separate lines as in the eight wire modes). Remote concentrators always use an eight wire externally clocked mode (the clock signal is provided by the synchronous modem). The table on the following page shows the modes that are supported by the XALL.SYS device driver. Note that the external clock baud rates are approximates used to set up time-outs and tuning parameters only. Values do not need to be exact; select the speed closest to the actual sped of your synchronous modem.