Mother Mychaela has developed a set of Linux command line tools for manipulating
configuration EEPROMs that are attached to FT2232x devices and accessed in-band
via USB.  This document describes these tools.

Supported FTDI chips and EEPROMs
================================

The present tools work with 93C46, 93C56 and 93C66 EEPROMs attached behind
FT2232x dual-channel UART/FIFO/MPSSE/etc chips, both FT2232C/D and FT2232H.
We can read these EEPROMs for examination or backup, and we can program them
with new bits, either restoring a previously saved backup or creating a new
from-scratch configuration.  These EEPROM configurations (which we can save,
restore or create from scratch) set the USB VID:PID and the textual strings
naming the manufacturer, the product model and an optional serial number,
select whether each FT2232x channel will come up in the default UART mode or
one of the other EEPROM-configurable modes (245 FIFO, CPU-style FIFO or fast
opto-isolated serial), and allow a few other obscure chip settings to be
tweaked.

Some work has also been done toward the goal of being able to program the
internal EEPROM in FT232R chips (a very popular single-channel USB to UART
converter needing no external components), but this work has not been finished
yet, and the present tools should NOT be used to attempt an EEPROM write on
that chip - the risking of bricking the chip is too high.

More generally, our fteeprom-read tool should be able to read out the EEPROM
content from just about any FTDI chip including FT232R, whereas our
fteeprom-prog tool should be able to program a user-supplied set of bits into
any FTDI+EEPROM combo where the EEPROM is a separate chip - but it is NOT safe
to use on FTDI chips like FT232R or FT-X that have their EEPROM built in.
Furthermore, if the goal is to generate a new EEPROM config from scratch, as
opposed to restoring a saved backup, we currently have generators only for
FT2232C/D and for FT2232H.  (We also have a generator program for FT232R, but
it is of no use for as long as fteeprom-prog is not safe to use on FT232R
chips.)

libftdi dependency
==================

We use libftdi (which is in turn layered on libusb) to issue the special USB
control pipe commands to FTDI chips which are needed to read and write their
EEPROMs.  We use old-style libftdi-0.x (-lftdi on the link line) as opposed to
libftdi1 (-lftdi1) because the new versions took away the ability to write to
the EEPROM directly with ftdi_write_eeprom_location() calls, forcing users to
go through libftdi1's own EEPROM smarts, which we don't want to do - our tools
are all about more direct user empowerment at the lowest level.

Selecting the device to operate on
==================================

Our fteeprom-read, fteeprom-prog and fteeprom-erase tools take a device selector
argument, selecting the device to operate on.  This required argument is the
string to be passed to the ftdi_usb_open_string() function in libftdi, allowing
the device to be operated on to be selected in one of several ways.  Copying
from libftdi documentation, the available formats are:

d:<devicenode> - path of bus and device-node (e.g. "003/001") within usb device
tree (usually at /proc/bus/usb/)

i:<vendor>:<product> - first device with given vendor and product id, ids can
be decimal, octal (preceded by "0") or hex (preceded by "0x")

i:<vendor>:<product>:<index> - as above with index being the number of the
device (starting with 0) if there are more than one

s:<vendor>:<product>:<serial> - first device with given vendor id, product id
and serial string

If you have only one FTDI device connected to your PC or laptop at the time of
your EEPROM manipulation session (generally a good idea to avoid hitting the
wrong device by mistake) and if that FTDI device has some sensible starting
USB VID:PID (either from the previous EEPROM config or the chip's sans-EEPROM
default) that doesn't clash with anything else, then the i: form will probably
be the most convenient, e.g.:

i:0x0403:0x6001 for single-channel FT232x devices running with the default ID
i:0x0403:0x6010 for dual-channel FT2232x devices running with the default ID
i:0x0403:0xPPPP for custom PIDs assigned out of FTDI's VID range
i:0xVVVV:0xPPPP for totally custom USB IDs

Or if the current device config is totally hosed (the EEPROM has a passing
checksum, but sets some completely bogus USB ID), then the d: form will
probably be required for recovery.

Reading the EEPROM
==================

The basic EEPROM read command is as follows:

fteeprom-read <device-selector>

See the previous section for the device selector argument.  In this default
form the tool will read the first 64 EEPROM words, which is appropriate for
93C46 external EEPROMs or for the internal 1024-bit EEPROM in the FT232R chip.
However, if you are working with an FT2232x board with an external EEPROM and
that EEPROM is of a larger variety (93C56 or 93C66), this basic form with give
you an incomplete (truncated) read, and you will need one of the following
extended forms to read the complete EEPROM:

fteeprom-read -b <device-selector>	-- read 128 EEPROM words (93C56)
fteeprom-read -B <device-selector>	-- read 256 EEPROM words (93C66)

(If you use one of the extended forms on a smaller EEPROM, you will get 2 or 4
 copies of the same bits.)

The output of fteeprom-read is in the same format as the input to fteeprom-prog,
thus you can redirect the output to a file and get a restorable backup copy of
your EEPROM.

Programming the EEPROM
======================

In terms of the primitives provided over USB, writing to EEPROMs behind FTDI
chips is accomplished by writing one 16-bit word at a time: the
SIO_WRITE_EEPROM_REQUEST command writes a user-supplied word at a user-supplied
EEPROM address.  However, our fteeprom-prog tool currently supports only writing
complete EEPROMs (64 or 128 or 256 16-bit words starting at address 0) and we
do not currently provide any kind of "random access write" utility; the primary
reason for this design decision is practical usefulness: FTDI's EEPROM structure
includes a checksum over the first 64 words for 1024-bit EEPROMs or over the
first 128 words for larger ones, and if this checksum fails to match, the entire
structure is deemed to be invalid - hence there is no practical use case for
selectively rewriting individual words.  The only exception may be with 93C66
EEPROMs: on these giants only the first half would be subject to the checksum,
and the second half could be used arbitrarily.  However, we have not yet
encountered any boards out in the wild with such big EEPROMs, and we have no
plans to use such in any of our own hardware designs either, hence there is no
business case at the present moment to develop tooling support for them.