TI USB 3410/5052 Linux Driver Package ti_usb_ibm-1.0.tgz ti_usb_ibm-1.0-3.src.rpm 1/26/05 CONTENTS 1. Introduction 2. Installation 3. Enhancements and Bug Fixes 4. Known Limitations 5. Vendor and Product Ids 6. Device Files 7. Major Numbers 8. Reserve Ports 1. INTRODUCTION These tgz and source RPM packages contains a device driver for the TI USB 3410 and 5052 evaluation boards in the Linux 2.4 kernels. This package is designed for these hardware platforms: - Standard PC with i486, Pentium, or compatible cpus (32 bit x86) This package has been tested on these Linux distributions: - Red Hat 8.0 - Red Hat 9.0 - SUSE Linux Standard Server 8.0 Most likely this package will work on many other Linux distributions based on the 2.4 kernels, but this has not yet been tested. Note that different distributions can make custom changes to the Linux kernel, and there is a small chance that these changes might be incompatible with this package. This package will not work in the Linux 2.6 kernels. Separate packages of the TI USB 3410/5052 driver are available for the Linux 2.6 kernels. These packages are available from http://www.brimson.com/downloads The tgz package will be named ti_usb-X.Y.tgz, and the source RPM package will be named ti_usb-X.Y-Z.src.rpm, where X.Y-Z is the version number. See www.brimson.com/downloads/README for a description of the packages available. If you have questions or problems with this package please contact TI technical support, Al Borchers, alborchers@steinerpoint.com, or Peter Berger, pberger@brimson.com. 2. INSTALLATION Install the Kernel Sources To build the TI USB driver you must have the matching kernel sources for your kernel. To verify that you have matching kernel sources, run "uname -r" to get the version of the running kernel. Then check for the directory /usr/src/linux-, /lib/modules//source, /lib/modules//build, or /usr/src/linux-, where stripped_version has the extra version information removed. In these directories look for the files include/linux/autoconf.h and .config. If you do not find the correct kernel source directory, you must find and install the kernel sources from your distribution CDs or other media. Prepare the Kernel Sources This step may or may not be necessary, depending on how your Linux distribution installs the kernel sources. Log in as root and do the following: Command Explanation -------------------------------------------------------------- 1. cd /usr/src/linux- Change to the source directory. 2. make mrproper Clean up any old files. 3. Make a configuration file to match your running kernel. Use either... make oldconfig For Red Hat. --OR-- make cloneconfig For SUSE. For other distributions these same commands might work, or you might need to find a config file in /boot or in a configs directory, copy it to .config, and run "make oldconfig". 4. make dep Create the dependency and version files. If you have built your own kernel, the kernel sources will already be installed and prepared. If you are using a kernel that came with a Linux distribution, it can sometimes be difficult to get the kernel sources correctly installed and prepared, since each Linux distribution handles kernel sources slightly differently. For example, if you get errors about the wrong kernel version, you may have installed the wrong kernel sources, or you may need to edit the kernel version in the top level Makefile of the kernel sources. If you get compilation errors, perhaps you forgot to run "make oldconfig" and "make dep". If you have difficulties, look carefully at the error messages when installing the TGZ or RPM packages--those messages should give you an indication of just what the error is. Build and Install the TI USB Driver from the Source RPM Package Follow this step if your distribution supports RPM packages; otherwise, follow the next step on installing from a TGZ package. You will need the TI USB source RPM package for this step. The Introduction section above describes where to find the latest TI USB source RPM. Log in as root and do the following: Command Explanation -------------------------------------------------------------- 1. rpmbuild --rebuild ti_usb-X.Y-Z.src.rpm For Red Hat. --OR-- rpm --rebuild ti_usb-X.Y-Z.src.rpm For SUSE. Build the driver package for your kernel. 2. cd /usr/src/redhat/RPMS/i386 For Red Hat. --OR-- cd /usr/src/packages/RPMS/i386 For SUSE. Or use the appropriate path for your distribution. 3. rpm -Uvh ti_usb-X.Y-Z.i386.rpm Install the driver package. If there are problems in this process, you may need to go back to install and prepare the kernel sources as described above. You man need to remove the RPM package with "rpm -e ti_usb-X.Y-Z" or remove RPM temporary files. Red Hat stores RPM temporary files in /var/tmp and /usr/src/redhat/BUILD; other distributions may store them in other places. Build and Install the TI USB Driver from the TGZ Package You will need the TI USB tgz package for this step. The Introduction section above describes where to find the latest TI USB tgz package. Log in as root and do the following: Command Explanation -------------------------------------------------------------- 1. tar xvzf ti_usb-X.Y.tgz Un-package the files. 2. cd ti_usb-X.Y 3. ./configure Configure the package for your distribution and kernel. 4. make Build the driver. 5. make install Install the ti_usb driver. If there are problems in this process, you may need to go back to install and prepare the kernel sources as described above. Load the TI USB Driver The ti_usb driver should be automatically loaded when you plug in the TI USB 3410 device, provided your device uses the default vendor and product ids. If it does not, see the section below titled "VENDOR and PRODUCT IDS". The first TI USB 3410 device plugged in will appear as /dev/ttyTIUSB0, then next as /dev/ttyTIUSB1, and so on. Note that these device names are different from the device names used by the Linux usbserial driver--see the section below titled "DEVICE FILES" for more information. If TI USB devices had been in use before installing the new TI USB driver, old versions of the drivers will still be loaded. These old versions must be unloaded before the newly installed driver will be used. The simplest way to unload the old drivers and load the new is to reboot. Alternatively, you can close all open TI USB serial ports, disconnect the TI USB serial devices, and then unload the old TI USB serial driver with the command rmmod ti_usb Then reconnect the TI USB serial devices and the new driver will be loaded. Uninstall the TI USB Driver If you installed the TI USB RPM package, you can uninstall it by logging in as root and running the command rpm -e ti_usb-X.Y-Z If you installed the TI USB TGZ package, you can uninstall it by logging in as root and running the commands cd ti_usb-X.Y (You will need to give a full or relative path to the unpacked source file directory.) make uninstall 3. ENHANCEMENTS and BUG FIXES Version 1.0 - Improved the documentation about installing and preparing the kernel sources. Version 0.9 - The state of DTR and RTS is maintained even when changing the serial settings (baud rate, data bits, stop bits, parity, and flow control). In version 0.8 DTR and RTS were reasserted when the serial settings were changed. Version 0.8 - Now available as a source RPM as well as a TGZ package. - Added set/clear DTR and RTS. - Added support for break signals. - Added support for baud rate 0 hangup. Version 0.7 - 5052/5152 support was added. The 5052 firmware is from 9/18/04. - Switched from hotplug to a /etc/modules.conf post-install command to create the device files. - Vendor and product ids can be specified when the module is loaded. Included instructions in the release notes on how to modify the sources to support different vendor and product ids, too. - Added the "major" module parameter to set an explicit major number. - The driver should now build in the 2.4.19 Linux kernel. (Not tested.) Version 0.6 - The driver downloads the firmware version from 9/10/04 to the device. - Improved the way received data is sent to the Linux tty subsystem. With low_latency off, this eliminates the lost/corrupted data problem seen in earlier versions. - Low latency is now off by default. - Added low_latency and closing_wait module parameters, for systems like SUSE that do not have setserial. - Added the reserve ports module parameter, to reserve device files for devices by vendor/product, serial number, or USB device path. (See the section below on Reserve Ports.) Version 0.5 - Added support for devices with EEPROMS installed. EEPROMS programmed with firmware should use a firmware version from 9/8/04 or later. See below for more information. - The driver now handles device disconnects much better, even if a port is open. Disconnect was tested with SUSE Standard Server 8.0 with a 2.4.21 kernel using both UHCI and OHCI USB host controller drivers, and no problems were seen. However, there may still be problems with disconnect in other contexts or with other Linux kernel versions. - Added setserial support for low_latency and closing_wait. Setserial correctly reports the line and port numbers. Other setserial options are not supported, since most do not apply. - Close waits for data to drain. Note however, that the maximum closing wait defaults to 40 seconds, and this might not be long enough for data rates below 300 bps. You can use setserial to increase the maximum closing wait time. - Open purges input and output buffers on the device. - Hardware and software flow control have been improved. Hardware flow control prevents data loss at up to 115200 bps (the maximum data rate currently supported). Software flow control is not fast enough to prevent data loss at high rates, however. - The driver downloads the firmware version from 9/8/04 to the device. - Other bug fixes and improvements. - Source code clean up. Version 0.3 - Renamed the driver ti_usb. - Removed all dependencies on usbserial. - Added hotplug script to create device nodes when the driver is loaded. Version 0.2 - Fixed outgoing software flow control. Version 0.1 - First release of the driver, open, close, read, write, hardware flow control, and incoming software flow control are working. 4. KNOWN LIMITATIONS - EEPROMS with firmware already programmed will only work with Linux if the firmware is from 9/8/04 or later for the 3410 and from 9/18/04 or later for the 5052. The patch file ti_usb_eeprom_firmware.patch included in this distribution can be applied to your kernel to allow it to work with earlier firmware. The patch is for Linux 2.4.27; it might or might not apply to other kernel versions. - There is a memory leak of less than 100 bytes each time firmware is downloaded to a 3410 device. Downloading firmware changes the USB descriptors and the old descriptors are not freed. - If the port is software flow controlled when it is closed, it will remain flow controlled when it is re-opened. The port must be re-opened, re-configured for software flow control, and a control-Q must be sent to the port to restart output. This is a firmware problem. - The TI USB devices always drop DTR on close. This behavior cannot be changed by turning off hang-up on close (HUPCL); HUPCL is always in effect and cannot be turned off. 5. VENDOR and PRODUCT IDS The ti_usb driver is built to use the default vendor id 0x0451 and the default product id 0x3410 for the TIUSB3410 and 0x5052, 0x5152, 0x505A, and 0x505F for the TIUSB5052/5152. If your device uses different product ids you must either specify the vendor and product ids when you load the ti_usb module or compile the vendor and product ids into the ti_usb module. The second solution is a bit more work, but allows the ti_usb driver to be loaded automatically when you plug in your device. Suppose you have a 3410 based device with vendor id 0x1234 and with a product id before firmware download of 0x1111 and after firmware download of 0x2222. Specifying the Vendor and Product Ids When Loading ti_usb You would load the ti_usb module with this command, either entered by hand or in a startup script, modprobe ti_usb vendor_3410=0x1234,0x1234 product_3410=0x1111,0x2222 Note that you must have the same number of vendor and product ids. Even if the vendor id is the same, you must list it once for each product id. Alternatively, you could add this line to /etc/modules.conf add options ti_usb vendor_3410=0x1234,0x1234 product_3410=0x1111,0x2222 But you would still need to load the ti_usb module by hand or in a startup script with the command modprobe ti_usb Specifying the vendor and product ids when loading the module requires that you explicitly load the module by hand or in a startup script. The module cannot be loaded automatically by Linux when you plug in the device, because Linux does not know what vendor and product ids are used by the device. If you have a 5052 based device, then the module parameters are "vendor_5052" and "product_5052". Compiling the Vendor and Product Ids into ti_usb (These instructions assume you are using the TGZ package; it is possible to do this with the RPM package, but more complicated.) In the ti_usb_X.Y/src directory, edit the file ti_usb_3410_5052.c. Find these lines near the top of the file static struct usb_device_id ti_id_table_3410[1+TI_EXTRA_VID_PID_COUNT+1] = { { USB_DEVICE(TI_VENDOR_ID, TI_3410_PRODUCT_ID) }, }; ... static __devinitdata struct usb_device_id ti_id_table_combined[] = { { USB_DEVICE(TI_VENDOR_ID, TI_3410_PRODUCT_ID) }, { USB_DEVICE(TI_VENDOR_ID, TI_5052_BOOT_PRODUCT_ID) }, { USB_DEVICE(TI_VENDOR_ID, TI_5152_BOOT_PRODUCT_ID) }, { USB_DEVICE(TI_VENDOR_ID, TI_5052_EEPROM_PRODUCT_ID) }, { USB_DEVICE(TI_VENDOR_ID, TI_5052_FIRMWARE_PRODUCT_ID) }, { } }; and change them to be static struct usb_device_id ti_id_table_3410[3+TI_EXTRA_VID_PID_COUNT+1] = { { USB_DEVICE(TI_VENDOR_ID, TI_3410_PRODUCT_ID) }, { USB_DEVICE(0x1234, 0x1111) }, { USB_DEVICE(0x1234, 0x2222) }, }; ... static __devinitdata struct usb_device_id ti_id_table_combined[] = { { USB_DEVICE(TI_VENDOR_ID, TI_3410_PRODUCT_ID) }, { USB_DEVICE(TI_VENDOR_ID, TI_5052_BOOT_PRODUCT_ID) }, { USB_DEVICE(TI_VENDOR_ID, TI_5152_BOOT_PRODUCT_ID) }, { USB_DEVICE(TI_VENDOR_ID, TI_5052_EEPROM_PRODUCT_ID) }, { USB_DEVICE(TI_VENDOR_ID, TI_5052_FIRMWARE_PRODUCT_ID) }, { USB_DEVICE(0x1234, 0x1111) }, { USB_DEVICE(0x1234, 0x2222) }, { } }; Notice that the array dimension on the ti_id_table_3410 array has been changed from "1+TI_EXTRA_VID_PID_COUNT+1" to "3+TI_EXTRA_VID_PID_COUNT+1" to make room for the two new vendor/product ids. Then as root in the ti_usb_X.Y directory run these commands make make install This will build and install the new driver with your vendor and product ids compiled in. Once your vendor and product ids are compiled in, Linux will automatically load the ti_usb driver when your device is connected. If you have a 5052 based device, then edit the ti_id_table_5052 instead of the ti_id_table_3410. Otherwise, the changes are similar. 6. DEVICE FILES Because the the TI USB driver does not use usbserial (to avoid known problems with usbserial) it uses its own device file names, /dev/ttyTIUSB0, /dev/ttyTIUSB1, and so on. The device files are created automatically when the ti_usb driver is loaded. This is done by the module post-install command in /etc/modules.conf, which runs the script /etc/ti_usb/make_devices. You can change the device names that ti_usb uses. First you should remove the old device files by running /etc/ti_usb/make_devices remove Then edit /etc/ti_usb/make_devices. At the top of this file you will find the parameters DEVICE_NAME which determines the basename of the TI USB device files, DEVICE_COUNT which determines the number of device files created, DEVICE_GROUP which determines the group owner of the device files, and DEVICE_PERMISSIONS which determines the device file permissions. For example, to create 8 TI USB device files named /dev/ttyusb0 through /dev/ttyusb7, owned by the uucp group, and having permissions 0660, change the parameters like this DEVICE_NAME=/dev/ttyusb DEVICE_COUNT=8 DEVICE_GROUP=uucp DEVICE_PERMISSIONS=0660 After editing make_devices, run the script to create the new device files, like this /etc/ti_usb/make_devices If you use devfs, the ti_usb devices will be /dev/usb/ti/0, /dev/usb/ti/1, and so on in the order they are plugged in. The ti_usb driver has has not been tested with devfs. 7. MAJOR NUMBERS The ti_usb driver uses dynamically assigned major numbers by default. That is why the /etc/modules.conf post-install command is used to create the device files: the major number is not know until after the driver is loaded. However, you can set the major number used by the ti_usb driver with the "major" module parameter. For example, to use major number 127, add this line to the /etc/modules.conf file: add options ti_usb major=127 8. RESERVE PORTS The ti_usb driver can explicitly assign device files to TI USB serial converters based on vendor id, product id, serial number, or USB device path. Without reserve ports, device files are assigned to devices based on the order the devices are connected or the order they are enumerated on boot up. The first port of the first device connected or enumerated is assigned to /dev/ttyTIUSB0, the next port to /dev/ttyTIUSB1, and so on. The "reserve_ports" module parameter to the ti_usb driver controls how device files are assigned to devices. This parameter is an array of strings, one for each TI USB device file, beginning at /dev/ttyTIUSB0 and continuing on up. The string is a pattern that reserves the port for a particular device by vendor/product id, by serial number, or by USB device path. Syntax Initially the strings NULL for all ports, and these NULL strings leave the port available for any device. The first character of the string determines the type of the pattern: V -- vendor/product id S -- serial number D -- device path ^ -- this port is available for a multiport device that matched the previous pattern - -- this port is not available for any device * -- this port is available for any device The rest of the string is interpreted according to the first character: Vendor/Product ID The vendor/product ids are two hex numbers separated by a ":" or "/". Either number can be replaced by a "*" as a wildcard to match any vendor or product id. The vendor and product ids should not have "0x" at the beginning. The TI USB serial converters all have vendor id 0x0451. The product id is 0x3410 for the 3410 and 0x5052 for the 5052. Serial Number The serial number is an ASCII string that is matched against the serial number reported by the device. An "*" can be used at the beginning or end of this string as a wildcard to match the beginning or ending of any serial number. The serial number of a device is logged by ti_usb to "/var/log/messages" when the device is connected, or it can be found by running "lsusb -v" when the device is connected. Device Path The device path is a "/" separated path of decimal integers. The first integer is the bus number, the rest are the USB port numbers of sequence of hubs leading to the device. Any integer in the path can be replaced by a "*" as a wildcard to match any port. For example, a device path like "D1/2/3" means the device attached to the 3rd port on the hub attached to the 2nd port on the virtual hub on bus 1. When the device is connected, you can use "lsusb -t" to print out the bus and device numbers of the path to the device. The reserve_ports module parameter can be given on the insmod or modprobe command line, or it can be given in the /etc/modules.conf file, like this add options ti_usb 'reserve_ports=V0451:5052,^,S00000001,D1/2/*'