FXLOAD(8) Linux Programmer's Manual FXLOAD(8)NAMEfxload - Firmware download to EZ-USB devices
SYNOPSISfxload [ -v ] [ -l ] [ -B backend] [ -D devpath ] [ -I firmware ] [ -t
type ] [ -c config ] [ -s loader ]
fxload [ -D devpath ] [ -L link ] [ -m mode ]
fxload [ -V ]
DESCRIPTIONfxload 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 ARM core. These con‐
trollers 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), EEP‐
ROMs, 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 disconnect‐
ing 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 sym‐
bolic 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 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 con‐
ventions include *.hex , *.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 down‐
loaded 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 with‐
out root privileges. Note that usbfs mount options like dev‐
mode=0666 are also available.
-V Identifies the version of fxload being invoked, and exits with‐
out 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 ker‐
nel 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 download‐
ing to a device's 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 con‐
trol 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 sec‐
ond 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 or FX3.
-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. 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 dif‐
ferent order.
-B 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. For "libusb", fxload must be compiled
with LIBUSB_SUPPORT compile option. On systems different than
GNU/Linux, "libusb" is always implied. See -D on how to pass a
device specification for particular backends.
NOTES
This program implements one extension to the standard "hex file" for‐
mat. 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 manag‐
ing downloads and renumeration there. This is less preferable in part
because much device firmware is provided with GPL-incompatible licens‐
ing, and in part because storing such firmware firmware wastes kernel
memory.
For EZ-USB family devices, the hardware's first stage loader (support‐
ing the 0xA0 vendor request) can't write into external memory. Config‐
urations that put firmware into external memory thus need a second
stage loader. For typical "flat" memory architectures, a loader sup‐
porting 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
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 ALSOhotplug(8)AUTHORS
Linux Hotplugging Project http://linux-hotplug.sourceforge.net/
April 2012 FXLOAD(8)
