************************************************************************

Test firmware for devices using EZ-USB Microcontroller
------------------------------------------------------

Copyright (c) 2003 Martin Diehl

Last modified: 2003-07-20

************************************************************************


Simple implementation of an USB 1.1 Interface with EP0 personality
and data source and sink. Can be used in combination with the usbtest
driver from Linux 2.6 for testing of the Linux HCD and usbcore modules.

Currently the firmware presents the device with the following features:
	- disconnect + reconnect after firmwaredownload
	- tailored USB descriptors describing the USB interfacing
	- Implementation of standard control requests on EP0, according
	  to USB 1.1 specification
	- Two bulk endpoints which act as infinite data source and sink
	  fast enough to saturate the full USB 1.1 bulk bandwidth. In
	  particular one should never see a NAK from the device.

For it to work the following is needed:
	- An USB device with the Cypress EZ-USB mcu. Both the AN213x
	  and FX types should work. Some code for the newer FX2 with
	  USB 2.0/HS support is included but not yet useable.
	- The firmware image. Either use the included fw.ihx or build
	  your own. The included fw.ihx image is compiled from the
	  sources of this package, particularly without using any
	  FX-specific features, no I/O features, no Debugging.
	- The fxload program or some similar tool to download the
	  firmware image in Intel-HEX format.
	- The corresponding driver and userland setup


Applicable devices
------------------

	--- WARNING! ---

Downloading third party firmware into any stock hardware might lead to unwanted
results! First, you'll almost certainly void your warranty. Furthermore, nobody
knows what the hardware inside is doing or might expect from its firmware to do.
Downloading unsupported third party firmware might - at least in theory - cause
any kind of damage to your device.

Ok, having this said, it's my personal believe such damage to happen is very unlikely
because this firmware doesn't touch any I/O of the controller. This means whatever
was glued around the microcontroller would see all its pins behave like after
power-up, before the original firmware get loaded. However, unfortunately this is
not a 100% guarantee, because there might be some firmware running from an internal
eeprom, which might do some important housekeeping f.e. - You have been warned ;-)

	----------------

Well, I've no list at hand which devices are in the field known to work with
this firmware. Unless you want to open it to check for the EZ-USB controller
probably the best bet is to check whether the device candidate gets some official
firmware loaded under Linux using the fxload utility from the hotplug package.
If so, the question is whether it's a FX2 or not. Firmware for FX2 doesn't
work with AN213x or FX and vice versa. The general rule of thumb here is, if
the device supports USB 2.0 and/or Highspeed it ought to be a FX2.


Building the firmware
---------------------

The attached 8051-assembler sources and build files are meant to be used
with the ASxxxx Cross Assembler From Alan R. Baldwin, which is available
at <http://shop-pdp.kent.edu/>. The included firmware image was build with
version 3.11. After installing this package on your box you might want to
modify the Makefile wrt. the path where you've installed it.

Note: The SDCC package comes with a modified version of this assembler which
may or may not work for you. In case of doubt simply install the original one.

Next you might want to modify some build options in the config.inc file.
Currently, the firmware is not yet ready to be build for the FX2. OTOH, when
build for the AN213x it will run on the FX (but not FX2) just fine. That's
why the included precompiled fw.ihx is build for AN213x and this is what
config.inc defaults to.

When done with the setup, simply type make!


Firmware download
-----------------

Before downloading, please read the warning above!

If you want to give it a try now: Just use your favourite USB firmware download
tool (like fxload from the Linux hotplug package) and follow the instructions
there to transfer the fw.ihx image to your device.


Firmware features
-----------------

Besides the EP0 standard control requests the firmware provides infinite data
source anf sink endpoints. Several modes are implemented, but have to be
selected at compiletime currently (there is some vendor-specific SetMode
request planned, but not yet working).

Sink:	* always except whatever was sent by the host, any packet length

Source:	* send 64 byte packets with certain payload (currently all zero)
	* send 64 byte packets with a 32-bit packet counter (incremented
	  with each packet sent) in the first 4 bytes (little endian)
	  This can be used to monitor data integrity.
	* send 64 byte packets with a 32-bit frame number in the first
	  4 bytes (little endian). The frame number is a combination of the
	  USB frame and microframe:	((frame# << 8) | microframe#).
	  The microframe is always zero except for the FX2.
	  Since these numbers are synchronized between device and host
	  this mode can be used for latency measurements.
	* send 7 packets with len=64 followed by 1 packet with len=0,
	  round-robin. Used to test the zero-packet method used by many
	  USB protocols.
	* send packet length sequence: 64, 63, ..., 2, 1, 64, 63, ...
	  Can be used to test arbitray length or short packets


Using the firmware
------------------

* usbtest: As of Linux 2.6.0-test1 the usbtest driver and corresponding
	userland utility are ready to work with this firmware right out
	of the box. Please see the documentation there to learn how to
	test your usb setup.

* usb-skeleton: The vendor/product id reported by the firmware's descriptor
	match with the usb-skeleton driver. So one could use this firmware
	to test this firmware for testing this driver.

* more ideas: just try it! You might even want to write some test to find
	issues with this test firmware implementation ;-)


License
-------

Obviously this is copyrighted stuff. This version of the firmware is published
with full source code under the GPL. See the included LICENSE file for details.
If you would prefer some different license conditions or some additional
features, please feel free to contact me using the address below.

Happy testing!

Martin Diehl
<info@mdiehl.de>

