TI USB 3410/5052 Linux Driver Package ti_usb-0.6-1.tgz 09/12/04 CONTENTS 1. Introduction 2. Installation 3. Enhancements and Bug Fixes 4. Known Limitations 5. Device Names 6. Reserve Ports 1. INTRODUCTION This tgz package contains a device driver for the TI USB 3410 evaluation board in the Linux 2.4 kernels. The TI USB 5052 evaluation boards are not yet supported by this driver. 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 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. Support for the 2.6 kernels is in progress. This tgz package is available from http://www.brimson.com/downloads The tgz package will be named ti_usb-X.Y-Z.tgz, 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, or Peter Berger, pberger@brimson.com, or Al Borchers, alborchers@steinerpoint.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. 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. Build and Install the TI USB Driver 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-Z.tgz Un-package the files. 2. cd ti_usb-X.Y-Z 3. ./configure Configure the package for your distribution and kernel. 4. make Build the driver. 5. make install Install the ti_usb driver. Uninstall Usbserial from Version 0.2 of the TI USB Drivers If you have version 0.2 of the TI USB Drivers installed, and you installed the alternate usbserial driver included with that package, you should uninstall it. Log in as root and do the following: Command Explanation -------------------------------------------------------------- 1. cd ti_usb-0.2-1 You must give the full or relative path to this directory, which was created when you installed the version 0.2 TI USB drivers. 2. make uninstall_usbserial This will restore the original version of usbserial. Load the TI USB Drivers The ti_usb driver should be automatically loaded when you plug in the TI USB 3410 device, using the Linux hotplug system. 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 on device names below for more information, including instructions for configuring your system to share the /dev/ttyUSB device names between ti_usb and usbserial. If TI USB devices had been plugged in before installing the new TI USB driver, old versions of the drivers may 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. If you are still running drivers from the 0.2-1 version of the TI USB package, then you should reboot. Alternatively, you can close all open USB serial ports on all USB serial devices, disconnect all USB serial devices, and then unload the 0.2-1 TI USB serial drivers with the command rmmod ti_3410_5052 usbserial Then reconnect the TI USB serial devices and the new driver will be loaded. 3. ENHANCEMENTS and BUG FIXES 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 - Only the 3410 is supported. - EEPROMS with firmware already programmed will only work with Linux if the firmware is from 9/8/04 or later. 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 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 most likely a firmware problem. - Data rates above 115200 bps are not supported. - Baud rate 0 to drop the modem control lines is not yet supported. - Hang-up on close (HUPCL) to hold DTR low on close is not yet supported. - Direct control of RTS and DTR is not yet supported. - Some other minor serial port features have not been tested or are not yet supported. 5. Device Names Because the the TI USB driver does not use usbserial (to avoid known problems with usbserial) it uses its own device names, /dev/ttyTIUSB0, /dev/ttyTIUSB1, and so on. You can change the device names that ti_usb uses by logging in as root and doing the following: Command Explanation -------------------------------------------------------------- 1. cd ti_usb-X.Y-Z You will need to give the full or relative path to this directory 2. make ti_usb_devices DEVICE_NAME=/dev/MYNAME MYNAME can be replace with any name you want. 3. (unload and reload the ti_usb driver, as described above) In addition to changing the name, you can also use the process above to change how many device files are created with DEVICE_COUNT (by default 16), what starting port number to use with DEVICE_START (by default 0), and the device permissions with DEVICE_PERMISSIONS (by default 0600). You can also configure your system so that the ti_usb driver shares the /dev/ttyUSB devices with usbserial. For example, the following procedure will configure your system so that /dev/ttyUSB0 through /dev/ttyUSB3 are used for TI USB devices and /dev/ttyUSB4 through /dev/ttyUSB19 are used for usbserial devices: Command Explanation -------------------------------------------------------------- 1. cd ti_usb-X.Y-Z You will need to give the full or relative path to this directory 2. make ti_usb_devices DEVICE_NAME=/dev/ttyUSB DEVICE_COUNT=4 Now ti_usb uses /dev/ttyUSB0 through /dev/ttyUSB3. 3. make usbserial_devices DEVICE_START=4 DEVICE_COUNT=16 Now usbserial uses /dev/ttyUSB4 through /dev/ttyUSB19. 4. (unload and reload the ti_usb driver, as described above) 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. 6. 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/*'