NAME

       fxload - Firmware download to EZ-USB devices

SYNOPSIS

       fxload [ -v ] [ -l ] [ -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/FX2LP 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 8K or 16K), 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
              (e.g.  vend_ax.hex)  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), or fx2lp
              (the Cypress EZ-USB FX2LP, with 16KB internal RAM).  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.

       -l     print error and verbose messages to syslog.

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

                                          September 2008                                FXLOAD(8)