Man Linux: Main Page and Category List


       fxload - Firmware download to EZ-USB devices


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


       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.


       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.


       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-

       -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

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


       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.


       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


              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.




       Linux Hotplugging Project

                                September 2008