--- a/doc/FTDI-EEPROM-tools	Mon Sep 11 05:24:26 2023 +0000
+++ b/doc/FTDI-EEPROM-tools	Mon Sep 11 06:51:05 2023 +0000
@@ -1,243 +1,3 @@
-Mother Mychaela has developed a set of Linux command line tools for manipulating
-configuration EEPROMs that are attached to FT2232x devices and accessed in-band
-via USB.  This document describes these tools.
-
-Supported FTDI chips and EEPROMs
-================================
-
-The present tools work with 93C46, 93C56 and 93C66 EEPROMs attached behind
-FT2232x dual-channel UART/FIFO/MPSSE/etc chips, both FT2232C/D and FT2232H.
-We can read these EEPROMs for examination or backup, and we can program them
-with new bits, either restoring a previously saved backup or creating a new
-from-scratch configuration.  These EEPROM configurations (which we can save,
-restore or create from scratch) set the USB VID:PID and the textual strings
-naming the manufacturer, the product model and an optional serial number,
-select whether each FT2232x channel will come up in the default UART mode or
-one of the other EEPROM-configurable modes (245 FIFO, CPU-style FIFO or fast
-opto-isolated serial), and allow a few other obscure chip settings to be
-tweaked.
-
-Some work has also been done toward the goal of being able to program the
-internal EEPROM in FT232R chips (a very popular single-channel USB to UART
-converter needing no external components), but this work should be considered
-experimental: the tools appear to work on an UB232R module from Digi-Key
-(presumably containing a genuine FT232RQ chip) and on a no-name FT232RL adapter
-where the chip is uncertain, but because we have no real production use case
-yet, we are not ready to truly vouch for FT232R support.
-
-More generally:
-
-* our fteeprom-read tool should be able to read out the EEPROM content from
-  just about any FTDI chip;
-
-* our fteeprom-prog tool should be able to program a user-supplied set of bits
-  into any FTDI+EEPROM combo where the EEPROM is a separate chip, or into FT232R
-  internal EEPROM - but it most likely won't work for newer FT-X chips;
-
-* if the goal is to generate a new EEPROM config from scratch, as opposed to
-  restoring a saved backup, we currently have generators only for FT2232C/D,
-  for FT2232H and for FT232R, with the last one considered experimental and not
-  proven.
-
-libftdi dependency
-==================
-
-We use libftdi (which is in turn layered on libusb) to issue the special USB
-control pipe commands to FTDI chips which are needed to read and write their
-EEPROMs.  We use old-style libftdi-0.x (-lftdi on the link line) as opposed to
-libftdi1 (-lftdi1) because the new versions took away the ability to write to
-the EEPROM directly with ftdi_write_eeprom_location() calls, forcing users to
-go through libftdi1's own EEPROM smarts, which we don't want to do - our tools
-are all about more direct user empowerment at the lowest level.
-
-Selecting the device to operate on
-==================================
-
-Our fteeprom-read, fteeprom-prog and fteeprom-erase tools take a device selector
-argument, selecting the device to operate on.  This required argument is the
-string to be passed to the ftdi_usb_open_string() function in libftdi, allowing
-the device to be operated on to be selected in one of several ways.  Copying
-from libftdi documentation, the available formats are:
-
-d:<devicenode> - path of bus and device-node (e.g. "003/001") within usb device
-tree (usually at /proc/bus/usb/)
-
-i:<vendor>:<product> - first device with given vendor and product id, ids can
-be decimal, octal (preceded by "0") or hex (preceded by "0x")
-
-i:<vendor>:<product>:<index> - as above with index being the number of the
-device (starting with 0) if there are more than one
-
-s:<vendor>:<product>:<serial> - first device with given vendor id, product id
-and serial string
-
-If you have only one FTDI device connected to your PC or laptop at the time of
-your EEPROM manipulation session (generally a good idea to avoid hitting the
-wrong device by mistake) and if that FTDI device has some sensible starting
-USB VID:PID (either from the previous EEPROM config or the chip's sans-EEPROM
-default) that doesn't clash with anything else, then the i: form will probably
-be the most convenient, e.g.:
-
-i:0x0403:0x6001 for single-channel FT232x devices running with the default ID
-i:0x0403:0x6010 for dual-channel FT2232x devices running with the default ID
-i:0x0403:0xPPPP for custom PIDs assigned out of FTDI's VID range
-i:0xVVVV:0xPPPP for totally custom USB IDs
-
-Or if the current device config is totally hosed (the EEPROM has a passing
-checksum, but sets some completely bogus USB ID), then the d: form will
-probably be required for recovery.
-
-Reading the EEPROM
-==================
-
-The basic EEPROM read command is as follows:
-
-fteeprom-read <device-selector>
-
-See the previous section for the device selector argument.  In this default
-form the tool will read the first 64 EEPROM words, which is appropriate for
-93C46 external EEPROMs or for the internal 1024-bit EEPROM in the FT232R chip.
-However, if you are working with an FT2232x board with an external EEPROM and
-that EEPROM is of a larger variety (93C56 or 93C66), this basic form with give
-you an incomplete (truncated) read, and you will need one of the following
-extended forms to read the complete EEPROM:
-
-fteeprom-read -b <device-selector>	-- read 128 EEPROM words (93C56)
-fteeprom-read -B <device-selector>	-- read 256 EEPROM words (93C66)
-
-(If you use one of the extended forms on a smaller EEPROM, you will get 2 or 4
- copies of the same bits.)
-
-The output of fteeprom-read is in the same format as the input to fteeprom-prog,
-thus you can redirect the output to a file and get a restorable backup copy of
-your EEPROM.
-
-It also needs to be noted that if the FTDI device has the kernel's ftdi_sio
-driver attached to it (ttyUSB device present) when you run fteeprom-read (same
-for fteeprom-prog and fteeprom-erase), the act of running any of our EEPROM
-tools will cause it to unbind, i.e., the ttyUSB device will disappear.  If the
-device being operated on is a dual-channel FT2232x, then only the ttyUSB device
-corresponding to Channel A will disappear, while the Channel B ttyUSB device
-will stay.
+This article has moved; the new location is:
 
-Programming the EEPROM
-======================
-
-In terms of the primitives provided over USB, writing to EEPROMs sitting behind
-FTDI chips is accomplished by writing one 16-bit word at a time: the
-SIO_WRITE_EEPROM_REQUEST command writes a user-supplied word at a user-supplied
-EEPROM address.  However, our fteeprom-prog tool currently supports only writing
-complete EEPROMs (64 or 128 or 256 16-bit words starting at address 0) and we
-do not currently provide any kind of "random access write" utility; the primary
-reason for this design decision is practical usefulness: FTDI's EEPROM structure
-includes a checksum over the first 64 words for 1024-bit EEPROMs or over the
-first 128 words for larger ones, and if this checksum fails to match, the entire
-structure is deemed to be invalid - hence there is no practical use case for
-selectively rewriting individual words.  The only exception may be with 93C66
-EEPROMs: on these giants only the first half would be subject to the checksum,
-and the second half could be used arbitrarily.  However, we have not yet
-encountered any boards out in the wild with such big EEPROMs, and we have no
-plans to use such in any of our own hardware designs either, hence there is no
-business case at the present moment to develop tooling support for them.
-
-There are two primary modes of usage for our fteeprom-prog tool: restoring a
-saved EEPROM backup or writing a new EEPROM config which you generate yourself.
-To restore a saved EEPROM backup, run the tool as follows:
-
-fteeprom-prog <device-selector> <eeprom-image-file>
-
-To program a new EEPROM config of your own, run a pipeline of this form:
-
-<generator-tool> | fteeprom-prog <device-selector>
-
-fteeprom-prog reads the EEPROM image from stdin if no image file is named on
-the command line; the image format is the same in both cases, and the length of
-this EEPROM image tells the tool how many words need to be programmed - there
-are no -b or -B options to fteeprom-prog.
-
-Generator tools
-===============
-
-Unfortunately FTDI never documented the format of their EEPROM configuration
-structure - apparently they consider it a proprietary trade secret just like
-the wire protocol spoken over USB between their chips and their closed-source
-proprietary drivers.  All FOSS community support for these chips is based on
-reverse engineering, and that includes the EEPROM format.
-
-The present suite of tools includes ftee-gen2232c and ftee-gen2232h EEPROM image
-generators, meant for use with FT2232C/D and FT2232H chips, respectively.  These
-tools are based on the knowledge extracted from other (pre-existing) community
-tools, primarily the EEPROM config code built into various libftdi versions -
-we haven't done any FTDI RE of our own, instead the goal of this project has
-been to create a set of tools that are better fit for production use.
-
-Our ftee-gen2232c and ftee-gen2232h tools are invoked as follows:
-
-ftee-gen2232[ch] [-b|-B] <config-file> [serial-num]
-
-The output of these generator tools is meant to be piped directly into
-fteeprom-prog.
-
-The philosophy of which settings are given in the config file vs. which ones
-are given on the command line reflects configuration management and factory
-production line operations.  In the envisioned usage there would be a config
-file for each product, giving the USB VID:PID, textual manufacturer and product
-ID strings and possibly other config settings which need to be changed from the
-defaults, but the optional serial number string is given on the command line
-because it would be different for each individual unit being programmed.
-
-The EEPROM size selection is also made on the command line, so that the same
-config can be programmed into a smaller EEPROM or a bigger one.  By default our
-tools generate an image suitable for a 93C46 EEPROM: the generated image is 64
-words long, with a checksum in word 63, and the EEPROM type byte in FTDI's
-structure is set to 0x46.  Running with -b produces an image for a 93C56 EEPROM:
-the EEPROM type byte is set to 0x56, and the checksum-covered image length is
-extended to 128 words.  Finally, -B sets things up for a 93C66 EEPROM: the
-EEPROM type byte is set to 0x66, but the generated checksum-covered image is
-still 128 words long just like with -b, as that is what FT2232x chips apparently
-expect.  I said "apparently" because I don't have any FT2232x hardware with
-93C66 EEPROMs and I don't plan on acquiring or building any, hence this minimal
-93C66 support is completely untested - use at your own risk.
-
-It also needs to be noted that with our current RE-based understanding of FTDI's
-undocumented EEPROM structure, using a bigger EEPROM does NOT provide more room
-for strings: all that happens with -b and -B options is that a gap of 64 unused
-EEPROM words is inserted between the end of the fixed structure and the
-beginning of strings.  The exact same arrangement has been observed in all 93C56
-EEPROM images found in the wild, presumably produced with FTDI's official tools,
-including FTDI's own USB-COM232-PLUS2 board - thus it is not clear at all if
-FT2232x chips actually support longer strings with bigger EEPROMs, and if not,
-what does one need a bigger EEPROM for...
-
-For the format of config files read by our ftee-gen2232[ch] tools and what
-settings can be tweaked, read the source code.
-
-Erasing the EEPROM (making it blank)
-====================================
-
-If you are playing with a "generic" FT2232x breakout board that is made for
-tinkering, as opposed to a more finished product, such boards are typically
-shipped with their EEPROMs completely blank.  In that case restoring the EEPROM
-to its "pristine" state after playing around would mean erasing it, i.e.,
-bringing it into a blank (all ones) state.  FT2232x chips provide two ways to
-do so: one can explicitly write 0xFFFF into each individual EEPROM word with
-SIO_WRITE_EEPROM_REQUEST, or one can send a SIO_ERASE_EEPROM_REQUEST command to
-the chip, and the chip then erases the entire EEPROM.  But we don't know how
-the latter SIO_ERASE_EEPROM_REQUEST operation is implemented by FT2232x chips:
-does the FT2232x chip go through and erase each word individually, or does it
-issue an "erase full chip" opcode to the serial EEPROM?  If the latter, then
-according to some EEPROM datasheets that operation may not work if the EEPROM
-is powered from a 3.3V rail rather than the full USB 5V - may be an issue in
-FT2232H-based designs.
-
-In any case our tools provide both ways.  To perform the "automatic full chip
-erase" operation, run the following command:
-
-fteeprom-erase <device-selector>
-
-To blank the EEPROM by writing 0xFFFF into each word, run one of the following
-pipelines:
-
-ftee-mkblank | fteeprom-prog <device-selector>		-- blank a 93C46 EEPROM
-ftee-mkblank -b | fteeprom-prog <device-selector>	-- blank a 93C56 EEPROM
-ftee-mkblank -B | fteeprom-prog <device-selector>	-- blank a 93C66 EEPROM
+https://www.freecalypso.org/hg/fc-usbser-tools/file/tip/doc/FTDI-EEPROM-tools