1FXLOAD(8)                  Linux Programmer's Manual                 FXLOAD(8)
2
3
4

NAME

6       fxload - Firmware download to EZ-USB devices
7

SYNOPSIS

9       fxload [ -v ] [ -D devpath ] [ -I hexfile ] [ -t type ] [ -c config ] [
10       -s loader ]
11       fxload [ -D devpath ] [ -L link ] [ -m mode ]
12       fxload [ -V ]
13

DESCRIPTION

15       fxload is a program which downloads firmware to USB  devices  based  on
16       AnchorChips  EZ-USB, Cypress EZ-USB FX, or Cypress EZ-USB FX2 microcon‐
17       trollers.  These have 8-bit 8051 cores with special extensions for  USB
18       I/O.   The  FX2 supports high speed USB 2.0 transfers (480 Mbit/sec) as
19       well as full speed USB 1.1 transfers (12 Mbit/sec), while  the  earlier
20       parts  supports only full speed transfers.  These controllers have sev‐
21       eral package options, and can be set up with external  memory  (on-chip
22       memory is usually about 8K), EEPROMs, and ROMs when device costs allow.
23
24       This  uses  "usbfs"  (older  name:   "usbdevfs") to access devices, and
25       issues vendor specific control requests to download and reset  the  EZ-
26       USB  devices.  Normally, firmware will then "renumerate" by disconnect‐
27       ing from USB and then reconnecting as a new device.   It  then  appears
28       with  new  device  descriptors  and  functionality,  as provided by the
29       firmware which has been downloaded.
30
31       To support some non-firmware applications, this can also  set  up  sym‐
32       bolic  links  for  those  usbfs names.  It can also change their access
33       modes.  Both of these can help simplify software applications that need
34       to  talk to USB devices using user mode drivers, don't want to run with
35       privileges or to examine all of the existing  USB  devices,  and  which
36       don't need more kernel drivers.
37
38       See  the Linux-Hotplug web site for information about how to use fxload
39       to download device firmware when hotplugging USB devices, using driver-
40       specific scripts stored in the /etc/hotplug/usb directory.
41

FUNCTION LETTERS

43       At  least one of the following options must be specified.  Note that as
44       usual with UNIX and Linux commands, the order of command  option  flags
45       does not matter.  You may use these in any order.
46
47       -I hexfile
48              Downloads  the  specified  firmware file.  This firmware is pro‐
49              vided in standard Intel hexfile format.  (Common naming  conven‐
50              tions  include  *.hex  and  *.ihx.)  Depending on the device and
51              firmware in use, the -s option may also be necessary to  specify
52              a  second  stage loader.  Firmware is normally downloaded to RAM
53              and executed, but there is also an option for  downloading  into
54              bootable I2C EEPROMs.
55
56       -L link
57              Creates  the  specified  symbolic link to the usbfs device path.
58              This would typically be used to create a  name  in  a  directory
59              that  would be searched by an application.  The symlink would be
60              removed by some other component on device unplug.
61
62       -m mode
63              Changes permissions on the "usbfs"  device  node.   By  default,
64              those  nodes  are  only  accessible  by  privileged users, which
65              doesn't help when the user mode device driver needs to run with‐
66              out  root  privileges.   Note that usbfs mount options like dev‐
67              mode=0666 are also available.
68
69       -V     Identifies the version of fxload being invoked, and exits  with‐
70              out performing other actions.
71
72       Note  that when downloading firmware that renumerates, there's no point
73       in changing the device permissions or creating a symbolic link.
74

OPTIONS

76       By default, fxload assumes the device uses an EZ-USB or EZ-USB FX.   It
77       also assumes that the device in question has been specified by USB ker‐
78       nel hotplugging conventions, using the DEVICE environment  variable  to
79       name a "usbfs" file that can be used to talk to the device.
80
81       -c config
82              Indicates  the specified firmware should be downloaded to an I2C
83              boot EEPROM rather than to RAM.  The parameter is the EZ-USB  FX
84              or FX2 configuration byte, and for AnchorChips devices the value
85              should be zero.  This requires a second stage loader that  knows
86              how  to  write  to I2C EEPROMs specified using the -s option, as
87              well as a device that's provided with an EEPROM large enough  to
88              store  the  boot firmware.  After downloading to a device's EEP‐
89              ROM, you should retest it starting from power off.
90
91       -s loader
92              This identifies the hex file holding a second stage  loader  (in
93              the  same  hex  file  format  as  the firmware itself), which is
94              loaded into internal memory.  This loader understands additional
95              vendor  control  requests,  beyond the one built into all EZ-USB
96              hardware, which are needed to write external RAM or EEPROM.   As
97              a  last  step  when loading firmware, fxload normally overwrites
98              this second stage loader with parts of the firmware residing on-
99              chip.
100
101       -t type
102              Indicates  which  type of microcontroller is used in the device;
103              type may be one of an21 (the original AnchorChips  devices),  fx
104              (Cypress'  updated  version, the EZ-USB FX), or fx2 (the Cypress
105              EZ-USB FX2, supporting high speed transfers).  Except when writ‐
106              ing  to  EEPROM,  all  that  normally  matters  when downloading
107              firmware is whether or not the device uses an FX2.
108
109       -v     Prints some diagnostics, such as download addresses  and  sizes,
110              to  standard  error.   Repeat  the  flag (-vv, -vvv) to get more
111              diagnostics.
112
113       -D devpath
114              Specifies the "usbfs" path name for the device in question, such
115              as /proc/bus/usb/004/080.  This takes precedence over any DEVICE
116              environment variable that may be set.
117

NOTES

119       This program implements one extension to the standard "hex  file"  for‐
120       mat.  Lines beginning with a "#" character are ignored, and may be used
121       to hold copyright statements and other information.   Other  tools  may
122       not handle hexfiles using this extension.
123
124       At  this writing, "usbfs" is a kernel configuration option.  That means
125       that device drivers relying on user mode firmware downloading may  need
126       to  depend  on  that  kernel  configuration  option.  A less preferable
127       alternative involves compiling the firmware into the kernel and  manag‐
128       ing  downloads and renumeration there.  This is less preferable in part
129       because much device firmware is provided with GPL-incompatible  licens‐
130       ing,  and  in part because storing such firmware firmware wastes kernel
131       memory.
132
133       For EZ-USB family devices, the hardware's first stage loader  (support‐
134       ing the 0xA0 vendor request) can't write into external memory.  Config‐
135       urations that put firmware into external  memory  thus  need  a  second
136       stage  loader.   For typical "flat" memory architectures, a loader sup‐
137       porting the 0xA3 vendor request is used  to  write  into  that  memory.
138       Similarly,  a second stage loader that supports the 0xA2 vendor request
139       is needed when writing boot firmware into an I2C  EEPROM.   These  0xA2
140       and  0xA3  vendor commands are conventions defined by Cypress.  Devices
141       that use bank switching or similar mechanisms to  stretch  the  64KByte
142       address space may need different approach to loading firmware.
143
144       Not  all  devices  support  EEPROM  updates.  Some EZ-USB based devices
145       don't have an I2C EEPROM; many such EEPROMs  are  too  small  to  store
146       firmware; and some firmware can't be placed in bootable I2C EEPROMs.
147

ENVIRONMENT VARIABLES

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

SEE ALSO

154       hotplug(8)
155

AUTHORS

157       Linux Hotplugging Project http://linux-hotplug.sourceforge.net/
158
159
160
161                                  April 2002                         FXLOAD(8)
Impressum