Introduction
The instructions below are designed to assist users with the software installation of WhiteHEAT USB serial adapters under a Linux platform. Although this document has been specifically written for Red Hat distributions (2.4.X kernels), it will apply for other Linux distributions as well. If you are NOT using Red Hat, please take note of the following potential differences between distributions.
- Differences in directory structure.
- Differences in filenames.
There is a possibility that certain files mentioned in this document may have different file names, or may be located in different directories other than the ones mentioned here with different distributions. Depending on how your system is set up, this may be the case even with a Red Hat distribution. Before you begin the installation, make sure you know the name of your kernel and the directory in which it is located. You MUST have the Linux source tree installed before you begin the installation procedure. Where there may be potential differences in directory structure, there has been an attempt to make the installation instructions relatively generic.
NOTE: To perform the installation, please be sure you are logged in as root.
To make the installation instructions easy to follow, all commands given on the command line are written in bold text. Before beginning the software installation procedure, please be sure to carefully read the WhiteHEAT User’s Manual that came with the host adapter for hardware installation/configuration instructions.
The majority of our products have default support in 2.6.X kernels. Be sure to add the kernel configuration options mentioned below and the system should automatically detect and install the serial ports. You don’t need to patch your Kernel source for 2.6.X as the WhiteHeat/USB has been already added into the Kernel source tree.
If you are using a Linux 2.6 Kernel you simply need to follow the instructions for compiling the kernel with the needed options mentioned below. Be aware changes to the 2.6 kernel have broken the WhiteHeat/USB driver at various points in 2.6 development. If you encounter any compile errors please contact support for assistance in working around these changes: [email protected]
Preamble
This section briefly describes what you will need to successfully install the WhiteHEAT USB multiport serial adapter in a Linux environment. There are several ways that you may obtain the necessary files for the installation:
– Linux driver diskette that comes with the WhiteHEAT USB serial adapter will have all the files necessary to complete the installation.
– You can download a .tar file which contains all of the necessary files from the Connect Tech website: https://connecttech.com/asp/Support/DownloadZone.asp
Extracting the Driver
Before we begin the installation, you will need to copy all files from the Linux driver diskette to a directory on your system. It is suggested that you copy the file to a /usr directory. You should place the files in an empty directory, or a newly created directory. The directory that you chose to copy the files to will be referenced by {direct}. To copy the file to the {direct} directory, issue the following command:
# cd {direct}
# tar -xvf /dev/fd0
Now all of the files from the driver diskette will be located in the {direct} directory. Of course, if you have downloaded the .tar file from the website, you will have to issue the following command:
# tar -xvf WH-Linux_XXXX.tar
Where XXXX is the current release version of the serial driver and patches (currently 5054).
Applying the Patches
NOTE: It is strongly recommended that you back up your kernel, as well as any serial source trees before applying the patches.
NOTE: These patches should only be used for 2.4.17 or 2.4.19 kernels. If you need to use other versions please contact Connect Tech support at [email protected]
NOTE: 2.4.19 is the most current 2.4.x kernel at the time of this writing. If you need to use a newer version, these instructions may work, but we recommend contacting Connect Tech Support at [email protected]
NOTE: 2.4.11 and 2.4.15 are known to be bad. These kernels are not supported.
All necessary patch files will be in cti-wh-patches.tar.gz. To extract the patches, issue the following commands:
# gunzip cti-wh-patches.tar.gz
# tar -xvf cti-wh-patches.tar
Once extracted, all patches will be placed in a subdirectory called cti-wh-patches. This directory will be now referenced by {patch}. You should have the linux kernel source in a subdirectory. This is usually /usr/src/linux but may be different for your system. This directory will be referenced by {linux}. To patch the kernel, issue the following commands:
# cd {linux}
# patch -p1 < {patch}/patch-2.4.X
where X is either 17 or 19, as appropriate for your installation.
Configuring the Kernel
At this point, we will configure the kernel to ensure that we have the appropriate settings needed to support the WhiteHEAT serial adapter on your system.
NOTE: Red Hat 7.2 installs: There is a circular dependency in the “make config” step. Please execute “make oldconfig” between the “make mrproper” and “make menu/config” steps to work around this.
# cd {Linux}
# make mrproper
At this point, you have a choice of two configuration utilities that you can use to configure your kernel. One utility, named config, is text based, and the other, named menuconfig, has a simple GUI (Graphical User Interface). The menuconfig utility is easier to use than config, so unless you have specific reasons use the menuconfig utility.
# make oldconfig (Red Hat 7.2 installs only)
To use the menuconfig / config utility:
# make menuconfig
Or
# make config
Once the configuration utility you choose is running, make sure that the following options are selected. Below shows the setting that must be enabled using the menuconfig and config utilities.
NOTE: You may need to unselect the selected UHCI driver to get the alternate UHCI driver to appear.
NOTE: If you would like to install the WhiteHEAT driver as a module, please refer to the
section entitled “Installing the Driver as a Module” for further information.
NOTE: You only need ONE of the UHCI drivers.
CONFIG_USB_UHCI_ALT
(USB support -> UHCI Alternate Driver (JE) support)
CONFIG_USB_UHCI
(USB support -> UHCI (Intel PIIX4, VIA, …) support (NEW)
CONFIG_USB_OHCI
(USB support -> OHCI (Compaq, iMacs, OPTi, SiS, ALi, …) support)
You’ll need all of the following options: CONFIG_USB_SERIAL
(USB support -> USB Serial Converter support -> USB Serial Converter support)
CONFIG_USB_SERIAL_WHITEHEAT
(USB support -> USB Serial Converter support -> USB Serial Converter support -> USB ConnectTech WhiteHEAT Serial Driver)
After all of the options have been checked and enabled, select exit. You will be prompted to save the new kernel configuration. Select yes. After you have finished configuring your kernel, issue the two following commands:
# make dep
# make clean
# make bzImage
# make modules
# make modules_install
Building/Installing the Kernel
NOTE: These instructions are for Red Hat standard installs. If you use a different distribution, or have set up your own system, these instructions will likely not help you. In that case please contact Connect Tech support at [email protected]
The “make bzImage” step created the kernel in the subdirectory {Linux}/arch//boot. If you don’t know what cpu type you’re using, you can find the new kernel by:
# ls -l {Linux}/arch/*/boot/bzImage
The < cpu type > is the “*” part of the pathname of the newest kernel.
/arch//boot will be referenced by {arch}.
# cp {Linux}/{arch}/bzImage /boot/vmlinuz-wh
# cp {Linux}/System.map /boot/System.map-wh
You may choose any postfix, -wh is a handy one
Editing your boot loader
NOTE: You only need to do one of these two sections (update lilo OR update grub). Please follow the instructions appropriate for the boot loader in your install.
1) Update lilo:
# vi /etc/lilo.conf
Image sections start with an image= keyword and end at the end of the file or the next image= keyword. Copy one section. Update the image= and label= keywords:
image=/boot/vmlinuz-bh
label=Linux-wh
Exit the editor.
NOTE: Running lilo here is critical. Lilo builds some information about the kernels listed in its configuration file. If you copy a new kernel over an old one and omit running lilo, the information will be wrong, and the new kernel may not work. The errors produced by this will usually appear to be unrelated to a misconfigured lilo, making this very difficult to debug.
# lilo
The kernel is now installed! To boot this kernel, press the tab key when prompted at boot time and specify the kernel you wish to boot.
2) Update grub:
# vi /boot/grub/grub.conf
Image sections start with a title keyword and end at the end of the file or the next title keyword. Copy one section. Update the title and kernel keywords:
title Linux-bh
kernel /vmlinuz-wh ro root=/dev/hda2
Note that pathnames in grub have a root of /boot by default, so the kernel keyword above actually refers to /boot/vmlinuz-wh.
Exit the editor.
The kernel is now installed! To boot this kernel, press the tab key when prompted at boot time and specify the kernel you wish to boot
Creating Nodes (ports) for the Host Adapter
Now that we have the new kernel in place capable of supporting the Whiteheat serial adapter we must create nodes, or ports, to allow the host adapter to communicate with other devices.
NOTE: Depending on your kernel distribution and default settings these nodes may be created automatically.
To begin, boot the new kernel. After the kernel boots, open up the messages file using the Vi editor, or your favorite text editor:
# vi {log_path}/messages
Where {log_path} is where the system logs are stored. Typically, {log_path} = /var/log but this may be different in some distributions/systems.
Go to the bottom of the file and search backwards for references to “ttyUSBx” where x is a number. You should see ttyS0 and ttyS1 for the standard serial ports, as well as a ttyUSBx entry for each installed Whiteheat port. In order to use the new ports, these ttyUSBx entries must exist in the /dev directory. If they do not exist (they aren’t created automatically, but do persist after reboots) you must make them with the following command:
# mknod -m [mode] /dev/ttyUSBx c 188 y
[mode] is the file mode (permissions) you wish the device to have. 666 is often good.
x is the number associated with the device which you have seen in the messages file.
188 is the number associated with ttyUSB. This can be confirmed with:
# cat /proc/devices -look for the number associated with USB
y just starts at 0, and increments by one for each port.
Here is an example of what you would do to add the nodes to your /dev directory:
First I opened the Vi editor and searched for ttyUSB*. The results of the search show I have ttyUSB0, ttyUSB1, ttyUSB2, and ttyUSB3. These four entries correspond to the four new ports for my CTI host adapter. I’ve written down the four entries on a sheet of paper, seeing how my memory is a little short. Now I would like to make the nodes. From the command line, I typed in the four following entries:
# mknod -m 666 /dev/ttyUSB0 c 188 0
# mknod -m 666 /dev/ttyUSB1 c 188 1
# mknod -m 666 /dev/ttyUSB2 c 188 2
# mknod -m 666 /dev/ttyUSB3 c 188 3
With the nodes in place, this finishes off our installation.
Installing the Driver as a Module
In order to compile modules at all, you need to select the following option when performing the “make menuconfig” step:
Config option
(Menuconfig equivalent)
CONFIG_MODULES (Loadable module support -> Enable loadable module support)
Selecting the following option is usually a good idea, it prevents subtle inconsistencies between kernels and modules from becoming a random, impossible to track problem.
CONFIG_MODVERSION (Loadable module support -> Set version information on all module symbols)
The following option should usually be selected. It allows the kernel to automatically load any required modules, meaning that manual handling is rarely required. The rest of this section can likely be ignored.
CONFIG_KMOD (Loadable module support -> Kernel module loader)
Loading a module:
This is the basic method for loading a module.
# insmod whiteheat
This will attempt to find the whiteheat module in a number of default locations. If it can’t be located, you can specify the module directly:
# insmod {path_to_module}/whiteheat.o
Unloading a module:
This is the basic method for unloading a module.
# rmmod whiteheat
Listing the loaded modules:
This is displays a list of the modules that are currently loaded, and some statistics about them.
# lsmod
Advanced module loading:
If you’ve configured a number of drivers as modules, they may depend on each other. In this case you’d have to load them one by one in the correct order. Fortunately there’s a command that does this for you.
# modprobe whiteheat
This will determine what other modules are required (like the USB serial layer module and a host controller driver module), and load them first, then load the WhiteHEAT module.
Troubleshooting
The following error messages are spurious and may be ignored:
uhci.c: : host controller halted. very bad
usb.c: USB device (vend/prod) 0x710/0x1 is not claimed by any active driver.