ezdownload — Download firmware into Achorchip EZ-USB based devices

ezdownload [-v] [-f hexfile] device

DESCRIPTION

The ezdownload command can be used to download the firmware into an Anchorchip EZ-USB integrated circuit as commonly found in USB devices. The chip is a generic 8051 based programmeble device. To function in a specific device, e.g. a USB to Parallel port convertor, the 8051 needs application specific 8051 firmware code.

For ’Soft’ ram based devices, the ezdownload command is needed to download the firmware after power on.

The ezdownload command takes an intel hex file with the custom firmware, normally located in /usr/share/usb/firmware or /usr/local/share/usb/firmware and downloads this over the USB(4) bus, using the control endpoint of a generic ugen(4) device. The actual path sought for the firmware can be overridden with the USB_FIRMWARE_PATH environment variable.

Device is a generic ugen(4) device, for example /dev/ugen3. See the output of dmesg(8) for the device your USB device is attached to. usbdevs(8) does not give you the right information as it produces the device address on the bus, not the unit number in the device name, the ’?’ in /dev/ugen?.

It uses the productNo, vendorNo and releaseNo values in hex to compose the file/leaf name of the hex file. This is to safeguard against downloading the wrong firmware. The product’s vendor should normally have provided you with the firmware.

As the download happens in 16 byte chunks, it might take quite some time. After the download the EZ-USB chip is ordered to re-nummerate, i.e. make it appear to the USB stack that it has unplugged itself (i.e. into its original void state) shortly after which it re-appears on the bus in its new disguise. The usb(4) stack treats it then as an entirely new enity.

This command is normally excecuted by the usbd(8) daemon when it detects a new USB device on the wire. See usbd.conf(5) for examples.

The -v parameter causes a more chatty and verbose excecution.

This utility was developed for use with the ActiveWire USB device. This is a low cost 16 pin in/out generic USB rapid prototyping block. For more information, contact <mato@activewireinc.com> or consult http://www.activewireinc.com

In theory this utility should work with all USB-EZ Anchorchips which have on board ram, i.e. the AN21y1, AN21y5 and AN21y6QC series, where y is the log2 of the internal memory size (i.e. aAN2146QC has 2^64=16kByte of ram.). Anchorchips has excellent documentation on-line at http://www.anchorchips.com

You really do not want to the wrong firmware in the wrong device. It might fry your microwave, or cause your zip drive to run around with the mice. For this reason ezdownload will check the filename of the hexfile with the actual (and unique) productNo , vendorNo and releaseNo string from the device. (See the USB_GET_DEVICEINFO and usb_device_info struct in usb(4) for more information. If you are trying to cheat, you are strongly adviced to use usbdevs to check that you are really sending the firmware down to the correct device.

It will download whatever hex file you give it regardless of size. Ultimately it relies on the invoker to have carefully checked the product and vendor ID’s, as to ensure download is suitable and will not blow up the device, your house or your microwave.

The download is not actively validated. Only delivery to the control endpoint is guaranteed. It can take quite some time before the new firmware is up and running. And it might take seconds for the usb(4) stack to realize that a device has plug-cycled itself.

Under certain circumstances you have to run the command twice, or you get the warning that the Reset to re-numerate could not be given. This seems to have to do with firmware which seems to do fiddle with the USB stack on the chip just after it was set running by the host’s reset. This is argubly a bug in that firmware and propably nothing to worry about.

aw(1), ezupload(1,) usb(4), ugen(4), usbd.conf(5), usbd(8)

Normally the /usr/share/usb/firmware and /usr/local/share/usb/firmware directories are sought for hex files with the format VVVV.PPPP.RRR.hex, where VVVV is the VendorNo, PPP is the ProductNo and RRR is the releaseNo value in hexadecimal.

The USB_FIRMWARE_PATH environment variable can be set to direct the firmware search path.

The ezdownload command was written by Dirk-Willem van Gulik, WebWeaving Consultancy for FreeBSD. The changes for Linux where made by Brad Hards, brad.hards@dao.defence.gov.au

http://proj.bpsw.biz/ezload/

FreeBSD 4.9 November 21, 1999 FreeBSD 4.9