FTDI configuration EEPROM format
================================

Unfortunately FTDI never documented the format of their EEPROM configuration
structure - apparently they consider it a proprietary trade secret just like
the wire protocol spoken over USB between their chips and their closed-source
proprietary drivers.  All FOSS community support for these chips is based on
reverse engineering, and that includes the EEPROM format.

We (FreeCalypso) have not done any significant FTDI RE of our own - instead we
are taking the knowledge that already exists in the FOSS community (including
RE-based knowledge of FTDI EEPROM format) and using it to produce better tools.

The present document summarizes the bits of knowledge we have collected
regarding FTDI's EEPROM configuration structure - this knowledge base is what
our generator and decoder tools are built on, as well as shipped EEPROM
programming in all physical hw products made by FreeCalypso.

Word-based vs byte-based views
==============================

Before FTDI started integrating the EEPROM inside their FT232R and FT-X chips,
their original design used external serial EEPROMs of 93C46, 93C56 or 93C66
type.  These EEPROMs are physically structured as an array of 16-bit words - or
more precisely, some EEPROM parts support both word and byte organization modes,
selected by pin strapping, but FTDI chips require word-structured EEPROMs.

Given this physical organization, we tend to view the EEPROM structure as an
array of 16-bit words.  For some parts of the configuration structure, such as
16-bit ID words and UCS-2 strings, this word-based view is ideal - however,
there are also times when the EEPROM structure needs to be viewed in terms of
bytes:

* Some configuration parameters are given as bytes rather than words;

* Pointers from the fixed structure at the beginning of the EEPROM to string
  descriptors in the "user" area use byte-based addressing.

The correspondence order between bytes and words is little-endian.

Fixed header structure
======================

The first 10 words (20 or 0x14 bytes) of the EEPROM follow the same basic
structure across all known-to-us FTDI chips:

Word 0 (bytes 0x00 and 0x01): this word is best viewed as two separate bytes,
and these bytes encode FTDI-specific functions detailed later in this document.

Word 1 (bytes 0x02 and 0x03): USB vendor ID, called idVendor in the USB spec.

Word 2 (bytes 0x04 and 0x05): USB product ID, called idProduct in the USB spec.

Word 3 (bytes 0x06 and 0x07): originally allocated for the bcdDevice word in
the USB device descriptor, see Table 9-8 in the USB 2.0 specification.  On older
FTDI chips such as FT2232D, the chip takes the value programmed in this EEPROM
word and actually reports this value in its device descriptor - thus if the
EEPROM is misprogrammed, all standard host software will be misled; see our
FTDI-chip-ID article.  OTOH, FT232R ignores this word and always reports its
bcdDevice as 0x0600; in terms of FT232R EEPROM images captured in the wild,
some have zero in this word while others have 0x0600.  FT2232H behaves like
FT232R (ignores this EEPROM word), but I haven't seen any EEPROM images with
this word zeroed out - it appears that FTDI's official tools still insert the
correct bcdDevice value.

Word 4 (bytes 0x08 and 0x09): this word is best viewed as two separate bytes.
Both bytes go into the USB configuration descriptor: byte 0x08 is bmAttributes
and byte 0x09 is bMaxPower.  See USB 2.0 specification Table 9-10 for the
detailed format.

Word 5 (bytes 0x0A and 0x0B): this word is best viewed as two separate bytes,
and these bytes encode FTDI-specific functions detailed later in this document.

Word 6 (bytes 0x0C and 0x0D): originally allocated for the bcdUSB word in the
USB device descriptor, indicating the version of the USB spec which the device
claims to support.  Starting with FT2232H this word has been repurposed for
other functions, as detailed in the chip-specific sections below.

Word 7 (bytes 0x0E and 0x0F): pointer to the manufacturer ID string; format
explained later in the string descriptors section.

Word 8 (bytes 0x10 and 0x11): pointer to the product ID string.

Word 9 (bytes 0x12 and 0x13): pointer to the serial number string if one is
present, otherwise 0.

FTDI-specific bytes in the fixed header
=======================================

Bytes 00, 01, 0A and 0B in the structure covered above are FTDI-specific (don't
correspond to any fields in any of the standard USB descriptors), and many of
the functions controlled by these bytes differ significantly from one FTDI chip
type to the next.

FT2232x bytes 00 and 01
-----------------------

On FT2232x chips bytes 00 and 01 configure channels A and B, respectively.
The 3 least significant bits of each byte encode the channel mode as follows:

0 = UART
1 = 245-style FIFO
2 = fast opto-isolated serial
4 = CPU-style FIFO

Bit 3 (mask 0x08) appears to have no function in the chip itself, but is used
by FTDI's Losedows drivers: for each of the two channels, FTDI's VCP driver is
selected if the bit is set and D2XX driver is selected if the bit is cleared.

On FT2232C/D only (not on FT2232H), bit 4 (mask 0x10) enables high current drive
on the respective A/B channel.

On FT2232H only, byte 01 bit 7 (mask 0x80) turns on a feature that is misnamed
"Suspend on DBus 7 Low" in FTDI's official programming tool.  It is misnamed
because the actual pin in question is BCBUS7, not "DBUS7".  When this function
is enabled via this bit, BCBUS7 becomes PWRSAV# input, which is sufficiently
documented in the FT2232H datasheet.

ftee-gen2232c and ftee-gen2232h default for both bytes is 0x08.

FT232R byte 00
--------------

This byte is conceptually similar to its counterpart on FT2232x, but not exactly
the same, and NOT compatible.  FT232R byte 00 bit assignments are as follows:

bit 0: 0 for FT232R, 1 for FT245R
bit 1: use external oscillator if set
bit 2: high current drive if set
bit 3: same VCP/D2XX nonsense as on other chips, but with reversed sense:
       0 means VCP, 1 means D2XX on this chip

ftee-gen232r default for this byte is 0x00.

FT232R byte 01
--------------

This byte is unique to FT232R: it sets the maximum packet size the chip
advertises for its Data In endpoint, via wMaxPacketSize in the endpoint
descriptor.  The standard value is 64 (0x40), and there does not seem to be
any need to change it.

Byte 0A on all FTDI chips
-------------------------

This byte has the same bit assignments across all FTDI chips we work with,
although newer chips don't support some of the older bits:

bit 0: isochronous endpoint control on FT232BM and FT2232C/D
bit 1: isochronous endpoint control on FT232BM and FT2232C/D
bit 2: enable suspend mode pull-down on I/O pins (all chips)
bit 3: 1 means serial number string present, 0 means serial # string absent
bit 4: set bcdUSB in device descriptor to EEPROM value (only up to FT2232C/D)
bit 5: isochronous endpoint control on FT2232C/D
bit 6: isochronous endpoint control on FT2232C/D

See chip-specific sections below for the details on isochronous endpoint
control bits.

ftee-gen* default for this byte is 0x00.

Byte 0B: FT2232x
----------------

This byte appears to be unused on FT2232C/D and on FT2232H.

Byte 0B: FT232R
---------------

This byte controls UART signal inversion.  Bits 0 through 7 (lsb through msb)
correspond to DBUS0 through DBUS7: if a given bit is set, the corresponding
DBUS/UART signal is inverted.

FT232BM specifics
=================

We don't have much support for this chip as it predates FreeCalypso involvement
in the business of FTDI chip tinkering - however, we know the following bits:

* The fixed part of the EEPROM config structure is just the 10 words described
  above, and the strings area begins at byte offset 0x14.

* Isochronous endpoint control via byte 0A appears to be the same as for
  Channel A of FT2232C/D, described below.

FT2232C/D specifics
===================

Words 0 through 9 (bytes up to 0x13) are as explained above.  The only
additional FT2232C/D-specific word is 10:

Byte 0x14 (low half of word 10) holds the EEPROM type: set to 0x46 for 93C46,
0x56 for 93C56 or 0x66 for 93C66.  It is not clear if the chip actually uses
this byte for anything: it seems to me that FTDI's EEPROM read engine has to
determine the required number of address bits (presumably by asking to read
address 0 and looking for the position of the dummy 0 bit from the EEPROM)
before it can proceed with incrementing addresses.  (The address bit order
in the serial EEPROM interface is big-endian, hence one needs to know the
correct number of address bits in order to increment linearly.)

Byte 0x15 (high half of word 10) appears to be unused.

The strings area of the EEPROM begins with word 11 or byte offset 0x16.

Isochronous endpoint control
----------------------------

The 4 data endpoints on this chip (In and Out for each channel) are of type
Bulk by default, but each of these 4 endpoints is independently selectable
between bulk and isochronous via these 4 bits in byte 0A:

bit 0: make Channel A data In endpoint isochronous
bit 1: make Channel A data Out endpoint isochronous
bit 5: make Channel B data In endpoint isochronous
bit 6: make Channel B data Out endpoint isochronous

FT2232H specifics
=================

On both FT2232H and FT4232H (which we don't support yet) EEPROM word 6
(originally allocated for bcdUSB override) is repurposed for I/O electrical
interface configuration.  The 16-bit word is divided into four 4-bit groups,
mapped to pins as follows:

Group #		FT2232H pins	FT4232H pins
--------------------------------------------
0		ADBUSx		ADBUSx
1		ACBUSx		BDBUSx
2		BDBUSx		CDBUSx
3		BCBUSx		DDBUSx

Within each group the 4 bits are assigned as follows:

Bits	Function
----------------
1:0	drive strength:
	00 = 4 mA
	01 = 8 mA
	10 = 12 mA
	11 = 16 mA
2	set to 1 for slow slew rate
3	set to 1 for Schmitt trigger

Other EEPROM quirks on FT2232H:

* Words 10 and 11, used on FT232R (chronologically between FT2232C and FT2232H)
  for CBUS configuration, appear to be reserved and unused on FT2232H.

* Word 12 on FT2232H is same as word 10 on FT2232C/D: EEPROM type code, even
  though it still isn't clear what the chip does with it, if anything.

* The strings area of the EEPROM begins with word 13 or byte offset 0x1A.

FT232R specifics
================

Words 0 through 9 (bytes up to 0x13) are as explained above.  The following
words 10 and 11 are specific to FT232R - they encode configured functions for
CBUSx pins as follows:

word 10 bits 3:0	CBUS0 config
word 10 bits 7:4	CBUS1 config
word 10 bits 11:8	CBUS2 config
word 10 bits 15:12	CBUS3 config
word 11 bits 3:0	CBUS4 config
word 11 bits 15:4	reserved

Please refer to libftdi source for the codes that go into individual 4-bit
fields for each CBUSx.

The strings area of the EEPROM begins with word 12 or byte offset 0x18.

USB string descriptors
======================

The standard USB device descriptor returned by FTDI chips has iManufacturer set
to 1 and iProduct set to 2, indicating presence of string descriptors at these
indices.  If byte 0A bit 3 is set, iSerialNumber is set to 3, otherwise
iSerialNumber is set to 0, indicating absence of serial number string.

The string descriptors themselves, returned upon the host asking for them at
these indices, are stored verbatim in the strings area of the EEPROM, i.e., in
the free space following the fixed configuration structure for each chip.

As defined in the USB spec, each string descriptor has the following structure:

1 byte:		total number of bytes in the descriptor
1 byte:		constant 0x03, meaning string descriptor
variable bytes:	string body in UCS-2

The total number of bytes in a string descriptor is the number of UCS-2
characters times 2 plus 2; this number is written into the first byte of the
descriptor itself, in the least-significant half of the first 16-bit word.  The
whole descriptor, consisting of this header word followed by UCS-2 character
words, can be placed at any EEPROM location within the "acceptable" area (see
below), and there is a pointer to each of the 3 possible string descriptors
from the fixed header structure at the beginning of the EEPROM.

Each of the 3 string pointers is one 16-bit word, structured as follows:

lower byte:	EEPROM byte address where the descriptor starts
		(see below regarding the most significant bit of this byte)
upper byte:	total number of bytes in the descriptor, same as written
		in the descriptor itself

String placement quirk
----------------------

Common sense says that the most natural way to pack the needed strings into the
EEPROM is to put the manufacturer ID string right after the fixed config
structure, then the product ID string and then the serial number string, if
included.  However, the EEPROM structure generated by FTDI's official tools is
slightly different:

* In the case of 93C56 or 93C66 EEPROMs, FTDI's official tools skip 64 words
  (128 bytes) after the end of the chip-defined config structure and then place
  the manufacturer ID string after this gap.  The byte-address pointer to each
  string descriptor always has its high bit set as a result of this quirk.

* In the case of 1024-bit EEPROMs (93C46 or FT232R internal) nothing is skipped,
  but the byte-address pointers to strings are written with the high bit set,
  as if the EEPROM were of 93C56 type.

My (Mother Mychaela's) first guess was that these quirks were just a matter of
FTDI's official tools being silly, and that those of us who write our own FOSS
tools can put our strings anywhere in the EEPROM, as long as the location we
pick doesn't conflict with something else.  However, experiments with real
boards featuring an FT2232x chip and an EEPROM reveal that the chip is NOT happy
when the most significant bit of the byte-address pointer to a string descriptor
is cleared: it appears that the chip is returning some kind of garbage to the
USB host when asked for the string descriptor in this case.  (I am using the
vague language of "appears that" because I am not currently able to allocate
the time to study the problem properly.)  Thus it appears that all strings MUST
be located in the upper half of 93C56, and the quirk of setting the msb of byte
address for 93C46 is also required.

Our ftee-gen* tools replicate both of these quirks, thus the resulting EEPROM
structure is the same as what the chip vendor's official tools produce.

ftee-gen* tools: config file language
=====================================

The format of EEPROM config files read by our ftee-gen* tools is line-based.
Each non-blank, non-comment line defines or tweaks one setting.  The following
settings are common to all ftee-gen* chip variants:

Setting		Format	Meaning
-------------------------------
ftdi-chip	keyword	Type of FTDI chip this config source was written for
eeprom		keyword	EEPROM size selector (not in ftee-gen232r)
vid		hex	USB vendor ID
pid		hex	USB product ID
manuf		string	Manufacturer ID string
product		string	Product ID string
byte00		hex	Raw setting of byte 00
byte01		hex	Raw setting of byte 01
byte08		hex	Raw setting of byte 08
byte0A		hex	Raw setting of byte 0A
maxpower	decimal	bMaxPower declaration, number in mA
usbver		hex	bcdUSB word (ftee-gen2232c and ftee-gen232r only)

Additional settings for FT2232H (ftee-gen2232h):

group0		hex	I/O electrical config for ADBUSx
group1		hex	I/O electrical config for ACBUSx
group2		hex	I/O electrical config for BDBUSx
group3		hex	I/O electrical config for BCBUSx

Additional settings for FT232R (ftee-gen232r):

byte0B		hex	Raw setting of byte 0B
cbus0		hex	CBUS0 config code
cbus1		hex	CBUS1 config code
cbus2		hex	CBUS2 config code
cbus3		hex	CBUS3 config code
cbus4		hex	CBUS4 config code

Only two settings are strictly mandatory: manuf and product strings.  For all
other settings the EEPROM generator tool provides chip-matching defaults:

* ftee-gen2232[ch] defaults match the configuration attained by the chip
  with a blank or missing EEPROM;

* ftee-gen232r defaults match FTDI's default factory programming of the
  chip-internal EEPROM.

As one can see, the config language is very low-level, most bits are set in raw
hex.  This design is justified by the paradigm of writing each config file once:
if you are designing a new board with an FTDI chip on it, and you need to change
some setting away from the FTDI chip's default, you research it once, figure out
the right bits, code the needed byte-level configuration in an EEPROM config
file, and then you just run a standard command line every time you need to
program a board.

The serial number string is never specified in the config file, instead it is
specified on the command line - this tool design is in accord with factory
production paradigm, where each EEPROM config is written once for a given board
design, and then a shell pipeline is executed for each board to be programmed.

Byte 0A bit 3 is always overridden by the generator tool based on the serial
number command line argument: set if a serial number is given and cleared if
this argument is omitted.

FTDI chip type matching
-----------------------

The design of FreeCalypso FTDI EEPROM tools calls for mostly manual matching
between EEPROM config files and generator tools: the operator is responsible
for selecting the correct tool (ftee-gen2232c, ftee-gen2232h or ftee-gen232r)
for the actual FTDI chip on the board of interest, and also responsible for
feeding correct EEPROM config files to this tool.  However, now that we are
starting to give EEPROM programming instructions to end users in the form of
"please run this shell pipeline", there is a natural desire to reduce potential
for operator error: if someone takes an EEPROM config file written for one FTDI
chip and feeds it to an ftee-gen* tool for a different chip, it would be nice
for this invalid combination to be detected and rejected.

Toward this end, the following optional settings may be included in EEPROM
config source files:

ftdi-chip FT2232C	# config valid only for ftee-gen2232c
ftdi-chip FT2232D	# same as FT2232C
ftdi-chip FT2232H	# config valid only for ftee-gen2232h
ftdi-chip FT2232x	# config valid for ftee-gen2232c and ftee-gen2232h
ftdi-chip FT232R	# config valid only for ftee-gen232r

EEPROM size selection
---------------------

In the case of EEPROM generator tools for FTDI chips with external EEPROMs,
one of the following settings may be included in the config source:

eeprom 93C46
eeprom 93C56
eeprom 93C66

If one of these settings is included, the EEPROM size is fixed; if an EEPROM
size option (-s, -b or -B) is included on the command line, it must match the
config-set EEPROM size, otherwise the tool bails out with an error.  If no
eeprom setting is included in the config file, then any EEPROM size may be
selected with command line options, and if no such options are included on the
command line either, then the final default is 93C46.

Preparing config files for boards
---------------------------------

If you have a specific board design with an FTDI chip and are preparing an
EEPROM config file for your board, our recommendation is to include ftdi-chip
and eeprom lines in your config file, naming the specific FTDI chip and the
specific EEPROM size on your board.  By doing so, you reduce the possibility
that someone will misprogram your EEPROM by selecting the wrong generator tool
or the wrong EEPROM size.

The alternative approach of leaving these settings unspecified or underspecified
should be used for unfinished EEPROM config templates or examples, or configs
that can be sensibly loaded into many different boards that may vary in FT2232x
chip choice and EEPROM size.