Manual Reference Pages - FXLOAD (8)
fxload - Firmware download to EZ-USB devices
[ -v ]
[ -l ]
[ -B backend]
[ -D devpath ]
[ -I firmware ]
[ -t type ]
[ -c config ]
[ -s loader ]
[ -D devpath ]
[ -L link ]
[ -m mode ]
[ -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/FX3 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 support only full speed transfers.
The FX3 supports super speed USB 3.0 transfers and has a 32-bit
These controllers have several package options,
and can be set up with external memory (on-chip memory is
usually 8K or 16K; for FX3, it is 512K), 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,
dont want to run with privileges or to examine all of the
existing USB devices,
and which dont need more kernel drivers.
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
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.
Note that when downloading firmware that renumerates,
theres no point in changing the device permissions
or creating a symbolic link.
-I firmware |
Downloads the specified firmware file.
For FX3 devices, the format is a Cypress-specific binary image.
For other devices, the file has standard Intel hexfile format.
(Common naming conventions include
*.ihx , and
*.img). 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 doesnt help when the user mode device driver
needs to run without root privileges.
Note that usbfs mount options like
devmode=0666 are also available.
Identifies the version of fxload being invoked, and exits
without performing other actions.
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 thats provided with an EEPROM
large enough to store the boot firmware.
After downloading to a devices EEPROM,
you should retest it starting from power off.
-s loader |
This identifies the file holding a second stage loader
(in the same 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),
fx2 (the Cypress EZ-USB FX2, supporting high speed transfers),
fx2lp (the Cypress EZ-USB FX2LP, with 16KB internal RAM), or
fx3 (the Cypress EZ-USB FX3, supporting USB 3.0).
Except when writing to EEPROM, all that normally matters when
downloading firmware is whether or not the device uses an FX2
Prints some diagnostics, such as download addresses and sizes,
to standard error. Repeat the flag
(-vv, -vvv) to get more diagnostics.
print error and verbose messages to syslog.
-D devpath |
Specifies the "usbfs" path name for the device in question,
/proc/bus/usb/004/080. This takes precedence over any
DEVICE environment variable that may be set.
If libusb backend is used, you must provide a device IDs
within a string of format vid=<VID>,pid=<PID>.
For example, for Xilinx JTAG USB cable you may want to
pass "vid=0x03fd,pid=0x000d" as an argument.
Longer version of syntax has been provided to prevent
confusion, since in various systems vendor/product IDs
are reported in different order.
specifies the backend used to provide USB functionality for
fxload . Possible values include "linux" and "libusb". On GNU/Linux systems,
"linux" is the default and refers to Linux-only ioctl() interface.
fxload must be compiled with
LIBUSB_SUPPORT compile option.
On systems different than GNU/Linux, "libusb" is always implied.
-D on how to pass a device specification for particular backends.
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 hardwares first stage loader
(supporting the 0xA0 vendor request) cant 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 approaches to loading firmware.
Not all devices support EEPROM updates.
Some EZ-USB based devices dont have an I2C EEPROM;
many such EEPROMs are too small to store firmware;
and some firmware cant be placed in bootable I2C EEPROMs.
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.
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
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.