            TI USB 3410/5052 Linux Driver Package

                      ti_usb-1.1.tgz
                      ti_usb-1.1-1.src.rpm

                          3/17/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-<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
   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-<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 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.1

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

  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/*'
