            TI USB 3410/5052 Linux Driver Package

                    ti_usb_2.6-1.2.3.tgz
                 ti_usb_2.6-1.2.3-1.src.rpm

                          10/31/07


CONTENTS

   1. Introduction
   2. Installation
   3. Enhancements and Bug Fixes
   4. Known Limitations
   5. Vendor and Product Ids
   6. Hotplug Scripts


1. INTRODUCTION

   These tgz and source RPM packages contains a device driver for the
   TI USB 3410 and 5052 evaluation boards and Multitech modems in the
   Linux 2.6 kernels.

   The TI USB 3410/5052 driver should be included in the official Linux
   kernel in version 2.6.11 or later.  The official Linux kernel does not
   yet have support for the Multitech modems, however.  You should not need
   these packages if you are running a 2.6.11 or later kernel with devices
   other than the Multitech modems.

   These packages have been tested on these Linux distributions:

   - Fedora Core 2

   Most likely these packages will work on many other Linux distributions
   based on the 2.6 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.

   The TI USB 3410/5052 driver has been tested in the kernel.org
   kernels 2.6.5 through a pre-release version of 2.6.10, and in
   the Fedora Core 2 kernels 2.6.5-1.358 and 2.6.9-1.6.  There are
   limitations in kernels before 2.6.8; see the section on Known
   Limitations below.

   These packages will not work in the Linux 2.4 kernels.  Separate
   packages of the TI USB 3410/5052 driver are available for the Linux
   2.4 kernels.

   These packages are available from

     http://www.brimson.com/downloads

   The tgz package will be named ti_usb_2.6-X.Y.tgz, and the source RPM
   package will be named ti_usb_2.6-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 complete matching
   kernel sources for your kernel.

   In particular, you must have the file usb-serial.h for your
   kernel sources.  Sometimes Linux distributions will include
   the kernel headers but not the complete kernel sources, and
   usb-serial.h will be missing.  However, the complete kernel
   sources should still be available as a separate add-on package.

   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-<version>, /lib/modules/<version>/source,
   /lib/modules/<version>/build, or /usr/src/linux-<stripped_version>,
   where stripped_version has the extra version information removed.
   In these directories look for the files include/linux/autoconf.h,
   .config, and drivers/usb/serial/usb-serial.h.

   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-<version> 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 prepare                To prepare the kernel sources for
                                    your machine.

   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 errors about a missing usb-serial.h, you may only have the
   kernel headers installed.  If you have trouble getting the full
   kernel sources installed and prepared, you can copy the correct
   version of usb-serial.h to drivers/usb/serial in the kernel headers
   directory and then the other kernel sources are not needed.

   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 3410/5052 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 3410/5052 source RPM package for this step.
   The Introduction section above describes where to find the latest TI
   USB 3410/5052 source RPM.

   Log in as root and do the following:

        Command                     Explanation
        --------------------------------------------------------------
     1. rpmbuild --rebuild ti_usb_2.6-X.Y-Z.src.rpm    For Red Hat.
          --OR--
        rpm --rebuild ti_usb_2.6-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_2.6-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_2.6-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 3410/5052 Driver from the TGZ Package

   Follow this step if your distribution does not support RPM packages;
   otherwise, follow the previous step on installing from an RPM package.

   You will need the TI USB 3410/5052 tgz package for this step.  The
   Introduction section above describes where to find the latest TI USB
   3410/5052 tgz package.

   Log in as root and do the following:

        Command                     Explanation
        --------------------------------------------------------------
     1. tar xvzf ti_usb_2.6-X.Y.tgz Un-package the files.
     2. cd ti_usb_2.6-X.Y
     3. ./configure                 Configure the package for your
                                    distribution and kernel.
     4. make install                Build and install the
                                    ti_usb_3410_5052 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 3410/5052 Driver

   The ti_usb_3410_5052 driver should be automatically loaded when you
   plug in the TI USB 3410/5052 devices, 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/5052 device plugged in will appear as
   /dev/ttyUSB0, then next as /dev/ttyUSB1, and so on.  These
   device names are shared with other USB serial devices.

   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_3410_5052

   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_2.6-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_2.6-X.Y   (You will need to give a full
                         or relative path to the unpacked
                         directory.)
     make uninstall


3. ENHANCEMENTS and BUG FIXES

  Version 1.2.3

  - A change was made to the MT9234ZBA-USB USB interface code. It used to 
    report class: FF, sub-class: 00 and protocol: 00. This has been changed 
    to report class: 02, sub-class: 00 and protocol: 00.

  Version 1.2.2

  - A problem was found on a Dell PS1950 server where the UHCI USB controller
    (back-side) worked fine, but the EHCI controller (front-side) did not.
    This was related to the URB prematurely timing out. The interval set in 
    the URB was 1 (1/8 msec). This did not allow enough time for proper 
    operation. Changing the URB interval to 8 (guaranteeing at least 1 msec)
    seemed to fix the problem. This appears to be a scheduling issue in the
    EHCI host controller code.
 
  Version 1.2.1
  
  - A problem had been found where removal of the USB cable from the device
    did not properly notify the application layer that a disconnect occurred.
    It was found that the problem was related to USB_SERIAL not performing 
    a tty_hangup when processing the disconnect. This was fixed in 2.6.11. 
    It was possible to move this code into a disconnect routine inside the
    TI USB driver to achieve the same result.

  Version 1.2

  - Added support for Multitech MT9234MU and MT9234ZBA-USB modems.
  
  Version 1.1

  - Added support for Multitech GSM. CDMA, and EDGE modems.  Thanks
    to Dale Martenson of Multi-Tech.

  Version 1.0

  - Improved the search for usb-serial.h in the kernel sources.

  - Improved the documentation about installing and preparing the
    kernel sources.

  Version 0.9

  - This is the first release of the Linux 2.6 version of the TI
    USB 3410/5052 driver.  This version has all of the features
    of the Linux 2.4 version 0.9 TI USB 3410/5052 driver, except
    for the following:

  - In Linux 2.6 the TI USB 3410/5052 driver uses the kernel USB
    serial device driver framework.  So devices are by default
    named /dev/ttyUSB0, /dev/ttyUSB1, and so on, and they are
    shared with other USB serial devices.

  - The reserve ports feature is not implemented in the Linux 2.6
    TI USB 3410/5052 driver.  The udev system provides that
    functionality in Linux 2.6.


4. KNOWN LIMITATIONS
 
  - A 3410 without firmware in EEPROM will only work correctly
    in Linux kernels 2.6.8 and later.  Earlier kernels are unable
    to reset the 3410 after downloading firmware.

  - In kernels before 2.6.6, vendor and product ids given as
    module parameters are limited to values between 0x0000 and
    0x7FFF.  This is a problem in the Linux module parameter
    feature.

  - 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.

  - 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_3410_5052 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_3410_5052 module
   or compile the vendor and product ids into the module.  The second
   solution is a bit more work, but allows the ti_usb_3410_5052 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_3410_5052

     You would load the ti_usb_3410_5052 module with this command, either
     entered by hand or in a startup script,

       modprobe ti_usb_3410_5052 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_3410_5052 vendor_3410=0x1234,0x1234 product_3410=0x1111,0x2222

     But you would still need to load the ti_usb_3410_5052 module by hand
     or in a startup script with the command

       modprobe ti_usb_3410_5052

     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_3410_5052

     (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 the command

       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_3410_5052 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. HOTPLUG SCRIPTS

   The ti_usb_3410_5052 driver needs a hotplug script to work correctly.
   This hotplug script is used to change the device configuration.

   When the driver is installed, a hotplug script is automatically
   installed in /etc/hotplug/usb/ti_usb_3410_5052.

   If the device configuration is not being set properly, you might need a
   slightly different hotplug script, depending on your Linux distribution.
   You can try copying /etc/ti_usb/ti_usb_3410_5052 into /etc/hotplug/usb.
   If that does not work, remove /etc/hotplug/usb/ti_usb_3410_5052 and
   instead copy /etc/ti_usb/ti_usb_3410_5052.hotplug into /etc/hotplug.d/usb.
