FreeCalypso > hg > freecalypso-hwlab

comparison doc/FTDI-EEPROM-tools @ 45:1f3a4115375f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FTDI-EEPROM-tools: article started
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 22 Apr 2019 19:32:31 +0000
parents
children b2e9a6f3c833
comparison
equal deleted inserted replaced
44:6a2886f9943e 45:1f3a4115375f
1 Mother Mychaela has developed a set of Linux command line tools for manipulating
2 configuration EEPROMs that are attached to FT2232x devices and accessed in-band
3 via USB. This document describes these tools.
4
5 Supported FTDI chips and EEPROMs
6 ================================
7
8 The present tools work with 93C46, 93C56 and 93C66 EEPROMs attached behind
9 FT2232x dual-channel UART/FIFO/MPSSE/etc chips, both FT2232C/D and FT2232H.
10 We can read these EEPROMs for examination or backup, and we can program them
11 with new bits, either restoring a previously saved backup or creating a new
12 from-scratch configuration. These EEPROM configurations (which we can save,
13 restore or create from scratch) set the USB VID:PID and the textual strings
14 naming the manufacturer, the product model and an optional serial number,
15 select whether each FT2232x channel will come up in the default UART mode or
16 one of the other EEPROM-configurable modes (245 FIFO, CPU-style FIFO or fast
17 opto-isolated serial), and allow a few other obscure chip settings to be
18 tweaked.
19
20 Some work has also been done toward the goal of being able to program the
21 internal EEPROM in FT232R chips (a very popular single-channel USB to UART
22 converter needing no external components), but this work has not been finished
23 yet, and the present tools should NOT be used to attempt an EEPROM write on
24 that chip - the risking of bricking the chip is too high.
25
26 More generally, our fteeprom-read tool should be able to read out the EEPROM
27 content from just about any FTDI chip including FT232R, whereas our
28 fteeprom-prog tool should be able to program a user-supplied set of bits into
29 any FTDI+EEPROM combo where the EEPROM is a separate chip - but it is NOT safe
30 to use on FTDI chips like FT232R or FT-X that have their EEPROM built in.
31 Furthermore, if the goal is to generate a new EEPROM config from scratch, as
32 opposed to restoring a saved backup, we currently have generators only for
33 FT2232C/D and for FT2232H. (We also have a generator program for FT232R, but
34 it is of no use for as long as fteeprom-prog is not safe to use on FT232R
35 chips.)
36
37 libftdi dependency
38 ==================
39
40 We use libftdi (which is in turn layered on libusb) to issue the special USB
41 control pipe commands to FTDI chips which are needed to read and write their
42 EEPROMs. We use old-style libftdi-0.x (-lftdi on the link line) as opposed to
43 libftdi1 (-lftdi1) because the new versions took away the ability to write to
44 the EEPROM directly with ftdi_write_eeprom_location() calls, forcing users to
45 go through libftdi1's own EEPROM smarts, which we don't want to do - our tools
46 are all about more direct user empowerment at the lowest level.
47
48 Selecting the device to operate on
49 ==================================
50
51 Our fteeprom-read, fteeprom-prog and fteeprom-erase tools take a device selector
52 argument, selecting the device to operate on. This required argument is the
53 string to be passed to the ftdi_usb_open_string() function in libftdi, allowing
54 the device to be operated on to be selected in one of several ways. Copying
55 from libftdi documentation, the available formats are:
56
57 d:<devicenode> - path of bus and device-node (e.g. "003/001") within usb device
58 tree (usually at /proc/bus/usb/)
59
60 i:<vendor>:<product> - first device with given vendor and product id, ids can
61 be decimal, octal (preceded by "0") or hex (preceded by "0x")
62
63 i:<vendor>:<product>:<index> - as above with index being the number of the
64 device (starting with 0) if there are more than one
65
66 s:<vendor>:<product>:<serial> - first device with given vendor id, product id
67 and serial string
68
69 If you have only one FTDI device connected to your PC or laptop at the time of
70 your EEPROM manipulation session (generally a good idea to avoid hitting the
71 wrong device by mistake) and if that FTDI device has some sensible starting
72 USB VID:PID (either from the previous EEPROM config or the chip's sans-EEPROM
73 default) that doesn't clash with anything else, then the i: form will probably
74 be the most convenient, e.g.:
75
76 i:0x0403:0x6001 for single-channel FT232x devices running with the default ID
77 i:0x0403:0x6010 for dual-channel FT2232x devices running with the default ID
78 i:0x0403:0xPPPP for custom PIDs assigned out of FTDI's VID range
79 i:0xVVVV:0xPPPP for totally custom USB IDs
80
81 Or if the current device config is totally hosed (the EEPROM has a passing
82 checksum, but sets some completely bogus USB ID), then the d: form will
83 probably be required for recovery.
84
85 Reading the EEPROM
86 ==================
87
88 The basic EEPROM read command is as follows:
89
90 fteeprom-read <device-selector>
91
92 See the previous section for the device selector argument. In this default
93 form the tool will read the first 64 EEPROM words, which is appropriate for
94 93C46 external EEPROMs or for the internal 1024-bit EEPROM in the FT232R chip.
95 However, if you are working with an FT2232x board with an external EEPROM and
96 that EEPROM is of a larger variety (93C56 or 93C66), this basic form with give
97 you an incomplete (truncated) read, and you will need one of the following
98 extended forms to read the complete EEPROM:
99
100 fteeprom-read -b <device-selector> -- read 128 EEPROM words (93C56)
101 fteeprom-read -B <device-selector> -- read 256 EEPROM words (93C66)
102
103 (If you use one of the extended forms on a smaller EEPROM, you will get 2 or 4
104 copies of the same bits.)
105
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
108 your EEPROM.
109
110 Programming the EEPROM
111 ======================
112
113 In terms of the primitives provided over USB, writing to EEPROMs behind FTDI
114 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
116 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
118 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
120 includes a checksum over the first 64 words for 1024-bit EEPROMs or over the
121 first 128 words for larger ones, and if this checksum fails to match, the entire
122 structure is deemed to be invalid - hence there is no practical use case for
123 selectively rewriting individual words. The only exception may be with 93C66
124 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
126 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
128 business case at the present moment to develop tooling support for them.