.\" Copyright (C) 1999 Dirk-Willem van Gulik, dirkx@webweaving.org
.\"      WebWeaving Consultancy, All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY WEBWEAVING AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL WEBWEAVING OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 21, 1999
.Os
.Dt EZUPLOAD 1
.Sh NAME
.Nm ezupload
.Nd Upload firmware from Achorchip EZ-USB based devices
.Sh SYNOPSIS
.Nm ezupload
.Op Fl a Ar fromaddr
.Oo
.Fl e Ar endaddr
|
.Fl s Ar size
.Oc
.Op Fl h | Fl b
.Op Fl v
.Ar device
.Sh DESCRIPTION
The
.Nm ezupload
command can be used to upload the firmware from an Anchorchip EZ-USB
integrated circuit as commonly found in USB devices to the host. This might be
useful during development, troubleshooting etc. to be able to see what the
currently loaded firmware is.
.Pp
The
.Nm ezupload
command takes an
.Xr ugen 4
device as an argument and outputs an intel hex file on the standard out.
.Pp
.Pa Device
is a generic
.Xr ugen 4
device, for example
.Pa /dev/ugen3 .
See the output of
.Xr dmesg 8
for the device your USB device is attached to.
.Xr usbdevs 8
does
.Em 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
.Pa /dev/ugen? .
.Pp
As the size of the ram section cannot be determined reliably from the
USB bus, the
.Fl s
flag can be used to specify this. If not specified up to 32k is uploaded.
The size is in kilobytes. If you know the number of the anchorchip, the
one but last digit indicates the log(2) of the size in kilobytes.
.Pp
Alternatively with a memory range
.Fl a Ar fromaddr
up to, but not including
.Fl e Ar endaddr
can be specified. You cannot specify both
.Fl s Ar size
and
.Fl e Ar endaddr .
.Pp
The
.Fl s
,
.Fl a
and
.Fl e
arguments are interpeted as decimal, unless it is prefixed
with an '0x' for a hex number or a '0' for an octal value.
See
.Xr strtol 3
for more information.
.Pp
The
.Fl h
and
.Fl b
flags select between Intel hex and binary output formats.
.Pp
The
.Fl v
parameter causes a more chatty and verbose excecution.
.Pp
The utility was written 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
.An <mato@activewireinc.com>
or consult
.Ad http://www.activewireinc.com
.Pp
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 excelent documentation on line at
.Ad http://www.anchorchips.com
.Sh W A R N I N G
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.
.Sh BUGS
It will upload the entire range specified. Regardless of whether it
contains active code, data sections, scratch space, etc. As space in
these devices is usually at a premium it might well be that the firmware
code originally downloaded has been overlaid, i.e.  is partly
overwritten or recycled during the boot sequence or at run time.
.Pp
In general you can thus not assume that the code you upload can be
downloaded again as is. There are some pointers on the
.Ad http://www.anchorchips.com
web site to tools for further hacking of the uploaded file.
.Pp
The upload is not actively validated. Only delivery from the
control endpoint is guaranteed by the OS.
.Sh SEE ALSO
.Xr aw 1 ,
.Xr ezdownload 1 ,
.Xr usb 4 ,
.Xr ugen 4 ,
.Xr usbd.conf 5 ,
.Xr usbd 8
.Sh HISTORY
The
.Nm ezupload
was written by
.An Dirk-Willem van Gulik ,
.Ad WebWeaving Consultancy
for
.Nm FreeBSD.
The changes for
.Nm Linux
where made by
.An Brad Hards ,
.Ad brad.hards@dao.defence.gov.au

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