--- a/doc/FTDI-EEPROM-tools	Mon Apr 22 21:36:48 2019 +0000
+++ b/doc/FTDI-EEPROM-tools	Mon Apr 22 23:17:14 2019 +0000
@@ -107,11 +107,19 @@
 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.
+
 Programming the EEPROM
 ======================
 
-In terms of the primitives provided over USB, writing to EEPROMs behind FTDI
-chips is accomplished by writing one 16-bit word at a time: the
+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
@@ -126,3 +134,95 @@
 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.
+
+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