FreeCalypso > hg > fc-usbser-tools

comparison doc/FTDI-EEPROM-tools @ 80:930bd5316d56

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FTDI-EEPROM-tools: update for current state
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 26 Sep 2023 04:29:54 +0000
parents 9cfe3223fbf8
children
comparison
equal deleted inserted replaced
79:f14d04e4d85d 80:930bd5316d56
131 necessary USB control endpoint transactions can be done while the kernel's 131 necessary USB control endpoint transactions can be done while the kernel's
132 ftdi_sio driver remains attached with ttyUSBx devices intact on all channels. 132 ftdi_sio driver remains attached with ttyUSBx devices intact on all channels.
133 The current version of fteeprom-read has been fixed to be non-invasive in this 133 The current version of fteeprom-read has been fixed to be non-invasive in this
134 regard: you can now freely read the EEPROM of any connected FTDI device 134 regard: you can now freely read the EEPROM of any connected FTDI device
135 *without* bumping off that device's ttyUSB. 135 *without* bumping off that device's ttyUSB.
136
137 Decoding EEPROM dumps
138 =====================
139
140 The output of fteeprom-read is a raw hex dump of the EEPROM; a few of these
141 dumps are included in the artifacts directory in the fc-usbser-tools
142 distribution. You can study these dumps directly in hex using the knowledge
143 base gathered in FTDI-EEPROM-format article, but there is also a utility that
144 decodes the most basic EEPROM settings that are common across all known FTDI
145 chips. You can run ftee-decode like this:
146
147 ftee-decode <eeprom-image-file>
148
149 or reading from stdin:
150
151 fteeprom-read <device-selector> | ftee-decode -
136 152
137 Programming the EEPROM 153 Programming the EEPROM
138 ====================== 154 ======================
139 155
140 In terms of the primitives provided over USB, writing to EEPROMs sitting behind 156 In terms of the primitives provided over USB, writing to EEPROMs sitting behind
181 The present suite of tools includes ftee-gen2232c and ftee-gen2232h EEPROM image 197 The present suite of tools includes ftee-gen2232c and ftee-gen2232h EEPROM image
182 generators, meant for use with FT2232C/D and FT2232H chips, respectively. These 198 generators, meant for use with FT2232C/D and FT2232H chips, respectively. These
183 tools are based on the knowledge extracted from other (pre-existing) community 199 tools are based on the knowledge extracted from other (pre-existing) community
184 tools, primarily the EEPROM config code built into various libftdi versions - 200 tools, primarily the EEPROM config code built into various libftdi versions -
185 we haven't done any FTDI RE of our own, instead the goal of this project has 201 we haven't done any FTDI RE of our own, instead the goal of this project has
186 been to create a set of tools that are better fit for production use. 202 been to create a set of tools that are better fit for production use. The
203 knowledge base we have collected is documented in FTDI-EEPROM-format article.
187 204
188 Our ftee-gen2232c and ftee-gen2232h tools are invoked as follows: 205 Our ftee-gen2232c and ftee-gen2232h tools are invoked as follows:
189 206
190 ftee-gen2232[ch] [-b|-B] <config-file> [serial-num] 207 ftee-gen2232[ch] [size-option] <config-file> [serial-num]
191 208
192 The output of these generator tools is meant to be piped directly into 209 The output of these generator tools is meant to be piped directly into
193 fteeprom-prog. 210 fteeprom-prog.
194 211
195 The philosophy of which settings are given in the config file vs. which ones 212 The philosophy of which settings are given in the config file vs. which ones
196 are given on the command line reflects configuration management and factory 213 are given on the command line reflects configuration management and factory
197 production line operations. In the envisioned usage there would be a config 214 production line operations. In the envisioned usage there would be a config
198 file for each product, giving the USB VID:PID, textual manufacturer and product 215 file for each product, giving the USB VID:PID, textual manufacturer and product
199 ID strings and possibly other config settings which need to be changed from the 216 ID strings and possibly other config settings which need to be changed from the
200 defaults, but the optional serial number string is given on the command line 217 defaults, but the optional serial number string is given on the command line
201 because it would be different for each individual unit being programmed. 218 because it would be different for each individual unit being programmed. The
202 219 detailed format of ftee-gen* input language (config source files) is documented
203 The EEPROM size selection is also made on the command line, so that the same 220 in FTDI-EEPROM-format article.
204 config can be programmed into a smaller EEPROM or a bigger one. By default our 221
205 tools generate an image suitable for a 93C46 EEPROM: the generated image is 64 222 EEPROM size selection
206 words long, with a checksum in word 63, and the EEPROM type byte in FTDI's 223 ---------------------
207 structure is set to 0x46. Running with -b produces an image for a 93C56 EEPROM: 224
208 the EEPROM type byte is set to 0x56, and the checksum-covered image length is 225 In the original design of these tools the EEPROM size selection is made on the
209 extended to 128 words. Finally, -B sets things up for a 93C66 EEPROM: the 226 command line, so that the same config can be programmed into a smaller EEPROM
210 EEPROM type byte is set to 0x66, but the generated checksum-covered image is 227 or a bigger one. By default our tools generate an image suitable for a 93C46
211 still 128 words long just like with -b, as that is what FT2232x chips apparently 228 EEPROM: the generated image is 64 words long, with a checksum in word 63, and
212 expect. I said "apparently" because I don't have any FT2232x hardware with 229 the EEPROM type byte in FTDI's structure is set to 0x46. Running with -b
213 93C66 EEPROMs and I don't plan on acquiring or building any, hence this minimal 230 produces an image for a 93C56 EEPROM: the EEPROM type byte is set to 0x56, and
214 93C66 support is completely untested - use at your own risk. 231 the checksum-covered image length is extended to 128 words. Finally, -B sets
232 things up for a 93C66 EEPROM: the EEPROM type byte is set to 0x66, but the
233 generated checksum-covered image is still 128 words long just like with -b, as
234 that is what FT2232x chips apparently expect. I said "apparently" because I
235 don't have any FT2232x hardware with 93C66 EEPROMs and I don't plan on acquiring
236 or building any, hence this minimal 93C66 support is completely untested - use
237 at your own risk.
238
239 In the current design it is also possible to set the EEPROM size in the config
240 source file - if the EEPROM size is set there, the command line options for it
241 become redundant. If the command line options for EEPROM size conflict with
242 the config source, the result is an error. For symmetry with -b selecting 93C56
243 and -B selecting 93C66, there is also -s option selecting 93C46 explicitly.
215 244
216 It also needs to be noted that with our current RE-based understanding of FTDI's 245 It also needs to be noted that with our current RE-based understanding of FTDI's
217 undocumented EEPROM structure, using a bigger EEPROM does NOT provide more room 246 undocumented EEPROM structure, using a bigger EEPROM does NOT provide more room
218 for strings: all that happens with -b and -B options is that a gap of 64 unused 247 for strings: all that happens with -b and -B options is that a gap of 64 unused
219 EEPROM words is inserted between the end of the fixed structure and the 248 EEPROM words is inserted between the end of the fixed structure and the
220 beginning of strings. The exact same arrangement has been observed in all 93C56 249 beginning of strings. The exact same arrangement has been observed in all 93C56
221 EEPROM images found in the wild, presumably produced with FTDI's official tools, 250 EEPROM images found in the wild, presumably produced with FTDI's official tools,
222 including FTDI's own USB-COM232-PLUS2 board - thus it is not clear at all if 251 including FTDI's own USB-COM232-PLUS2 board - thus it is not clear at all if
223 FT2232x chips actually support longer strings with bigger EEPROMs, and if not, 252 FT2232x chips actually support longer strings with bigger EEPROMs, and if not,
224 what does one need a bigger EEPROM for... 253 what does one need a bigger EEPROM for...
225
226 For the format of config files read by our ftee-gen2232[ch] tools and what
227 settings can be tweaked, read the source code.
228 254
229 Installation directory for EEPROM config files 255 Installation directory for EEPROM config files
230 ---------------------------------------------- 256 ----------------------------------------------
231 257
232 If the name of the config file passed to ftee-gen* does not contain any '/' 258 If the name of the config file passed to ftee-gen* does not contain any '/'
295 ftee-mkblank -B | fteeprom-prog <device-selector> -- blank a 93C66 EEPROM 321 ftee-mkblank -B | fteeprom-prog <device-selector> -- blank a 93C66 EEPROM
296 322
297 Unbinding of ftdi_sio ttyUSBx devices 323 Unbinding of ftdi_sio ttyUSBx devices
298 ===================================== 324 =====================================
299 325
300 When invoked without any options, current versions of fteeprom-prog and 326 By default, fteeprom-prog and fteeprom-erase utilities command the Linux
301 fteeprom-erase do NOT unbind the kernel's ftdi_sio driver from any of the chip's 327 kernel's ftdi_sio driver to unbind from all interfaces of the target chip,
302 interfaces, thus none of the associated ttyUSB devices disappear. This behavior 328 causing all associated ttyUSB devices to disappear. These ttyUSB devices will
303 can be modified as follows: 329 come back in the new configuration when you unplug and replug the USB device
304 330 after programming. If you are a hacker and you really know what you are doing,
305 * Both fteeprom-prog and fteeprom-erase support -d1, -d2 and -d4 options. These 331 you can suppress this logic with -n option - however, doing so is generally not
306 options instruct the tool to command the kernel to unbind from one, two or 332 recommended:
307 four interfaces on the target chip - they should be used with FT232x, FT2232x 333
308 and FT4232x, respectively. 334 * An unplug-replug manipulation is required for the new EEPROM programming to
309 335 take effect. Removal of ttyUSB devices forces the user to unplug and replug
310 * fteeprom-prog running with -r option (FT232R special mode) and no -d options 336 the USB device to get them to come back.
311 defaults to -d1. This default was made because -r option is intended only for 337
312 FT232R, which is known to be a single-channel chip, and the special magic 338 * In the case of FT232R, the special magic sequence it requires for EEPROM
313 sequence is invasive/disruptive to normal UART operation, hence it isn't 339 programming (fteeprom-prog -r) is invasive/disruptive to normal UART
314 really compatible with ttyUSB sticking around. If you are a hacker and you 340 operation, hence it isn't really compatible with ttyUSB sticking around.
315 really know what you are doing, you can defeat this logic with -r -d0.
316 341
317 Please refer to Replug-after-EEPROM-write article for additional notes. 342 Please refer to Replug-after-EEPROM-write article for additional notes.