The purpose of this document is to give the end user a good idea as to what needs to be done in order to get a serial card to operate under Linux. Certain topics covered in this document will cover kernel options and other sensitive subjects. Great care must be taken whenever you see *CAUTION* included in a topic. Whenever you see *IMPORTANT*, there may be a potential Catch-22 that needs to be read, understood, and possibly dealt with. We have extensively tested and confirmed as much of this document as possible, however; Linux distributions, kernel revisions, and system configurations being many and we being few in comparison, there are bound to be differences from the norm. You are highly encouraged to refer to the Linux-HOWTO documents and individual man pages for any topics we cover. If something just doesn't seem right, by all means, consult the supplemental documentation freely avaliable. WARRANTY We make no implied or express warranty of any kind with regard to this software or the documentation that is included. We will not be liable for damages of any type resulting from the performance, use or furnishing of any of the supplied software. Any liabiliby will be limited to a refund of the purchase price or product replacement. Note that for the rest of this document, you need to be logged in as root. CONTENTS 1) Pre-Installation requirements and notes *IMPORTANT* 1.1) Kernel configuration 1.2) ISA/PC104, PCMCIA, PCI, or USB 1.3) What is an ISP (Interrupt Status Port) and why does it concern me? 1.4) Serial Device Nodes (/dev/ttySXXX) 2) Configuring your system prior to installation 2.1) ISA/PC-104 Non-Shared Interrupts and/or single port PCI products. 2.2) ISA/PC-104 Shared Interrupts and/or multiport PCI products. 2.3) PCMCIA 2.4) USB 3) Installation of a Serial device 3.1) ISA/PC-104 Non-Shared Interrupts and/or single port PCI products. 3.2) ISA/PC-104 Shared Interrupts and/or multiport PCI products. 3.3) PCMCIA 3.4) USB 4) Utilities 4.1) Minicom 4.2) Setserial 4.3) Hotplug 5) Supplemental Documents 5.1) Kernel Documentation 5.2) Man Pages 5.3) Linux-HOWTO's 1) Pre-Installation requirements and notes *IMPORTANT* 1.1) Kernel configuration *IMPORTANT* *CAUTION* Certain features of our serial products require special kernel options to be set in order for them to work. Please note that whenever dealing with your kernel, care needs to be taken to not set or unset the wrong option which may cause your system to become unstable or worse, unusable. 1.2) ISA/PC104, PCMCIA, PCI, or USB When installing an ISA/PC-104 product a few things need to be remembered. An ISA board cannot share an interrupt with other devices in the system and therefore need to be assigned a free interrupt. Certain boards have the ability to share interrupts with other ports on the board itself. These boards may or may not have what is known as an ISP (see section 1.3). If your ISA/PC-104 serial board does not have an ISP, you still have the option of sharing the interrupts on a multi-port board, but you may not use the ports simultaneously. See sections 2.1 and 3.1 for configuration and installation of single port or "multiport non-shared interrupt" boards. See sections 2.2 and 3.2 if you intend to share interrupts on a multiport board with an ISP. PCMCIA serial devices need special configuration within the system to be installed properly. See sections 2.3 and 3.3 for configuration and installation. PCI serial devices also require special configuration within the system to be installed properly. See sections 2.2 and 3.2 for configuration and installation. USB serial devices will require special configuration, and some third party software which most distributions do not ship with. It is highly recommended that you have a 2.4 or later release kernel installed in order to use USB serial devices. 1.3) What is an ISP (Interrupt Status Port) and why does it concern me? An ISP (Interrupt Status Port) is a section of I/O space on the first port of a multiport board that has information concerning which port has generated an interrupt when multiple ports are sharing a single interrupt. Certain ISA/PC-104 boards have them (refer to the manual) and all multiport PCI boards have them. If your ISA board has one and you intend to share interrupts, or if you have a PCI multiport board, a specific kernel configuration option has to be set, and a special "setserial" parameter has to be included to prevent a possible system lock if you are using more than one port at a time. See section 2.2 and 3.2 for proper configuration of this option. 1.4) Serial Device Nodes (/dev/ttySXXX) Serial Device Nodes are what you assign a given port to. /dev/ttyS0 is the equivalent to Com1 in DOS, /dev/ttyS1, Com2 and so on. If there are fewer device names than ports to install, you will have to add some. The simplest method is to change to the /dev directory and run ./MAKEDEV /dev/ttySX. X = the next number in line. If there are already /dev/ttyS0 to /dev/ttyS15 then start at /dev/ttyS16. To find out what the last serial device you have setup is, type (Look carefully at the string, it has both "l" and "1") ls -1vl /dev/ttyS[0-9]* | tail - 1 If MAKEDEV is not avaliable you will have to use the more complicated method which uses "mknod". In order to make the serial device this way, you will have to know the serial driver major and minor numbers. 98% of all serial devices will have a major number of "4", whereas the minor number typically starts at "64" (for COM1) and goes up from there. Ex: Com1 = Major 4, Minor 64; Com2 = Major 4, Minor 65; Com3 = Major 4, Minor 66; etc. The best way to find out what the last serial device including major and minor number information is to type (Look carefully at the string, it has both "l" and "1") ls -1vl /dev/ttyS[0-9]* | tail - 1 That will return a single line of information similar to: crw-rw---- 1 root uucp 4, 67 Aug 24 2000 /dev/ttyS3 In this case, /dev/ttyS3 is the highest serial device location with a major number 4 and a minor number of 67 (Hence the 4, 67). If you are to use mknod to make a new serial device starting immediately after the last one in this example, you would type: mknod -m660 /dev/ttyS4 c 4 68 Notice that we incremented both the /dev/ttyS4 and the 68 to the next number in line. Note that the range of serial ports is only from /dev/ttyS0 M4 m64 to /dev/ttyS191 M4 m255. You cannot have more than that. (M=major number, m=minor number). 2) Configuring your system prior to installation 2.1) ISA/PC-104 Non-Shared Interrupts and/or single port PCI products. There is no special configuration necessary for installation of this type. Proceed to section 3.1 for installation. 2.2) ISA/PC-104 Shared Interrupts and/or multiport PCI products. There are a few special kernel options that need to be set prior to installing either multiport ISA or multiport PCI. *IMPORTANT* You need to have the kernel source installed in order to complete the following tasks. *CAUTION* We will be configuring your kernel at this point if it is not already set properly. Change directory to "/usr/src" Change directory to "linux" OR Change directory to "linux-YOURCURRENTKERNELVERSION" You have 2 options at this point, option 1 is to configure the kernel using the ".config" file and a text editor, or option 2 is to use "make menuconfig". It is totally a user preference at this point, option 1 is a little faster though. OPTION 1 *CAUTION* Here is where we need to walk carefully Using your favorite text editor while in the /usr/src/linux directory, edit the ".config" file. Search for "Character devices", if that fails, search for "CONFIG_SERIAL_EXTENDED". We are now in the correct section to set up the proper parameters. The lines we need to change are as follows: CONFIG_SERIAL CONFIG_SERIAL_EXTENDED CONFIG_SERIAL_MANY_PORTS CONFIG_SERIAL_SHARE_IRQ CONFIG_SERIAL_MULTIPORT If any of those lines are listed as: # CONFIG_SERIAL... is not set Remove the "#" and make them look like: CONFIG_SERIAL=y CONFIG_SERIAL_EXTENDED=y CONFIG_SERIAL_MANY_PORTS=y CONFIG_SERIAL_SHARE_IRQ=y CONFIG_SERIAL_MULTIPORT=y If these options are already set and this is not a brand new kernel, you may skip to section 3.2 You may now save and exit the editor. Proceed to after "End of OPTIONS" OPTION 2 *CAUTION* This is where we need to walk carefully. From the /usr/src/linux directory, type make menuconfig That will bring up a menu-driven configuration screen. Scroll down to "Character Devices" and enter that menu. Using the spacebar to select options, we need to make sure that the following options have a "*" next to them. Standard/Generic (8250/16550 and compatible UARTS)... Extended Dumb Serial Driver Options Support for more than 4 serial ports Support for sharing serial Interrupts Support for special multiport boards If these options are already set and this is not a brand new kernel, you may skip to section 3.2 Exit all of the menus and when it asks to save your new kernel configuration hit "yes" Proceed to "End of OPTIONS" End of OPTIONS Now a kernel recompile is necessary. Assuming you are using lilo as your boot loader, the following compilation string should work for you. *CAUTION* *CAUTION* *CAUTION* If anything here seems out-of-the-ordinary or wrong, STOP NOW! Consult your distribution documentation on how to properly recompile your kernel. This next command will work in about 90% of distributions out there, but you don't want to be the 10%. This is not Vegas, and I would not suggest playing the odds on this one if you are unsure about any of it. make clean && make dep && make modules && make modules_install && make bzlilo After completion without error, and a successful reboot you should be ready to install your cards, proceed to section 3.2 2.3) PCMCIA In order for linux to properly detect and set-up a PCMCIA serial device, it first needs to know what it is and associate a driver to it. We do this by modifying the /etc/pcmcia/config file. The "config" file may not be in that directory, but it commonly is. We suggest you consult your distribution documentation if it is not in /etc/pcmcia. Using your favorite text editor, edit the "config" file and search for the section that reads: "Modems and other serial devices". We will be inserting approximately 9 lines of information in that section: card "RS-422 Capable Serial PCMCIA Card" manfid 0x0167, 0x3602 bind "serial_cs" card "RS-232 Capable Serial PCMCIA Card" manfid 0x0167, 0x3603 bind "serial_cs" card "Dual RS-232 Capable Serial PCMCIA Card" manfid 0x0167, 0x3622 bind "serial_cs" If everything else is properly configured as far as your PCMCIA services, after a reboot, the PCMCIA serial cards should be hot pluggable and ready to go. Skip to section 3.3 2.4) USB It is highly recommended that you use 2.4 and higher kernels if you want to use USB serial devices. There is a third party piece of software called "hotplug" that most distributions do not ship with by default. You can download and install it from http://linux-hotplug.sourceforge.net Next, extract the sealevel_usb.tar.gz which is included in the software distribution to a local directory, and run "./apply-patch" from the directory which you extracted to. Next we will need to check your kernel options to make sure we have the proper ones set. You have two Options on how you can do it and it really comes down to user preference. Option 1 is using your favorite text editor on the ".config" file, and Option 2 is using the "make menuconfig" method. OPTION 1 *IMPORTANT* You need to have the kernel source installed to complete the following *CAUTION* We need to walk carefully in these next lines Change to your /usr/src/linux directory. Use your favorite editor to edit the ".config" file. We are searching for the "USB Support" section. The option "CONFIG_USB" needs to be set like this: CONFIG_USB=y Depending on what type of USB host controller you have you need to have either: CONFIG_USB_UHCI_ALT=y or CONFIG_USB_OHCI=y Procced to the "End of OPTIONS" OPTION 2 *IMPORTANT* You need to have the kernel source installed in order to complete the following *CAUTION* We need to walk carefully in these next lines Change directory to /usr/src/linux Type make menuconfig Enter "Code Maturity level options" and if it does not have a "*" next to it, use the spacebar to select the "Prompt for development and/or incomplete code/drivers" Using the arrow keys, move down to and enter the "USB Support" Section. Using the spacebar to change options, make sure that "Support for USB" has a "*" next to it. Depending on what type of USB host controller your system has, you will need to have a "*" next to either "UHCI Alternate Driver (JE) Support", or "OHCI (Compaq, iMacs, OPTi.....)" Next, enter the "USB Serial Converter Support" Menu near the bottom. "USB Serial Converter Support" needs to have a "M" next to it. "USB Generic Serial Driver" needs to have an "*" next to it. "USB FTDI Single Port Serial Driver (EXPERIMENTAL) needs to have an "M" next to it. You may now exit and save your new kernel options. Proceed to "End of OPTIONS" End of OPTIONS Now a kernel recompile is necessary. Assuming you are using lilo as your boot loader, the following compilation string should work for you. *CAUTION* *CAUTION* *CAUTION* If anything here seems out-of-the-ordinary or wrong, STOP NOW! Consult your distribution documentation on how to properly recompile your kernel. This next command will work in about 90% of distributions out there, but you don't want to be the 10%. This is not Vegas, and I would not suggest playing the odds on this one if you are unsure about any of it. make clean && make dep && make modules && make modules_install && make bzlilo After completion without error, and a successful reboot you should be able to plug in your USB serial device and begin using it. 3) Installation of a serial device 3.1) ISA/PC-104 Non-Shared Interrupts and/or single port PCI products. Installation of a PCI single port card is simplified by a script that we include on the software media. If you extract the pci_inst.tar.gz file in a convenient directory, and then run "setserial_pci XX" where XX is the serial device number you want to assign it to. Eg. "setserial_pci 24" will assign the single port PCI device to /dev/ttyS24. The first step to installing an ISA/PC-104 card is to set the card's Base Input/Output range, and the Interrupt line. You want to pick both an IO space and Interrupt that are not used. Generally speaking, the defaults on the card are fine and ready for installation, but it is infinitely better to make sure now before you install it and possibly have a headache later figuring out why it isn't installing because of a conflict. To find out what IO space is being used type more /proc/ioports This will give you a breakdown of what devices are occupying what IO currently on your system. You should now check your default configuration on the card and decide if you need to change it to anything else in order to not conflict with an existing device. Next you will need to find what interrupts are being used; type more /proc/interrupts This will give you a breakdown of what devices are currently using what interrupts. You should note this and choose an interrupt on the card that is not currently occupied if the defaults are conflicting. Note that if you are configuring a multiport board for non- shared interrupts, you will need to verify each port's I/O and interrupt are not conflicting with other devices. Next, halt the system and install the card. Remembering what IO space and Interrupt you configured the port(s) to we will now be using that information with setserial setserial /dev/ttySXX port 0xBASEIO irq IRQLEVEL autoconfig ttySXX = whatever device you want to assign it to BASEIO = the IO address you selected on the card IRQLEVEL = the IRQ you selected on the card That should do it. You now have a serial port set up. If you have a multiport non-shared interrupt board, do the same for the rest of the ports, increasing in the /dev/ttySXX ranges until you have finished setting up all of your ports. 3.2) ISP/PC-104 Shared Interrupts and/or multiport PCI products. PCI installation is much easier than ISA installation and is covered a little further down the section. Installing a multiport shared interrupt ISA board, the installation procedure is very similar to section 3.1. The main differences are that you will be using the same interrupt and after setting up the last port on the board, you have to add one more setserial command to properly set up the ISP. We will use an example of a 4 port ISA board sharing IRQ 5 IO starting at 0x280 and finishing at 0x297. setserial /dev/ttyS5 port 0x280 irq 5 ^fourport autoconfig setserial /dev/ttyS6 port 0x288 irq 5 ^fourport autoconfig setserial /dev/ttyS7 port 0x290 irq 5 ^fourport autoconfig setserial /dev/ttyS8 port 0x298 irq 5 ^fourport autoconfig setserial /dev/ttyS5 set_multiport port1 0x287 mask1 0xf match1 0x0 If you notice, the first four lines are very similar to the previous section on installing a port. The most striking difference is the "^fourport" and the fifth line in the text. The fifth line sets up the ISP. The ISP will always be at (base address of port one + 7h). In this case, port 1 is at 0x280 therefore the ISP is at 0x287. If port 1 was at 0x588 the ISP would be at 0x58f. The next detail that needs to be carefully watched is the "0xf" parameter. In this case we have a four port board and it will always be 0xf for four port boards. If you are installing a 2 port board, it will always be 0x3, and if you are installing an 8 port board, it will always be 0xff. For example, we will use an 8 port board. Configured for 0x500 starting base address. (Note: I will omit the initial setserial commands for the 8 individual ports, I will only display the ISP configuration) setserial /dev/ttySX set_multiport port1 0x507 mask1 0xff match1 0x0 Note the 0xff is required for 8 port boards and the base address is different. PCI Multiport installation is much easier, extract the pci_inst.tar.gz from the supplied driver disk and after inserting the card into the system, run the "pci_inst/setserial_pci XX" command. XX=Number of the serial device (eg. 16 = ttyS16, 5 = ttyS5). The script will install however many ports are on the PCI board starting at the device you specify. 3.3) PCMCIA If your system is configured right, all you have to do is insert the PCMCIA card into the slot and everything will be automatically done for you. If you wish to find out what device number the PCMCIA card got assigned to, on most Linux distibutions, the "/var/lib/pcmcia/stab" OR the "/var/state/stab" OR the "/var/state/pcmcia/stab" file contains PC-Card information and driver information assigned to it. If those files do not exist, check your distribution documentation concerning PCMCIA devices. 3.4) USB If your system is configured right, when you plug in the device it will automatically be installed to a /dev/ttyUSBX device. If you type "dmesg |grep ttyUSB" it will return something similar to usbserial.c: Serial capable USB device now attached to ttyUSB0 (or usb/tts/0 for devfs) If you notice the first word on the second line has "ttyUSB0" this is the serial device which acts the same as a regular serial device now. 4) Utilities 4.1) Minicom Minicom is a small easy-to-use utility that is installed by default on most distributions that can be used as a serial testing utility. When you run Minicom for the first time, it will request information that it will use as defaults and initial start-up parameters. It will ask which serial/modem device you wish to use. Here is where you put in the serial device you are testing first. After the first initial configuration, it will be necessary to use the option screens to select another port. *BUG* *BUG* *BUG* Minicom has a bug that will not let you choose another port on the fly. You have to select a new port, save your options as the default, exit minicom and then re-enter it. A workaround for this is to assign minicom to a symbolically linked file. Eg. /dev/TestSerial -> /dev/ttyS0, and after you test that port, create a new symlink to refer to /dev/ttyS1. You can do this by typing "ln -s /dev/ttySX /dev/TestSerial" X= The port you wish to use. 4.2) Setserial Setserial is the general, all-purpose, serial utility. It provides for serial configuration, serial verification, port states, and many other options. If you run "setserial -g /dev/ttySX" it will return information concerning the port. If it returns UNKNOWN for the UART Type, than either the port is not configured properly, or the UART is one the system does not recognize as a standard UART type. The "man" pages for setserial are very helpful when working with serial devices. You can access it by typing "man setserial". 4.3) Hotplug Hotplug is a utility released to provide for hot-swapping USB devices in a system. It automatically assigns a driver and device node to a particular device plugged into the system, and automatically removes the same information on disconnect. The latest versions and documentation resides at: "http://linux-hotplug.sourceforge.net" 5) Supplemental Documents 5.1) Kernel Documentation There is a wealth of information concerning the device drivers and other kernel configuration options located in "/usr/src/linux/Documentation" It contains all the latest information for a given driver including quirks and pitfalls. This information is extremely valuable when learning about specific functions of the serial, PCMCIA, and USB driver. If you have a driver issue or need more information concerning a driver, consult this information first. 5.2) Man Pages The man pages are the individual MANual pages for a specific command, utility, piece of software, etc. They provide good information concerning syntax, bugs, and tips when using a given program and also reference utilities they depend on or that may come in useful. To access a given manual page for any command type in "man PROGRAM" PROGRAM = the program you want information on. 5.3) Linux-HOWTO's Linux-HOWTO's get into depth on how do to a specific thing, not just provide the user with syntax and parameters. The HOWTO's take you through an entire process to accomplish a goal whereas the Man pages and Kernel Docs only provide you with assistance with one step in the process, and will sometimes not provide you with the next step you have to complete to accomplish your goal.