1FXLOAD(8) Linux Programmer's Manual FXLOAD(8)
2
6 fxload - Firmware download to EZ-USB devices
7
9 fxload [ -v ] [ -l ] [ -D devpath ] [ -I hexfile ] [ -t type ] [ -c
10 config ] [ -s loader ]
11 fxload [ -D devpath ] [ -L link ] [ -m mode ]
12 fxload [ -V ]
13
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/FX2LP
17 microcontrollers. These have 8-bit 8051 cores with special extensions
18 for USB I/O. The FX2 supports high speed USB 2.0 transfers (480
19 Mbit/sec) as well as full speed USB 1.1 transfers (12 Mbit/sec), while
20 the earlier parts supports only full speed transfers. These con‐
21 trollers have several package options, and can be set up with external
22 memory (on-chip memory is usually 8K or 16K), EEPROMs, and ROMs when
23 device costs allow.
24 This uses "usbfs" (older name: "usbdevfs") to access devices, and
26 issues vendor specific control requests to download and reset the EZ-
27 USB devices. Normally, firmware will then "renumerate" by disconnect‐
28 ing from USB and then reconnecting as a new device. It then appears
29 with new device descriptors and functionality, as provided by the
30 firmware which has been downloaded.
31 To support some non-firmware applications, this can also set up sym‐
33 bolic links for those usbfs names. It can also change their access
34 modes. Both of these can help simplify software applications that need
35 to talk to USB devices using user mode drivers, don't want to run with
36 privileges or to examine all of the existing USB devices, and which
37 don't need more kernel drivers.
38 See the Linux-Hotplug web site for information about how to use fxload
40 to download device firmware when hotplugging USB devices, using driver-
41 specific scripts stored in the /etc/hotplug/usb directory.
42
44 At least one of the following options must be specified. Note that as
45 usual with UNIX and Linux commands, the order of command option flags
46 does not matter. You may use these in any order.
47 -I hexfile
49 Downloads the specified firmware file. This firmware is pro‐
50 vided in standard Intel hexfile format. (Common naming conven‐
51 tions include *.hex and *.ihx.) Depending on the device and
52 firmware in use, the -s option may also be necessary to specify
53 a second stage loader. Firmware is normally downloaded to RAM
54 and executed, but there is also an option for downloading into
55 bootable I2C EEPROMs.
56 -L link
58 Creates the specified symbolic link to the usbfs device path.
59 This would typically be used to create a name in a directory
60 that would be searched by an application. The symlink would be
61 removed by some other component on device unplug.
62 -m mode
64 Changes permissions on the "usbfs" device node. By default,
65 those nodes are only accessible by privileged users, which
66 doesn't help when the user mode device driver needs to run with‐
67 out root privileges. Note that usbfs mount options like dev‐
68 mode=0666 are also available.
69 -V Identifies the version of fxload being invoked, and exits with‐
71 out performing other actions.
72 Note that when downloading firmware that renumerates, there's no point
74 in changing the device permissions or creating a symbolic link.
75
77 By default, fxload assumes the device uses an EZ-USB or EZ-USB FX. It
78 also assumes that the device in question has been specified by USB ker‐
79 nel hotplugging conventions, using the DEVICE environment variable to
80 name a "usbfs" file that can be used to talk to the device.
81 -c config
83 Indicates the specified firmware should be downloaded to an I2C
84 boot EEPROM rather than to RAM. The parameter is the EZ-USB FX
85 or FX2 configuration byte, and for AnchorChips devices the value
86 should be zero. This requires a second stage loader (e.g.
87 vend_ax.hex) that knows how to write to I2C EEPROMs specified
88 using the -s option, as well as a device that's provided with an
89 EEPROM large enough to store the boot firmware. After download‐
90 ing to a device's EEPROM, you should retest it starting from
91 power off.
92 -s loader
94 This identifies the hex file holding a second stage loader (in
95 the same hex file format as the firmware itself), which is
96 loaded into internal memory. This loader understands additional
97 vendor control requests, beyond the one built into all EZ-USB
98 hardware, which are needed to write external RAM or EEPROM. As
99 a last step when loading firmware, fxload normally overwrites
100 this second stage loader with parts of the firmware residing on-
101 chip.
102 -t type
104 Indicates which type of microcontroller is used in the device;
105 type may be one of an21 (the original AnchorChips devices), fx
106 (Cypress' updated version, the EZ-USB FX), or fx2 (the Cypress
107 EZ-USB FX2, supporting high speed transfers), or fx2lp (the
108 Cypress EZ-USB FX2LP, with 16KB internal RAM). Except when
109 writing to EEPROM, all that normally matters when downloading
110 firmware is whether or not the device uses an FX2.
111 -v Prints some diagnostics, such as download addresses and sizes,
113 to standard error. Repeat the flag (-vv, -vvv) to get more
114 diagnostics.
115 -l print error and verbose messages to syslog.
117 -D devpath
119 Specifies the "usbfs" path name for the device in question, such
120 as /proc/bus/usb/004/080. This takes precedence over any DEVICE
121 environment variable that may be set.
122
124 This program implements one extension to the standard "hex file" for‐
125 mat. Lines beginning with a "#" character are ignored, and may be used
126 to hold copyright statements and other information. Other tools may
127 not handle hexfiles using this extension.
128 At this writing, "usbfs" is a kernel configuration option. That means
130 that device drivers relying on user mode firmware downloading may need
131 to depend on that kernel configuration option. A less preferable
132 alternative involves compiling the firmware into the kernel and manag‐
133 ing downloads and renumeration there. This is less preferable in part
134 because much device firmware is provided with GPL-incompatible licens‐
135 ing, and in part because storing such firmware firmware wastes kernel
136 memory.
137 For EZ-USB family devices, the hardware's first stage loader (support‐
139 ing the 0xA0 vendor request) can't write into external memory. Config‐
140 urations that put firmware into external memory thus need a second
141 stage loader. For typical "flat" memory architectures, a loader sup‐
142 porting the 0xA3 vendor request is used to write into that memory.
143 Similarly, a second stage loader that supports the 0xA2 vendor request
144 is needed when writing boot firmware into an I2C EEPROM. These 0xA2
145 and 0xA3 vendor commands are conventions defined by Cypress. Devices
146 that use bank switching or similar mechanisms to stretch the 64KByte
147 address space may need different approach to loading firmware.
148 Not all devices support EEPROM updates. Some EZ-USB based devices
150 don't have an I2C EEPROM; many such EEPROMs are too small to store
151 firmware; and some firmware can't be placed in bootable I2C EEPROMs.
152
154 DEVICE normally names a "usbfs" file that will be used to talk to the
155 device. This is provided by the Linux kernel as part of USB
156 hotplugging.
157
159 hotplug(8)
160
162 Linux Hotplugging Project http://linux-hotplug.sourceforge.net/
163 September 2008 FXLOAD(8)