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/