fxload

FXLOAD(8)                  Linux Programmer's Manual                 FXLOAD(8)



NAME
       fxload - Firmware download to EZ-USB devices

SYNOPSIS
       fxload [ -v ] [ -D devpath ] [ -I hexfile ] [ -t type ] [ -c config ] [
       -s loader ]
       fxload [ -D devpath ] [ -L link ] [ -m mode ]
       fxload [ -V ]

DESCRIPTION
       fxload is a program which downloads firmware to USB devices based on
       AnchorChips EZ-USB, Cypress EZ-USB FX, or Cypress EZ-USB FX2
       microcontrollers.  These have 8-bit 8051 cores with special extensions
       for USB I/O.  The FX2 supports high speed USB 2.0 transfers (480
       Mbit/sec) as well as full speed USB 1.1 transfers (12 Mbit/sec), while
       the earlier parts supports only full speed transfers.  These
       controllers have several package options, and can be set up with
       external memory (on-chip memory is usually about 8K), EEPROMs, and ROMs
       when device costs allow.

       This uses "usbfs" (older name:  "usbdevfs") to access devices, and
       issues vendor specific control requests to download and reset the EZ-
       USB devices.  Normally, firmware will then "renumerate" by
       disconnecting from USB and then reconnecting as a new device.  It then
       appears with new device descriptors and functionality, as provided by
       the firmware which has been downloaded.

       To support some non-firmware applications, this can also set up
       symbolic links for those usbfs names.  It can also change their access
       modes.  Both of these can help simplify software applications that need
       to talk to USB devices using user mode drivers, don't want to run with
       privileges or to examine all of the existing USB devices, and which
       don't need more kernel drivers.

       See the Linux-Hotplug web site for information about how to use fxload
       to download device firmware when hotplugging USB devices, using driver-
       specific scripts stored in the /etc/hotplug/usb directory.

FUNCTION LETTERS
       At least one of the following options must be specified.  Note that as
       usual with UNIX and Linux commands, the order of command option flags
       does not matter.  You may use these in any order.

       -I hexfile
              Downloads the specified firmware file.  This firmware is
              provided in standard Intel hexfile format.  (Common naming
              conventions include *.hex and *.ihx.)  Depending on the device
              and firmware in use, the -s option may also be necessary to
              specify a second stage loader.  Firmware is normally downloaded
              to RAM and executed, but there is also an option for downloading
              into bootable I2C EEPROMs.

       -L link
              Creates the specified symbolic link to the usbfs device path.
              This would typically be used to create a name in a directory
              that would be searched by an application.  The symlink would be
              removed by some other component on device unplug.

       -m mode
              Changes permissions on the "usbfs" device node.  By default,
              those nodes are only accessible by privileged users, which
              doesn't help when the user mode device driver needs to run
              without root privileges.  Note that usbfs mount options like
              devmode=0666 are also available.

       -V     Identifies the version of fxload being invoked, and exits
              without performing other actions.

       Note that when downloading firmware that renumerates, there's no point
       in changing the device permissions or creating a symbolic link.

OPTIONS
       By default, fxload assumes the device uses an EZ-USB or EZ-USB FX.  It
       also assumes that the device in question has been specified by USB
       kernel hotplugging conventions, using the DEVICE environment variable
       to name a "usbfs" file that can be used to talk to the device.

       -c config
              Indicates the specified firmware should be downloaded to an I2C
              boot EEPROM rather than to RAM.  The parameter is the EZ-USB FX
              or FX2 configuration byte, and for AnchorChips devices the value
              should be zero.  This requires a second stage loader that knows
              how to write to I2C EEPROMs specified using the -s option, as
              well as a device that's provided with an EEPROM large enough to
              store the boot firmware.  After downloading to a device's
              EEPROM, you should retest it starting from power off.

       -s loader
              This identifies the hex file holding a second stage loader (in
              the same hex file format as the firmware itself), which is
              loaded into internal memory.  This loader understands additional
              vendor control requests, beyond the one built into all EZ-USB
              hardware, which are needed to write external RAM or EEPROM.  As
              a last step when loading firmware, fxload normally overwrites
              this second stage loader with parts of the firmware residing on-
              chip.

       -t type
              Indicates which type of microcontroller is used in the device;
              type may be one of an21 (the original AnchorChips devices), fx
              (Cypress' updated version, the EZ-USB FX), or fx2 (the Cypress
              EZ-USB FX2, supporting high speed transfers).  Except when
              writing to EEPROM, all that normally matters when downloading
              firmware is whether or not the device uses an FX2.

       -v     Prints some diagnostics, such as download addresses and sizes,
              to standard error.  Repeat the flag (-vv, -vvv) to get more
              diagnostics.

       -D devpath
              Specifies the "usbfs" path name for the device in question, such
              as /proc/bus/usb/004/080.  This takes precedence over any DEVICE
              environment variable that may be set.

NOTES
       This program implements one extension to the standard "hex file"
       format.  Lines beginning with a "#" character are ignored, and may be
       used to hold copyright statements and other information.  Other tools
       may not handle hexfiles using this extension.

       At this writing, "usbfs" is a kernel configuration option.  That means
       that device drivers relying on user mode firmware downloading may need
       to depend on that kernel configuration option.  A less preferable
       alternative involves compiling the firmware into the kernel and
       managing downloads and renumeration there.  This is less preferable in
       part because much device firmware is provided with GPL-incompatible
       licensing, and in part because storing such firmware firmware wastes
       kernel memory.

       For EZ-USB family devices, the hardware's first stage loader
       (supporting the 0xA0 vendor request) can't write into external memory.
       Configurations that put firmware into external memory thus need a
       second stage loader.  For typical "flat" memory architectures, a loader
       supporting the 0xA3 vendor request is used to write into that memory.
       Similarly, a second stage loader that supports the 0xA2 vendor request
       is needed when writing boot firmware into an I2C EEPROM.  These 0xA2
       and 0xA3 vendor commands are conventions defined by Cypress.  Devices
       that use bank switching or similar mechanisms to stretch the 64KByte
       address space may need different approach to loading firmware.

       Not all devices support EEPROM updates.  Some EZ-USB based devices
       don't have an I2C EEPROM; many such EEPROMs are too small to store
       firmware; and some firmware can't be placed in bootable I2C EEPROMs.

ENVIRONMENT VARIABLES
       DEVICE normally names a "usbfs" file that will be used to talk to the
              device.  This is provided by the Linux kernel as part of USB
              hotplugging.

FILES
       /usr/share/usb/a3load.hex
              Second stage loader that works with AnchorChips EZ-USB, Cypress
              EZ-USB FX, and Cypress EZ-USB FX2.  Note that this only supports
              the 0xA3 vendor command, to write external memory.  A loader
              that also supports the 0xA2 command, to write boot EEPROMs, is
              included with Cypress developer kits.

SEE ALSO
       hotplug(8)

AUTHORS
       Linux Hotplugging Project http://linux-hotplug.sourceforge.net/



                                  April 2002                         FXLOAD(8)