FreeCalypso > hg > fc-usbser-tools

comparison doc/FTDI-EEPROM-format @ 69:065f68a94b6b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FTDI-EEPROM-format: beginning of article
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 14 Sep 2023 23:56:25 +0000
parents
children 09da7db45dce
comparison
equal deleted inserted replaced
68:5cbde3c80c24 69:065f68a94b6b
1 FTDI configuration EEPROM format
2 ================================
3
4 Unfortunately FTDI never documented the format of their EEPROM configuration
5 structure - apparently they consider it a proprietary trade secret just like
6 the wire protocol spoken over USB between their chips and their closed-source
7 proprietary drivers. All FOSS community support for these chips is based on
8 reverse engineering, and that includes the EEPROM format.
9
10 We (FreeCalypso) have not done any significant FTDI RE of our own - instead we
11 are taking the knowledge that already exists in the FOSS community (including
12 RE-based knowledge of FTDI EEPROM format) and using it to produce better tools.
13
14 The present document summarizes the bits of knowledge we have collected
15 regarding FTDI's EEPROM configuration structure - this knowledge base is what
16 our generator and decoder tools are built on, as well as shipped EEPROM
17 programming in all physical hw products made by FreeCalypso.
18
19 Word-based vs byte-based views
20 ==============================
21
22 Before FTDI started integrating the EEPROM inside their FT232R and FT-X chips,
23 their original design used external serial EEPROMs of 93C46, 93C56 or 93C66
24 type. These EEPROMs are physically structured as an array of 16-bit words - or
25 more precisely, some EEPROM parts support both word and byte organization modes,
26 selected by pin strapping, but FTDI chips require word-structured EEPROMs.
27
28 Given this physical organization, we tend to view the EEPROM structure as an
29 array of 16-bit words. For some parts of the configuration structure, such as
30 16-bit ID words and UCS-2 strings, this word-based view is ideal - however,
31 there are also times when the EEPROM structure needs to be viewed in terms of
32 bytes:
33
34 * Some configuration parameters are given as bytes rather than words;
35
36 * Pointers from the fixed structure at the beginning of the EEPROM to string
37 descriptors in the "user" area use byte-based addressing.
38
39 The correspondence order between bytes and words is little-endian.
40
41 Fixed header structure
42 ======================
43
44 The first 10 words (20 or 0x14 bytes) of the EEPROM follow the same basic
45 structure across all known-to-us FTDI chips:
46
47 Word 0 (bytes 0x00 and 0x01): this word is best viewed as two separate bytes,
48 and these bytes encode FTDI-specific functions detailed later in this document.
49
50 Word 1 (bytes 0x02 and 0x03): USB vendor ID, called idVendor in the USB spec.
51
52 Word 2 (bytes 0x04 and 0x05): USB product ID, called idProduct in the USB spec.
53
54 Word 3 (bytes 0x06 and 0x07): originally allocated for the bcdDevice word in
55 the USB device descriptor, see Table 9-8 in the USB 2.0 specification. On older
56 FTDI chips such as FT2232D, the chip takes the value programmed in this EEPROM
57 word and actually reports this value in its device descriptor - thus if the
58 EEPROM is misprogrammed, all standard host software will be misled; see our
59 FTDI-chip-ID article. OTOH, FT232R ignores this word and always reports its
60 bcdDevice as 0x0600; in terms of FT232R EEPROM images captured in the wild,
61 some have zero in this word while others have 0x0600. FT2232H behaves like
62 FT232R (ignores this EEPROM word), but I haven't seen any EEPROM images with
63 this word zeroed out - it appears that FTDI's official tools still insert the
64 correct bcdDevice value.
65
66 Word 4 (bytes 0x08 and 0x09): this word is best viewed as two separate bytes.
67 Both bytes go into the USB configuration descriptor: byte 0x08 is bmAttributes
68 and byte 0x09 is bMaxPower. See USB 2.0 specification Table 9-10 for the
69 detailed format.
70
71 Word 5 (bytes 0x0A and 0x0B): this word is best viewed as two separate bytes,
72 and these bytes encode FTDI-specific functions detailed later in this document.
73
74 Word 6 (bytes 0x0C and 0x0D): originally allocated for the bcdUSB word in the
75 USB device descriptor, indicating the version of the USB spec which the device
76 claims to support. Starting with FT2232H this word has been repurposed for
77 other functions, as detailed in the chip-specific sections below.
78
79 Word 7 (bytes 0x0E and 0x0F): pointer to the manufacturer ID string; format
80 explained later in the string descriptors section.
81
82 Word 8 (bytes 0x10 and 0x11): pointer to the product ID string.
83
84 Word 9 (bytes 0x12 and 0x13): pointer to the serial number string if one is
85 present, otherwise 0.
86
87 FTDI-specific bytes in the fixed header
88 =======================================
89
90 Bytes 00, 01, 0A and 0B in the structure covered above are FTDI-specific (don't
91 correspond to any fields in any of the standard USB descriptors), and many of
92 the functions controlled by these bytes differ significantly from one FTDI chip
93 type to the next.
94
95 FT2232x bytes 00 and 01
96 -----------------------
97
98 On FT2232x chips bytes 00 and 01 configure channels A and B, respectively.
99 The 3 least significant bits of each byte encode the channel mode as follows:
100
101 0 = UART
102 1 = 245-style FIFO
103 2 = fast opto-isolated serial
104 4 = CPU-style FIFO
105
106 Bit 3 (mask 0x08) appears to have no function in the chip itself, but is used
107 by FTDI's Losedows drivers: for each of the two channels, FTDI's VCP driver is
108 selected if the bit is set and D2XX driver is selected if the bit is cleared.
109
110 On FT2232C/D only (not on FT2232H), bit 4 (mask 0x10) enables high current drive
111 on the respective A/B channel.
112
113 On FT2232H only, byte 01 bit 7 (mask 0x80) turns on a feature that is misnamed
114 "Suspend on DBus 7 Low" in FTDI's official programming tool. It is misnamed
115 because the actual pin in question is BCBUS7, not "DBUS7". When this function
116 is enabled via this bit, BCBUS7 becomes PWRSAV# input, which is sufficiently
117 documented in the FT2232H datasheet.
118
119 ftee-gen2232c and ftee-gen2232h default for both bytes is 0x08.
120
121 FT232R byte 00
122 --------------
123
124 This byte is conceptually similar to its counterpart on FT2232x, but not exactly
125 the same, and NOT compatible. FT232R byte 00 bit assignments are as follows:
126
127 bit 0: 0 for FT232R, 1 for FT245R
128 bit 1: use external oscillator if set
129 bit 2: high current drive if set
130 bit 3: same VCP/D2XX nonsense as on other chips, but with reversed sense:
131 0 means VCP, 1 means D2XX on this chip
132
133 ftee-gen232r default for this byte is 0x00.
134
135 FT232R byte 01
136 --------------
137
138 This byte is unique to FT232R: it sets the maximum packet size the chip
139 advertises for its Data In endpoint, via wMaxPacketSize in the endpoint
140 descriptor. The standard value is 64 (0x40), and there does not seem to be
141 any need to change it.
142
143 Byte 0A on all FTDI chips
144 -------------------------
145
146 This byte has the same bit assignments across all FTDI chips we work with,
147 although newer chips don't support some of the older bits:
148
149 bit 0: isochronous endpoint control on FT232BM and FT2232C/D
150 bit 1: isochronous endpoint control on FT232BM and FT2232C/D
151 Bit 2: enable suspend mode pull-down on I/O pins (all chips)
152 bit 3: 1 means serial number string present, 0 means serial # string absent
153 bit 4: set bcdUSB in device descriptor to EEPROM value (only up to FT2232C/D)
154 bit 5: isochronous endpoint control on FT2232C/D
155 bit 6: isochronous endpoint control on FT2232C/D
156
157 See chip-specific sections below for the details on isochronous endpoint
158 control bits.
159
160 ftee-gen* default for this byte is 0x00.
161
162 Byte 0B: FT2232x
163 ----------------
164
165 This byte appears to be unused on FT2232C/D and on FT2232H.
166
167 Byte 0B: FT232R
168 ---------------
169
170 This byte controls UART signal inversion. Bits 0 through 7 (lsb through msb)
171 correspond to DBUS0 through DBUS7: if a given bit is set, the corresponding
172 DBUS/UART signal is inverted.
173
174 FT232BM specifics
175 =================
176
177 We don't have much support for this chip as it predates FreeCalypso involvement
178 in the business of FTDI chip tinkering - however, we know the following bits:
179
180 * The fixed part of the EEPROM config structure is just the 10 words described
181 above, and the strings area begins at byte offset 0x14.
182
183 * Isochronous endpoint control via byte 0A appears to be the same as for
184 Channel A of FT2232C/D, described below.
185
186 FT2232C/D specifics
187 ===================
188
189 Words 0 through 9 (bytes up to 0x13) are as explained above. The only
190 additional FT2232C/D-specific word is 10:
191
192 Byte 0x14 (low half of word 10) holds the EEPROM type: set to 0x46 for 93C46,
193 0x56 for 93C56 or 0x66 for 93C66. It is not clear if the chip actually uses
194 this byte for anything: it seems to me that FTDI's EEPROM read engine has to
195 determine the required number of address bits (presumably by asking to read
196 address 0 and looking for the position of the dummy 0 bit from the EEPROM)
197 before it can proceed with incrementing addresses. (The address bit order
198 in the serial EEPROM interface is big-endian, hence one needs to know the
199 correct number of address bits in order to increment linearly.)
200
201 Byte 0x15 (high half of word 10) appears to be unused.
202
203 The strings area of the EEPROM begins with word 11 or byte offset 0x16.
204
205 Isochronous endpoint control
206 ----------------------------
207
208 The 4 data endpoints on this chip (In and Out for each channel) are of type
209 Bulk by default, but each of these 4 endpoints is independently selectable
210 between bulk and isochronous via these 4 bits in byte 0A:
211
212 bit 0: make Channel A data In endpoint isochronous
213 bit 1: make Channel A data Out endpoint isochronous
214 bit 5: make Channel B data In endpoint isochronous
215 bit 6: make Channel B data Out endpoint isochronous
216
217 FT2232H specifics
218 =================
219
220 On both FT2232H and FT4232H (which we don't support yet) EEPROM word 6
221 (originally allocated for bcdUSB override) is repurposed for I/O electrical
222 interface configuration. The 16-bit word is divided into four 4-bit groups,
223 mapped to pins as follows:
224
225 Group # FT2232H pins FT4232H pins
226 --------------------------------------------
227 0 ADBUSx ADBUSx
228 1 ACBUSx BDBUSx
229 2 BDBUSx CDBUSx
230 3 BCBUSx DDBUSx
231
232 Within each group the 4 bits are assigned as follows:
233
234 Bits Function
235 ----------------
236 1:0 drive strength:
237 00 = 4 mA
238 01 = 8 mA
239 10 = 12 mA
240 11 = 16 mA
241 2 set to 1 for slow slew rate
242 3 set to 1 for Schmitt trigger
243
244 Other EEPROM quirks on FT2232H:
245
246 * Words 10 and 11, used on FT232R (chronologically between FT2232C and FT2232H)
247 for CBUS configuration, appear to be reserved and unused on FT2232H.
248
249 * Word 12 on FT2232H is same as word 10 on FT2232C/D: EEPROM type code, even
250 though it still isn't clear what the chip does with it, if anything.
251
252 * The strings area of the EEPROM begins with word 13 or byte offset 0x1A.