FreeCalypso > hg > freecalypso-hwlab

comparison doc/FTDI-EEPROM-tools @ 49:b2e9a6f3c833

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FTDI-EEPROM-tools: document finished
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 22 Apr 2019 23:17:14 +0000
parents 1f3a4115375f
children 311c800268b8
comparison
equal deleted inserted replaced
48:af70c59654ed 49:b2e9a6f3c833
105 105
106 The output of fteeprom-read is in the same format as the input to fteeprom-prog, 106 The output of fteeprom-read is in the same format as the input to fteeprom-prog,
107 thus you can redirect the output to a file and get a restorable backup copy of 107 thus you can redirect the output to a file and get a restorable backup copy of
108 your EEPROM. 108 your EEPROM.
109 109
110 It also needs to be noted that if the FTDI device has the kernel's ftdi_sio
111 driver attached to it (ttyUSB device present) when you run fteeprom-read (same
112 for fteeprom-prog and fteeprom-erase), the act of running any of our EEPROM
113 tools will cause it to unbind, i.e., the ttyUSB device will disappear. If the
114 device being operated on is a dual-channel FT2232x, then only the ttyUSB device
115 corresponding to Channel A will disappear, while the Channel B ttyUSB device
116 will stay.
117
110 Programming the EEPROM 118 Programming the EEPROM
111 ====================== 119 ======================
112 120
113 In terms of the primitives provided over USB, writing to EEPROMs behind FTDI 121 In terms of the primitives provided over USB, writing to EEPROMs sitting behind
114 chips is accomplished by writing one 16-bit word at a time: the 122 FTDI chips is accomplished by writing one 16-bit word at a time: the
115 SIO_WRITE_EEPROM_REQUEST command writes a user-supplied word at a user-supplied 123 SIO_WRITE_EEPROM_REQUEST command writes a user-supplied word at a user-supplied
116 EEPROM address. However, our fteeprom-prog tool currently supports only writing 124 EEPROM address. However, our fteeprom-prog tool currently supports only writing
117 complete EEPROMs (64 or 128 or 256 16-bit words starting at address 0) and we 125 complete EEPROMs (64 or 128 or 256 16-bit words starting at address 0) and we
118 do not currently provide any kind of "random access write" utility; the primary 126 do not currently provide any kind of "random access write" utility; the primary
119 reason for this design decision is practical usefulness: FTDI's EEPROM structure 127 reason for this design decision is practical usefulness: FTDI's EEPROM structure
124 EEPROMs: on these giants only the first half would be subject to the checksum, 132 EEPROMs: on these giants only the first half would be subject to the checksum,
125 and the second half could be used arbitrarily. However, we have not yet 133 and the second half could be used arbitrarily. However, we have not yet
126 encountered any boards out in the wild with such big EEPROMs, and we have no 134 encountered any boards out in the wild with such big EEPROMs, and we have no
127 plans to use such in any of our own hardware designs either, hence there is no 135 plans to use such in any of our own hardware designs either, hence there is no
128 business case at the present moment to develop tooling support for them. 136 business case at the present moment to develop tooling support for them.
137
138 There are two primary modes of usage for our fteeprom-prog tool: restoring a
139 saved EEPROM backup or writing a new EEPROM config which you generate yourself.
140 To restore a saved EEPROM backup, run the tool as follows:
141
142 fteeprom-prog <device-selector> <eeprom-image-file>
143
144 To program a new EEPROM config of your own, run a pipeline of this form:
145
146 <generator-tool> | fteeprom-prog <device-selector>
147
148 fteeprom-prog reads the EEPROM image from stdin if no image file is named on
149 the command line; the image format is the same in both cases, and the length of
150 this EEPROM image tells the tool how many words need to be programmed - there
151 are no -b or -B options to fteeprom-prog.
152
153 Generator tools
154 ===============
155
156 Unfortunately FTDI never documented the format of their EEPROM configuration
157 structure - apparently they consider it a proprietary trade secret just like
158 the wire protocol spoken over USB between their chips and their closed-source
159 proprietary drivers. All FOSS community support for these chips is based on
160 reverse engineering, and that includes the EEPROM format.
161
162 The present suite of tools includes ftee-gen2232c and ftee-gen2232h EEPROM image
163 generators, meant for use with FT2232C/D and FT2232H chips, respectively. These
164 tools are based on the knowledge extracted from other (pre-existing) community
165 tools, primarily the EEPROM config code built into various libftdi versions -
166 we haven't done any FTDI RE of our own, instead the goal of this project has
167 been to create a set of tools that are better fit for production use.
168
169 Our ftee-gen2232c and ftee-gen2232h tools are invoked as follows:
170
171 ftee-gen2232[ch] [-b|-B] <config-file> [serial-num]
172
173 The output of these generator tools is meant to be piped directly into
174 fteeprom-prog.
175
176 The philosophy of which settings are given in the config file vs. which ones
177 are given on the command line reflects configuration management and factory
178 production line operations. In the envisioned usage there would be a config
179 file for each product, giving the USB VID:PID, textual manufacturer and product
180 ID strings and possibly other config settings which need to be changed from the
181 defaults, but the optional serial number string is given on the command line
182 because it would be different for each individual unit being programmed.
183
184 The EEPROM size selection is also made on the command line, so that the same
185 config can be programmed into a smaller EEPROM or a bigger one. By default our
186 tools generate an image suitable for a 93C46 EEPROM: the generated image is 64
187 words long, with a checksum in word 63, and the EEPROM type byte in FTDI's
188 structure is set to 0x46. Running with -b produces an image for a 93C56 EEPROM:
189 the EEPROM type byte is set to 0x56, and the checksum-covered image length is
190 extended to 128 words. Finally, -B sets things up for a 93C66 EEPROM: the
191 EEPROM type byte is set to 0x66, but the generated checksum-covered image is
192 still 128 words long just like with -b, as that is what FT2232x chips apparently
193 expect. I said "apparently" because I don't have any FT2232x hardware with
194 93C66 EEPROMs and I don't plan on acquiring or building any, hence this minimal
195 93C66 support is completely untested - use at your own risk.
196
197 For the format of config files read by our ftee-gen2232[ch] tools and what
198 settings can be tweaked, read the source code.
199
200 Erasing the EEPROM (making it blank)
201 ====================================
202
203 If you are playing with a "generic" FT2232x breakout board that is made for
204 tinkering, as opposed to a more finished product, such boards are typically
205 shipped with their EEPROMs completely blank. In that case restoring the EEPROM
206 to its "pristine" state after playing around would mean erasing it, i.e.,
207 bringing it into a blank (all ones) state. FT2232x chips provide two ways to
208 do so: one can explicitly write 0xFFFF into each individual EEPROM word with
209 SIO_WRITE_EEPROM_REQUEST, or one can send a SIO_ERASE_EEPROM_REQUEST command to
210 the chip, and the chip then erases the entire EEPROM. But we don't know how
211 the latter SIO_ERASE_EEPROM_REQUEST operation is implemented by FT2232x chips:
212 does the FT2232x chip go through and erase each word individually, or does it
213 issue an "erase full chip" opcode to the serial EEPROM? If the latter, then
214 according to some EEPROM datasheets that operation may not work if the EEPROM
215 is powered from a 3.3V rail rather than the full USB 5V - may be an issue in
216 FT2232H-based designs.
217
218 In any case our tools provide both ways. To perform the "automatic full chip
219 erase" operation, run the following command:
220
221 fteeprom-erase <device-selector>
222
223 To blank the EEPROM by writing 0xFFFF into each word, run one of the following
224 pipelines:
225
226 ftee-mkblank | fteeprom-prog <device-selector> -- blank a 93C46 EEPROM
227 ftee-mkblank -b | fteeprom-prog <device-selector> -- blank a 93C56 EEPROM
228 ftee-mkblank -B | fteeprom-prog <device-selector> -- blank a 93C66 EEPROM