TCL Card Driver for Linux V2.4.2, 2.4.7 & 2.4.7-10 ============================================================================== Contents ======== 1. Introduction 2. Installing the Linux Driver 3. Removing the Linux Driver 4. Loading and Unloading the Linux driver 5. Driver Log File 6. Device Naming Conventions 7. Using TCL Ports with Terminals 8. Using the TCL Ports to Dial Out 9. The Driver Configuration File 9.1 Configuration File Syntax 9.2 The SETCARD Paragraph 9.3 The SETPORT Paragraph 9.4 Allocating Buffers using a Configuration File 9.5 Configuration File Problems 10. Warning Messages 11. Driver Disk Contents 12. Driver Files 13. Driver Release Notes 14. To Contact TCL 1. Introduction =============== The TCL Intelligent range of multiport serial I/O adapters provide high speed asynchronous communications. Up to eight of these adapter cards may be installed in a PC which allows up to 256 TCL ports in a single Linux system. The TCL serial ports can be used in the same way as the standard serial ports, so for instance they can be used to attach terminals to the system, for dialling out to the internet using modems, or they can be used for raw serial I/O. The TCL hardware is extremely easy to install. The installation for a PCI card consists simply of plugging it into a free slot on the PCI bus. The Linux driver installation is equally simple and is described in the next section. 2. Installing the Linux Driver ============================== The recommended installation procedure is as follows : NOTE: The device name and mount point name for the floppy drive may not be the same in all systems. - Log in as root. - Insert the driver disk into the floppy drive. - Mount the drive : # mount /dev/fd0 - Change directory to the mount point for the floppy drive : # cd /mnt/floppy - Run the setup script on the driver disk. This installs the driver using the Red Hat Package Manager : # tclsetup - The driver should now be installed. If the installation is successful, the driver documentation will be in directory /usr/doc/tcldrv-1.6.3 and the driver is loaded if the option was selected during installation. 3. Removing the Linux Driver ============================ The driver can be removed from the system by running the driver removal script on the driver disk. This unloads the driver and removes the driver files using the Red Hat Package Manager : # tclremove Note that once installed, the driver must be removed first (using the tclremove script) before it can be reinstalled. 4. Loading and Unloading the Linux driver ========================================= When the driver is installed, the system is set up to load the driver automatically when the system boots. The driver would normally stay loaded until the system is rebooted. However, the driver can also be loaded or unloaded manually using the tclload script which is installed with the driver. During installation, a sybolic link is made to the tclload script in the /usr/bin directory, which should be in the default path. Therefore the tclload script can be invoked without having to specify the path. The usage of the command is as follows : tclload [ start | stop ] tclload Loads the TCL driver. If tclload is used without the start or stop parameter and the driver is already loaded, the user is asked whether or not to reload the driver. Note that if any of the ports are open when tclload attempts to unload the driver, then the driver will not be unloaded. This may happen for instance if any of the TCL ports have an entry in /etc/inittab so they can be used as dial-in ports. tclload start This loads the driver. If the driver is already loaded, tclload attempts to unload and then reload the driver without prompting the user. tclload stop This attempts to unload the driver. NOTE: The driver can be loaded and unloaded from the command line using insmod and rmmod commands. However, use of the tclload script is strongly recommended as this ensures that the device nodes in the /dev directory are set up correctly. 5. Driver Log File ================== When the driver is loaded, a log file /var/log/tcl.log is created. This can be used to identify problems with the driver. It also contains other information which may be useful, such as the driver version and the major and minor numbers of the TCL devices. As an example where the log file can be used to solve a problem, the following log file indicates that the external box of a Superport-186 system is not connected: # cat /var/log/tcl.log Merlin gateway is minor device 63 of misc (major 10) TCL modem device major number is 148 TCL callout device major number is 149 TCL intelligent card driver loaded OK TCL Serial Driver V1.6.3 File open failed for /usr/bin/tcldrv/tclcf.ini Found Protected Mode PCI BIOS Card=1 Type=DataPump-4 FoundPorts=4 Addr=0xC8000 Wind=4K Mem=128K ConfiguredPorts=4 ExecName=/usr/bin/tcldrv/tcl186.sys ExecVer=5.3.28 [card:2] WARNING: External interface box not connected to the card! Superport-186 card will not be loaded. Card=2 Addr=0xE0800000 State=FOUND PCI Slot 2 4 ports configured (num_ports) Note that the line "File open failed for /usr/bin/tcldrv/tclcf.ini" does not usually indicate a problem. It just means that the driver couldn't find the optional driver configuration file tclcf.ini. In most situations, this file is not required. Whilst the driver is loaded, similar information is maintained in the /proc file system at /proc/tcl.log : #cat /proc/tcl.log TCL Serial Driver V1.6.3 File open failed for /usr/bin/tcldrv/tclcf.ini Found Protected Mode PCI BIOS Card=1 Type=DataPump-4 FoundPorts=4 Addr=0xC8000 Wind=4K Mem=128K ConfiguredPorts=4 ExecName=/usr/bin/tcldrv/tcl186.sys ExecVer=5.3.28 [card:2] WARNING: External interface box not connected to the card! Superport-186 card will not be loaded. Card=2 Addr=0xE0800000 State=FOUND PCI Slot 2 4 ports configured (num_ports) Note that the information about the major and minor numbers is not available in this file. Also note that this file is only present on the system while the driver is loaded since it is a special file maintained in memory by the driver. 6. Device Naming Conventions ============================ Two device nodes are created for each configured port - ttyTx and ttymx, where x is a number from 0 to one less than the number of TCL ports configured by the driver. The ttyTx are conventional terminal devices and the ttymx devices are known as modem devices. The major numbers for these devices are determined dynamically when the driver is loaded. For instance, if the system contains two four port cards, the following device nodes will be created (by the tclload script) when the driver is loaded : Card 1: /dev/ttyT0 /dev/cut0 /dev/ttyT1 /dev/cut1 /dev/ttyT2 /dev/cut2 /dev/ttyT3 /dev/cut3 Card2: /dev/ttyT4 /dev/cut4 /dev/ttyT5 /dev/cut5 /dev/ttyT6 /dev/cut6 /dev/ttyT7 /dev/cut7 7. Using TCL Ports with Terminals ================================= The TCL ports can be set up to connect to a terminal. The procedure is described fully in the Linux Serial Howto, so only a brief description is given here. To create a direct connection from the port to a terminal, a null modem cable is required between the port and the terminal. Make sure there is a suitable entry for the port in /etc/gettydefs. These entries specify the baud rate and tty flags to be used when the port is opened or closed by getty. Two example entries : # 9600 baud Dumb Terminal entry DT9600# B9600 CS8 CLOCAL # B9600 SANE -ISTRIP CLOCAL #@S login: #DT9600 # 115200 baud Dumb Terminal entry DT115200# B115200 CS8 CLOCAL CRTSCTS # B115200 SANE -ISTRIP CLOCAL CRTSCTS #@S login: #DT115200 Add lines in /etc/inittab for the ports to be used with terminals. This specifies port's device name, the name of the gettydefs entry, the runlevels in which the terminal should be enabled, the login program (usually getty) and the terminal type. Supported terminal types are found in /usr/share/terminfo. Example entries to add to /etc/inittab : T4:2345:respawn:/sbin/getty ttyT4 DT115200 ansi80x25 T6:2345:respawn:/sbin/getty ttyT6 DT9600 vt52 Now configure the terminal and connect it to the port using the null modem cable. Make sure that the TCL driver is loaded and then type the following command : # init q The login prompt should now appear on the terminal screen and you should be able to log into the system. Error messages will be displayed (e.g. "getty respawning too fast") if the TCL driver is not loaded when the init command is run. Please NOTE for RedHat 7.2, to enable TCL Port 1 as a terminal you need to add the following to /etc/inittab: T0:2345:respawn:/sbin/agetty 9600 ttyT0 and again use init q to force ithe init process to read the inittab file. 8. Using the TCL Ports to Dial Out ================================== The TCL ports can be used to dial out using terminal emulation packages such as Minicom. They can also be used to establish PPP connections to the internet using modems. Setting up a PPP connection is beyond the scope of this manual - for full details, see the Linux Serial Howto and the Linux PPP Howto. 9. The Driver Configuration File ================================ The driver configuration file is a user-supplied ASCII text file which specifies the configuration and port setup information for all TCL cards in the system. A configuration file can be created using any text editor. The driver configuration file is called tclcf.ini and the driver expects to find it in the same directory as the driver (i.e. in directory /usr/bin/tcldrv). It is not essential to use a configuration file as all ports will be initialised to default settings if no configuration file is specified when the driver is loaded. The main uses of the driver configuration file are as follows : - To specify non-default transmit and receive buffer sizes. The default buffer sizes are 4096 bytes for the transmit buffer of each port and 4096 bytes for the receive buffer. - To limit the number of ports used on a particular card. The default is to use all ports found on the card. - To specify which TCL cards in the system will be used. The default is to use all found cards up to a maximum of 8. - To specify the default port configuration that each port will be set to when a port is opened. Note that this default value may be overridden by other system software such as getty. - To specify the use of a non-standard executive to load onto a TCL card. The default executive for most TCL cards is TCL186.SYS. 9.1 Configuration File Syntax The configuration file consists of paragraphs which begin with key words identifying the paragraph type. The following paragraph types are permitted : setcard setport The setcard paragraph can be used to indicate the number of ports to use on a card and the name of the executive to load onto the card. Each setcard paragraph may be followed by a number of setport paragraphs. The setport paragraph is used to specify port setup information for the ports on the card mentioned in the immediately preceding setcard paragraph. The paragraph type key word is followed by a number of optional parameters as described in the following sections. Note that if there is more than one TCL card in the system, the administrator must know the address of each TCL card in the system in order to be able to create a configuration file. This is because the cards are referred to in ascending address order. 9.2 The SETCARD Paragraph The setcard paragraph has the following format : setcard [cX] nports=Y exec=Z [cX] Here X is the card number and can have a value from 1 to 8. Note that cards are sorted by their physical address with the card at the lowest address being Card 1. The [cX] parameter must be present. nports=Y The value Y is used to indicate how many ports to use on this card. The nports parameter is optional. If not present, the number of ports actually found on the card will be used. Note that the ports used always start at the first port on the card. exec=Z Here Z is the filename of the executive to be loaded onto the card. The path to the file should be specified, including the volume name. Some examples of valid setcard paragraphs : setcard [c1] nports=32 exec=sys:system\myexec.sys setcard [c2] nports=8 setcard [c3] If the driver finds a valid configuration file, then only those TCL cards mentioned in the configuration file are loaded with an executive and used by the driver. If a configuration file is not found, all found TCL cards are loaded with TCL186.SYS and all ports are set up to default values as described in the next section. Note that a minimal configuration file just contains setcard paragraphs with card numbers saying which cards are to be used. For example, if only card 2 and card 5 are needed, then the following configuration file might be appropriate : setcard [c2] setcard [c5] 9.3 The SETPORT Paragraph The setport paragraph has the following format : setport [pN] baud=B, wordlen=W, stopbits=S, parity=P, prot=F, rxbuff=R, txbuff=T [pN] The value N indicates the port being referred to and can take any value from 1 to the number of ports specified in the preceding setcard paragraph. A group of ports is specified using the format [pN-M] (where M >= N). baud=B The following are valid values for B : 50, 75, 110, 134.5, 150, 200, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, 9600, 19200, 38400, 57600, 76800, 115200. wordlen=W This parameter specifies the number of databits and the value of W can be any of the following : 5, 6, 7, 8. stopbits=S The value of S specifies the number of stopbits. Permissible values : 1, 1.5, 2. parity=P P indicates the parity mode with the following permissible settings : none, even, odd, mark, space. prot=F This parameter specifies the flow control method to use for the port. If more than one flow control method is needed, this can be specified by specifiying multiple values seperated by a plus sign (e.g. txxon+cts+dtr). Any sensible combination of the following values is allowed : txxon Transmit XON/XOFF flow. cts Transmit CTS flow. dsr Transmit DSR flow. dcd Transmit DCD flow. ixany Any char acts as received XON. dcdlogoff Kill related processes if DCD drops (UNIX) rtstog Raise RTS when transmitting. rxxon Receive XON/XOFF flow. dtr Receive DTR flow. rts Receive RTS flow. rxdsren DSR acts as receive enable. rxhdxnf Stop transmit if have sent XOFF. rxdcden DCD acts as receive enable. rxhdx Receiver disabled during transmit. none No flow control. If modem is selected, the only other flow modes allowed in conjunction with this are txxon and rxxon. If rxhdx mode is selected, no other flow modes are allowed. rxbuff=R The size of the receive buffer on the card is specified by the value R. Any value from 16 up to 65535 is allowed. Note that the actual capacity of the buffer is one byte less than the specified size. txbuff=T The value T specifies the size of the transmit buffer on the card. Any value from 16 to 65535 is allowed and the actual buffer capacity is one less than the specified size. NOTE: When specifying large buffer sizes, it is possible that there may not be enough memory on the card. In this case, the card allocates as many buffers as it can and then disables any ports for which there was not enough memory for the requested buffers. If this happens, the driver will write a warning to the driver log file (/var/log/tcl.log). The baud, wordlen, stopbits, parity, prot, rxbuff and txbuff parameters are all optional and may appear in any order. Examples of valid setport paragraphs are as follows : setport [p15] baud=9600, wordlen=7, parity=odd, txbuff=512 setport [p16-17] baud=38400, wordlen=8, stopbits=1, parity=none, prot=rts+cts, rxbuff=256, txbuff=512 setport [p18-19] baud=19200 The initial default values are as follows : baud=19200, wordlen=8, stopbits=1, parity=none, prot=none, rxbuff=2047, txbuff=2047 Note that the setport paragraphs are dealt with sequentially and that if not all parameters are specified in a setport paragraph, it is assumed that the rest of them have already been set to a valid value and they are not actively set to the default values. Therefore if a port is named implicitly or explicitly more than once, any parameter not mentioned in the latest setport paragraph will not be altered from what it was set to in the last one. This is illustrated in the following example where the end result is that port 1 on a card is set to 19200 baud, 8 bits, 1 stopbit, even parity, RTS/CTS flow, 256 byte receive buffer and 1024 byte transmit buffer : setport [p1] parity=even setport [p1-4] prot=rts+cts setport [p1-8] txbuff=1024 9.4 Allocating Buffers using a Configuration File The main use for the driver configuration file is to set the transmit and receive buffer sizes. In general, larger buffers will improve performance under heavy load conditions. In addition, the use of large receive buffers reduces the risk of losing data due to the receive buffer becoming full. Most DataServer/8 and Superport-186 cards have 512K memory and about 48K of will be used up by the on-board software for code and data and the top 4K is reserved since this is the card's control window. Therefore roughly 460K is available for allocation as transmit and receive buffers. For an 8-port card, this would allow each port to have a 28,750-byte transmit and receive buffer, although there is no obligation to allocate equal sized buffers as the following example illustrates : setcard [c1] nports=8 setport [p1-2] txbuff=8192 rxbuff=65535 setcard [c2] nports=8 setport [p1-8] txbuff=28000 rxbuff=28000 On the first card, the result would be that the first two ports would have 8K transmit and 64K receive buffers, and the remaining six ports would have the default 4K buffers for both receive and transmit. On the second card, all ports would have 28000-byte buffers for both receive and transmit. Note that the "nports=8" statements are not necessary if these are 8-port cards. 9.5 Configuration File Problems The main problem with using a configuration file is that the system administrator must ensure that the contents of this file correspond to the actual TCL hardware in the machine. If this is not the case, then unexpected behaviour may result. The most important factor is that if the driver finds a valid configuration file, then it ignores any TCL card which is not specifically mentioned. Most situations like this can be detected by inspecting the driver log file. For instance, if a system contains a single 8-port card, the administrator may have created the following configuration file : setcard [c1] setport [p1-8] rxbuff=30000 Now if a second card is added to the system it may or may not be loaded depending on what address it's at. If at a lower address, the new card will be loaded and the old card will be ignored by the driver. If the new card is installed at a higher address, the driver will load the old card and ignore the new one. Therefore if the intention is to use both cards, the necessary minimum change to the configuration file is as follows : (for new card at lower address than old card :) setcard [c1] setcard [c2] setport [p1-8] rxbuff=30000 (for new card at higher address than old card :) setcard [c1] setport [p1-8] rxbuff=30000 setcard [c2] NOTE: If there is no configuration file, the driver loads all TCL cards and configures all the ports on these cards to the default setting (19K2, n, 8, 1, no flow, txbuff=4096, rxbuff=4096). 10. Warning Messages ====================== The following is a list of messages that may appear in the driver log file. "File open failed for " This message means that the driver couln't find the named file. In most cases, the driver will continue initialisation but will substitute default values for information that might have been contained in the missing file. This message is displayed with filename as tclcf.ini if there is no configuration file, but this only indicates a problem if you intended the driver to use a configuration file. If the file tcl186.sys is missing, this will cause the loader to terminate unless a different executive has been specified using the driver configuration file using an "exec=" statement. "Warning : Superport-186 at address xxxxx is not connected/not switched on" This message is displayed if the Superport-186 external interface box is not connected to the card or is not switched on. The driver will continue loading and configuring other TCL cards in the system but will not attempt to configure any ports on this card. Once the external interface box has been connected and switched on, the driver must first be unloaded and then reloaded in order to be able to use the Superport-186 ports. "No TCL cards found in the system" This message will be displayed if there are no TCL cards installed in the system. The driver will not load in this case. "[card:%d] ERR_CARD_NOT_FOUND: Card pre-specified at address 0x%lX was not found.\n" This message indicates that more cards were specified in the configuration file than were physically found in the machine. (Usually the address in this message will be given as 0x0, just ignore this). "ERR_CARD_NOT_FOUND: No TCL hardware was found in the system\n" No TCL intelligent cards were found in the system. "[%s] WARNING: nports=%d trimmed to %d.\n" The "nports=" statement in a setcard paragraph in the configuration file brought the total number of preconfigured ports to more than 512 ports. The driver can handle a maximum of 512 TCL ports. "[%s] WARNING: setport[%d-%d] trimmed to [%d-%d].\n" The "setport [pn1-n2]" statement is for more ports than have been configured on the card. "[%s] WARNING: invalid statement setport[%d-%d], assuming [%d-%d].\n" This will occur for a "setport [pn1-n2]" where n2 is less than n1. "File read failed (%s)\n" An error occurred reading the named file. Usually this would be because the file does not exist. "[card:%d] WARNING: External interface box not connected to the card!\n" This applies to the Superport-186. This sometimes occurs even when the external box appears to be connected to the card if the connectors are not firmly pushed in. "[card:%d] WARNING: External interface box not switched on!\n" This applies to the Superport-186. Switch on the external box and reload the driver. "[card:%d] ERR_CARD_EXECUTION: Card has failed to execute.\n" This message indicates that the driver has loaded a program onto the card, but that the card did not appear to execute the program. This can occur due to faulty hardware or an invalid file being loaded. "[card:%d] ERR_BAD_PARAM: Unable to import file %s image for loading.\n" The driver couldn't open or read a file that it wanted to load onto the card. "[card:%d] ERR_EXEFIXUP: An error has occurred fixing up %s.\n" The named file is probably not a valid .EXE format file. "[card:%d] ERR_FILE_TOO_LARGE: %s size %ld is too big for card memory %XK.\n" The named file is too large to be loaded onto the card. "[card:%d] WARNING: Unable to import Defn file %s, using internal defaults.\n" The driver couldn't find TCLHW.DEF. "[card:%d] WARNING: Unable to import ID file %s, using internal defaults.\n" The driver couldn't find TCLID.BIN. "[card:%d] ERR_CARD_EXECUTION: Unable to execute ID code.\n" The driver loaded TCLID.BIN onto the card but an error occurred (the driver has timed out waiting for TCLID.BIN to identify the card). "[card:%d] WARNING: Unknown hardware attached to the card\n Superport-186 card will not be loaded.\n" It's hardware Jim, but not as we know it. "[card:%d] WARNING: External interface box not connected to the card!\n Superport-186 card will not be loaded.\n" OR "[card:%d] WARNING: External interface box not switched on!\n Superport-186 card will not be loaded.\n" Superport-186 only. The external box is not connected to the card or the external box is not switched on. "[card:%d] ERR_BAD_CARD_ID: The card at address 0x%lX has an unrecognised Id code 0x%X.\n" TCLID.BIN appears to have run successfully but it has not found any of the cards defined in TCLHW.DEF. The driver will not be able to use this card. "[card:%d] ERR_BAD_EXECVER: Executive version %d.%d.%d.%d is not compatible with this software.\n" Usually, this message means that TCL186.SYS failed to execute properly. Although this message would be diplayed for older executives such as PCCASYNC.SYS which do not work with the V2.01 driver. "[card:%d] ERR_NO_PORTS: No ports have been found on the card.\n" No ports found on the card. "[card:%d] WARNING: Pre-Configured ports exist which will not be initialised.\n" The configuration file specified more ports than actually exist on the card or more ports than were specified by a "nports=" statement. "[card:%d] %X: Card has failed to initialise.\n" An executive was loaded onto the card but did not complete initialisation. "[card:%d] WARNING: Ports have been restricted to %d.\n" This message usually indicates that there is not enough memory on the card for the requested receive and transmit buffers. 11. Driver Disk Contents ======================== The driver distributions disk is in ext2 format and contains the following files : README Installation instructions. tclsetup Script used to install the driver. tclremove Script used to remove the driver. tcldrv-1.6.3-1.i386.rpm RPM package containing the driver files. 12. Driver Files ================ The following files are installed by the driver installation program : /usr/doc/tcldrv-1.6.3/tcldrv.txt This file /usr/bin/tcldrv/tcldrv.o The driver module /usr/bin/tcldrv/tcldrv.o.2.4.2 The 2.4.2 kernel driver module /usr/bin/tcldrv/tcldrv.o.2.4.7 The 2.4.7 kernel driver module /usr/bin/tcldrv/tcldrv.o.2.4.7-10 The 2.4.7-10 RedHat kernel driver module /usr/bin/tcldrv/tcl186.sys Async executive /usr/bin/tcldrv/tclsync.sys GlobeServer sync executive /usr/bin/tcldrv/tclrisc.sys RISC card executive /usr/bin/tcldrv/tclid.bin Card identification program /usr/bin/tcldrv/tclhw.def Card feature file /etc/rc.d/init.d/tclload Driver load script /etc/rc.d/rc0.d/K65tclload Symbolic link to tclload /etc/rc.d/rc1.d/K65tclload Symbolic link to tclload /etc/rc.d/rc2.d/S65tclload Symbolic link to tclload /etc/rc.d/rc3.d/S65tclload Symbolic link to tclload /etc/rc.d/rc4.d/S65tclload Symbolic link to tclload /etc/rc.d/rc5.d/S65tclload Symbolic link to tclload /etc/rc.d/rc6.d/K65tclload Symbolic link to tclload /usr/bin/tclload Symbolic link to tclload 13. Driver Release Notes ======================== The driver does not work with the setserial program. This is because it does not need to as the parameters that setserial sets such as I/O address and interrupt number do not apply to TCL hardware. This driver has been written using Linux Kernel 2.2.x. Using this driver with Linux Kernel 2.0.x will result in unresolved externals (1.2.1). driver 1.3.1: ============= DTR/RTS problem has been fixed for modem devices. driver 1.4.1: ============= ODD/EVEN parity problem has been fixed. insmod to use -f switch for loading on different kernel version. modem device names changed from cut to ttym. driver 1.5.1: ============= Recompile the driver under 2.2.18 to include the new tty fields. Please note that this driver has fully tested to run OK with Kernel 2.2.16. Modem device names restored back to cut. driver 1.6.1: ============= Recompile the driver under 2.4.2 replacing proc_register and proc_unregister. This driver has been tested to run OK with Kernel 2.4.2. driver 1.6.2: ============= Recompile the driver under 2.4.7. Also new tcl186.sys version 5.3.28. On the installation side, the new TCL script will test for the Kernel version if not 2.4.2 --> the driver object compiled for 2.4.7 will be copied as tcldrv.o. driver 1.6.3: ============= Recompile the driver under RedHat 7.2 Kernel 2.4.7-10. On the installation side, the new TCL script will test for the Kernel version copy over tcldrv.o the correct driver object file. 14. To Contact TCL: =================== IT Factor Ltd t/a TCL, 24 Thatcham House, Turners Drive, Thathcam, Berkshire, UK RG19 4QD www.TheTcl.com support@teccon.co.uk tel: +44 (0)1635 876754 fax: +44 (0)1635 871739 # End of tcldrv.txt