FreeCalypso > hg > fc-usbser-tools

annotate doc/FTDI-EEPROM-tools @ 86:b7397959ae68

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cp2102-decode-ee-desc: show bMaxPacketSize0 in decimal
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 27 Sep 2023 18:46:10 +0000
parents 930bd5316d56
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Mother Mychaela has developed a set of Linux command line tools for manipulating
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 configuration EEPROMs that are attached to FT2232x devices and accessed in-band
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 via USB. This document describes these tools.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 Supported FTDI chips and EEPROMs
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 ================================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 The present tools work with 93C46, 93C56 and 93C66 EEPROMs attached behind
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 FT2232x dual-channel UART/FIFO/MPSSE/etc chips, both FT2232C/D and FT2232H.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 We can read these EEPROMs for examination or backup, and we can program them
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 with new bits, either restoring a previously saved backup or creating a new
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 from-scratch configuration. These EEPROM configurations (which we can save,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 restore or create from scratch) set the USB VID:PID and the textual strings
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 naming the manufacturer, the product model and an optional serial number,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 select whether each FT2232x channel will come up in the default UART mode or
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 one of the other EEPROM-configurable modes (245 FIFO, CPU-style FIFO or fast
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 opto-isolated serial), and allow a few other obscure chip settings to be
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 tweaked.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 Some work has also been done toward the goal of being able to program the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 internal EEPROM in FT232R chips (a very popular single-channel USB to UART
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 converter needing no external components), but this work should be considered
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 experimental: the tools appear to work on an UB232R module from Digi-Key
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 (presumably containing a genuine FT232RQ chip) and on a no-name FT232RL adapter
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 where the chip is uncertain, but because we have no real production use case
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 yet, we are not ready to truly vouch for FT232R support.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 More generally:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 * our fteeprom-read tool should be able to read out the EEPROM content from
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 just about any FTDI chip;
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 * our fteeprom-prog tool should be able to program a user-supplied set of bits
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 into any FTDI+EEPROM combo where the EEPROM is a separate chip, or into FT232R
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 internal EEPROM - but it most likely won't work for newer FT-X chips;
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 * if the goal is to generate a new EEPROM config from scratch, as opposed to
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 restoring a saved backup, we currently have generators only for FT2232C/D,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 for FT2232H and for FT232R, with the last one considered experimental and not
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 proven.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
42 No more libftdi dependency!
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
43 ===========================
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
45 Our initial implementation of fteeprom-* tools was based on libftdi; more
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
46 specifically, one had to use an old libftdi-0.x version, as these old versions
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
47 were the only ones that allowed writing to the EEPROM directly with
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
48 ftdi_write_eeprom_location() API calls. However, the present version has been
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
49 reimplemented to NOT use libftdi at all - instead we have our own minilibs,
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
50 maintained as part of fc-usbser-tools package, that are built on top of
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
51 libusb-0.x API. (The version of libftdi we used previously was also built on
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
52 top of the same libusb-0.x API, hence no change in that dependency.) The
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
53 libusb-0.x API we use consists of <usb.h> include header and -lusb link library
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
54 pull-in; on "modern" systems these pieces will typically be provided by
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
55 libusb-compat-0.1 package wrapping around libusb-1.x, but in the spirit of Holy
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
56 retrocomputing, really old systems can be used with native libusb-0.1.
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 Selecting the device to operate on
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 ==================================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 Our fteeprom-read, fteeprom-prog and fteeprom-erase tools take a device selector
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
62 argument, selecting the device to operate on. The design of this device
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
63 selector mechanism has been copied from libftdi; while we no longer use libftdi,
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
64 we found its device selector mechanism to be a really good design and we have
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
65 fully reimplemented it. The device selector argument is a string in one of the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
66 following formats (some wording copied from libftdi documentation):
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
68 d:<devicenode> - path of bus and device-node (e.g. "003/001") within USB device
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
69 tree as enumerated via libusb-0.x API. Libftdi documentation said
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
70 /proc/bus/usb, but at least on Mother's Slackware 14.2 system, the observed
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
71 location of this device tree is /dev/bus/usb.
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 i:<vendor>:<product> - first device with given vendor and product id, ids can
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 be decimal, octal (preceded by "0") or hex (preceded by "0x")
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 i:<vendor>:<product>:<index> - as above with index being the number of the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 device (starting with 0) if there are more than one
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 s:<vendor>:<product>:<serial> - first device with given vendor id, product id
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 and serial string
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 If you have only one FTDI device connected to your PC or laptop at the time of
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 your EEPROM manipulation session (generally a good idea to avoid hitting the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 wrong device by mistake) and if that FTDI device has some sensible starting
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 USB VID:PID (either from the previous EEPROM config or the chip's sans-EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 default) that doesn't clash with anything else, then the i: form will probably
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 be the most convenient, e.g.:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 i:0x0403:0x6001 for single-channel FT232x devices running with the default ID
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 i:0x0403:0x6010 for dual-channel FT2232x devices running with the default ID
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 i:0x0403:0xPPPP for custom PIDs assigned out of FTDI's VID range
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 i:0xVVVV:0xPPPP for totally custom USB IDs
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 Or if the current device config is totally hosed (the EEPROM has a passing
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 checksum, but sets some completely bogus USB ID), then the d: form will
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 probably be required for recovery.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 Reading the EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 ==================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 The basic EEPROM read command is as follows:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 fteeprom-read <device-selector>
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 See the previous section for the device selector argument. In this default
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 form the tool will read the first 64 EEPROM words, which is appropriate for
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 93C46 external EEPROMs or for the internal 1024-bit EEPROM in the FT232R chip.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 However, if you are working with an FT2232x board with an external EEPROM and
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 that EEPROM is of a larger variety (93C56 or 93C66), this basic form with give
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 you an incomplete (truncated) read, and you will need one of the following
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 extended forms to read the complete EEPROM:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 fteeprom-read -b <device-selector> -- read 128 EEPROM words (93C56)
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 fteeprom-read -B <device-selector> -- read 256 EEPROM words (93C66)
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 (If you use one of the extended forms on a smaller EEPROM, you will get 2 or 4
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 copies of the same bits.)
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 The output of fteeprom-read is in the same format as the input to fteeprom-prog,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 thus you can redirect the output to a file and get a restorable backup copy of
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 your EEPROM.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
123 Change from previous version
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
124 ----------------------------
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
125
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
126 In the original libftdi-based implementation of fteeprom-read, the act of
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
127 reading the EEPROM was invasive: libftdi's open function would unbind the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
128 kernel's ftdi_sio driver (Channel A ttyUSB device disappears) and
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
129 reset/reinitialize the SIO channel itself. However, it turns out that these
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
130 invasive steps aren't needed if the goal is only to read the EEPROM - the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
131 necessary USB control endpoint transactions can be done while the kernel's
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
132 ftdi_sio driver remains attached with ttyUSBx devices intact on all channels.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
133 The current version of fteeprom-read has been fixed to be non-invasive in this
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
134 regard: you can now freely read the EEPROM of any connected FTDI device
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
135 *without* bumping off that device's ttyUSB.
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136
80
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
137 Decoding EEPROM dumps
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
138 =====================
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
139
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
140 The output of fteeprom-read is a raw hex dump of the EEPROM; a few of these
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
141 dumps are included in the artifacts directory in the fc-usbser-tools
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
142 distribution. You can study these dumps directly in hex using the knowledge
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
143 base gathered in FTDI-EEPROM-format article, but there is also a utility that
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
144 decodes the most basic EEPROM settings that are common across all known FTDI
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
145 chips. You can run ftee-decode like this:
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
146
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
147 ftee-decode <eeprom-image-file>
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
148
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
149 or reading from stdin:
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
150
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
151 fteeprom-read <device-selector> | ftee-decode -
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
152
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 Programming the EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 ======================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 In terms of the primitives provided over USB, writing to EEPROMs sitting behind
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157 FTDI chips is accomplished by writing one 16-bit word at a time: the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 SIO_WRITE_EEPROM_REQUEST command writes a user-supplied word at a user-supplied
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 EEPROM address. However, our fteeprom-prog tool currently supports only writing
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160 complete EEPROMs (64 or 128 or 256 16-bit words starting at address 0) and we
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 do not currently provide any kind of "random access write" utility; the primary
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 reason for this design decision is practical usefulness: FTDI's EEPROM structure
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163 includes a checksum over the first 64 words for 1024-bit EEPROMs or over the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 first 128 words for larger ones, and if this checksum fails to match, the entire
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165 structure is deemed to be invalid - hence there is no practical use case for
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166 selectively rewriting individual words. The only exception may be with 93C66
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167 EEPROMs: on these giants only the first half would be subject to the checksum,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 and the second half could be used arbitrarily. However, we have not yet
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169 encountered any boards out in the wild with such big EEPROMs, and we have no
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 plans to use such in any of our own hardware designs either, hence there is no
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171 business case at the present moment to develop tooling support for them.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 There are two primary modes of usage for our fteeprom-prog tool: restoring a
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174 saved EEPROM backup or writing a new EEPROM config which you generate yourself.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 To restore a saved EEPROM backup, run the tool as follows:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 fteeprom-prog <device-selector> <eeprom-image-file>
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 To program a new EEPROM config of your own, run a pipeline of this form:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181 <generator-tool> | fteeprom-prog <device-selector>
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183 fteeprom-prog reads the EEPROM image from stdin if no image file is named on
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 the command line; the image format is the same in both cases, and the length of
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185 this EEPROM image tells the tool how many words need to be programmed - there
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186 are no -b or -B options to fteeprom-prog.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188 Generator tools
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189 ===============
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
191 Unfortunately FTDI never documented the format of their EEPROM configuration
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 structure - apparently they consider it a proprietary trade secret just like
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 the wire protocol spoken over USB between their chips and their closed-source
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 proprietary drivers. All FOSS community support for these chips is based on
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195 reverse engineering, and that includes the EEPROM format.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 The present suite of tools includes ftee-gen2232c and ftee-gen2232h EEPROM image
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198 generators, meant for use with FT2232C/D and FT2232H chips, respectively. These
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199 tools are based on the knowledge extracted from other (pre-existing) community
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 tools, primarily the EEPROM config code built into various libftdi versions -
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201 we haven't done any FTDI RE of our own, instead the goal of this project has
80
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
202 been to create a set of tools that are better fit for production use. The
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
203 knowledge base we have collected is documented in FTDI-EEPROM-format article.
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 Our ftee-gen2232c and ftee-gen2232h tools are invoked as follows:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206
80
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
207 ftee-gen2232[ch] [size-option] <config-file> [serial-num]
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209 The output of these generator tools is meant to be piped directly into
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210 fteeprom-prog.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212 The philosophy of which settings are given in the config file vs. which ones
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 are given on the command line reflects configuration management and factory
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214 production line operations. In the envisioned usage there would be a config
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215 file for each product, giving the USB VID:PID, textual manufacturer and product
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216 ID strings and possibly other config settings which need to be changed from the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217 defaults, but the optional serial number string is given on the command line
80
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
218 because it would be different for each individual unit being programmed. The
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
219 detailed format of ftee-gen* input language (config source files) is documented
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
220 in FTDI-EEPROM-format article.
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
221
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
222 EEPROM size selection
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
223 ---------------------
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
224
80
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
225 In the original design of these tools the EEPROM size selection is made on the
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
226 command line, so that the same config can be programmed into a smaller EEPROM
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
227 or a bigger one. By default our tools generate an image suitable for a 93C46
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
228 EEPROM: the generated image is 64 words long, with a checksum in word 63, and
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
229 the EEPROM type byte in FTDI's structure is set to 0x46. Running with -b
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
230 produces an image for a 93C56 EEPROM: the EEPROM type byte is set to 0x56, and
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
231 the checksum-covered image length is extended to 128 words. Finally, -B sets
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
232 things up for a 93C66 EEPROM: the EEPROM type byte is set to 0x66, but the
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
233 generated checksum-covered image is still 128 words long just like with -b, as
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
234 that is what FT2232x chips apparently expect. I said "apparently" because I
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
235 don't have any FT2232x hardware with 93C66 EEPROMs and I don't plan on acquiring
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
236 or building any, hence this minimal 93C66 support is completely untested - use
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
237 at your own risk.
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
238
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
239 In the current design it is also possible to set the EEPROM size in the config
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
240 source file - if the EEPROM size is set there, the command line options for it
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
241 become redundant. If the command line options for EEPROM size conflict with
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
242 the config source, the result is an error. For symmetry with -b selecting 93C56
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
243 and -B selecting 93C66, there is also -s option selecting 93C46 explicitly.
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
244
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
245 It also needs to be noted that with our current RE-based understanding of FTDI's
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
246 undocumented EEPROM structure, using a bigger EEPROM does NOT provide more room
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
247 for strings: all that happens with -b and -B options is that a gap of 64 unused
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
248 EEPROM words is inserted between the end of the fixed structure and the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
249 beginning of strings. The exact same arrangement has been observed in all 93C56
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
250 EEPROM images found in the wild, presumably produced with FTDI's official tools,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
251 including FTDI's own USB-COM232-PLUS2 board - thus it is not clear at all if
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
252 FT2232x chips actually support longer strings with bigger EEPROMs, and if not,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
253 what does one need a bigger EEPROM for...
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
254
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
255 Installation directory for EEPROM config files
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
256 ----------------------------------------------
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
257
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
258 If the name of the config file passed to ftee-gen* does not contain any '/'
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
259 characters, the named file is sought first in an installation directory
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
260 (/opt/freecalypso/ftdi) and then in the current directory. To suppress this
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
261 search path and read EEPROM config files only from the current directory,
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
262 specify your config file as ./name - filenames (pathnames) containing slashes
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
263 are read as-is.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
264
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
265 This installation directory and search mechanism have been added in order to
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
266 allow standard (usually developed at FreeCalypso HQ) FTDI EEPROM configs which
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
267 end users can then program into their boards by executing a fixed command line
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
268 given in a manual.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
269
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
270 FT232R differences
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
271 ==================
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
272
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
273 The EEPROM generator tool for FT232R is ftee-gen232r; it works on the same
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
274 principle as ftee-gen2232[ch] for FT2232x. However, when you run fteeprom-prog
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
275 to program FT232R's internal EEPROM (whether you are restoring a backup or
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
276 programming the output of ftee-gen232r), you need to add -r option before the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
277 device selector string. This option tells fteeprom-prog to execute the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
278 FT232R-specific magic sequence (documented in FT232R-notes) before proceeding
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
279 to actual EEPROM writes - without this option the EEPROM content will be garbage
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
280 (bitwise AND of old and new EEPROM images), producing the appearance of a
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
281 bricked chip.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
282
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
283 In the previous libftdi-based version of fteeprom-prog the magic sequence in
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
284 question was executed unconditionally - however, because it is needed only for
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
285 FT232R and because we could simplify our new sans-libftdi code by implementing
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
286 it in an FT232R-only manner (no support for different "index" values for
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
287 multichannel FTDI devices), we've changed it from unconditional to -r option.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
288
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
289 Experiments show that fteeprom-prog -r option appears to be harmless (though
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
290 unnecessary) on FT2232D and FT2232H - however, Mother's recommendation is to
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
291 use it only on FT232R devices.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
292
34
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
293 Erasing the EEPROM (making it blank)
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
294 ====================================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
295
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
296 If you are playing with a "generic" FT2232x breakout board that is made for
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
297 tinkering, as opposed to a more finished product, such boards are typically
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
298 shipped with their EEPROMs completely blank. In that case restoring the EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
299 to its "pristine" state after playing around would mean erasing it, i.e.,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
300 bringing it into a blank (all ones) state. FT2232x chips provide two ways to
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
301 do so: one can explicitly write 0xFFFF into each individual EEPROM word with
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
302 SIO_WRITE_EEPROM_REQUEST, or one can send a SIO_ERASE_EEPROM_REQUEST command to
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
303 the chip, and the chip then erases the entire EEPROM. But we don't know how
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
304 the latter SIO_ERASE_EEPROM_REQUEST operation is implemented by FT2232x chips:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
305 does the FT2232x chip go through and erase each word individually, or does it
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
306 issue an "erase full chip" opcode to the serial EEPROM? If the latter, then
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
307 according to some EEPROM datasheets that operation may not work if the EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
308 is powered from a 3.3V rail rather than the full USB 5V - may be an issue in
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
309 FT2232H-based designs.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
310
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
311 In any case our tools provide both ways. To perform the "automatic full chip
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
312 erase" operation, run the following command:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
313
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
314 fteeprom-erase <device-selector>
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
315
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
316 To blank the EEPROM by writing 0xFFFF into each word, run one of the following
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
317 pipelines:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
318
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
319 ftee-mkblank | fteeprom-prog <device-selector> -- blank a 93C46 EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
320 ftee-mkblank -b | fteeprom-prog <device-selector> -- blank a 93C56 EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
321 ftee-mkblank -B | fteeprom-prog <device-selector> -- blank a 93C66 EEPROM
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
322
48
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options
Mychaela Falconia <falcon@freecalypso.org>
parents: 35
diff changeset
323 Unbinding of ftdi_sio ttyUSBx devices
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options
Mychaela Falconia <falcon@freecalypso.org>
parents: 35
diff changeset
324 =====================================
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
325
80
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
326 By default, fteeprom-prog and fteeprom-erase utilities command the Linux
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
327 kernel's ftdi_sio driver to unbind from all interfaces of the target chip,
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
328 causing all associated ttyUSB devices to disappear. These ttyUSB devices will
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
329 come back in the new configuration when you unplug and replug the USB device
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
330 after programming. If you are a hacker and you really know what you are doing,
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
331 you can suppress this logic with -n option - however, doing so is generally not
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
332 recommended:
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
333
80
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
334 * An unplug-replug manipulation is required for the new EEPROM programming to
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
335 take effect. Removal of ttyUSB devices forces the user to unplug and replug
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
336 the USB device to get them to come back.
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
337
80
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
338 * In the case of FT232R, the special magic sequence it requires for EEPROM
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
339 programming (fteeprom-prog -r) is invasive/disruptive to normal UART
930bd5316d56 doc/FTDI-EEPROM-tools: update for current state
Mychaela Falconia <falcon@freecalypso.org>
parents: 48
diff changeset
340 operation, hence it isn't really compatible with ttyUSB sticking around.
35
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version
Mychaela Falconia <falcon@freecalypso.org>
parents: 34
diff changeset
341
48
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options
Mychaela Falconia <falcon@freecalypso.org>
parents: 35
diff changeset
342 Please refer to Replug-after-EEPROM-write article for additional notes.