--- a/doc/FTDI-EEPROM-tools	Tue Sep 26 02:44:52 2023 +0000
+++ b/doc/FTDI-EEPROM-tools	Tue Sep 26 04:29:54 2023 +0000
@@ -134,6 +134,22 @@
 regard: you can now freely read the EEPROM of any connected FTDI device
 *without* bumping off that device's ttyUSB.
 
+Decoding EEPROM dumps
+=====================
+
+The output of fteeprom-read is a raw hex dump of the EEPROM; a few of these
+dumps are included in the artifacts directory in the fc-usbser-tools
+distribution.  You can study these dumps directly in hex using the knowledge
+base gathered in FTDI-EEPROM-format article, but there is also a utility that
+decodes the most basic EEPROM settings that are common across all known FTDI
+chips.  You can run ftee-decode like this:
+
+ftee-decode <eeprom-image-file>
+
+or reading from stdin:
+
+fteeprom-read <device-selector> | ftee-decode -
+
 Programming the EEPROM
 ======================
 
@@ -183,11 +199,12 @@
 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.
+been to create a set of tools that are better fit for production use.  The
+knowledge base we have collected is documented in FTDI-EEPROM-format article.
 
 Our ftee-gen2232c and ftee-gen2232h tools are invoked as follows:
 
-ftee-gen2232[ch] [-b|-B] <config-file> [serial-num]
+ftee-gen2232[ch] [size-option] <config-file> [serial-num]
 
 The output of these generator tools is meant to be piped directly into
 fteeprom-prog.
@@ -198,20 +215,32 @@
 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.
+because it would be different for each individual unit being programmed.  The
+detailed format of ftee-gen* input language (config source files) is documented
+in FTDI-EEPROM-format article.
+
+EEPROM size selection
+---------------------
 
-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.
+In the original design of these tools the EEPROM size selection is 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.
+
+In the current design it is also possible to set the EEPROM size in the config
+source file - if the EEPROM size is set there, the command line options for it
+become redundant.  If the command line options for EEPROM size conflict with
+the config source, the result is an error.  For symmetry with -b selecting 93C56
+and -B selecting 93C66, there is also -s option selecting 93C46 explicitly.
 
 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
@@ -223,9 +252,6 @@
 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.
-
 Installation directory for EEPROM config files
 ----------------------------------------------
 
@@ -297,21 +323,20 @@
 Unbinding of ftdi_sio ttyUSBx devices
 =====================================
 
-When invoked without any options, current versions of fteeprom-prog and
-fteeprom-erase do NOT unbind the kernel's ftdi_sio driver from any of the chip's
-interfaces, thus none of the associated ttyUSB devices disappear.  This behavior
-can be modified as follows:
+By default, fteeprom-prog and fteeprom-erase utilities command the Linux
+kernel's ftdi_sio driver to unbind from all interfaces of the target chip,
+causing all associated ttyUSB devices to disappear.  These ttyUSB devices will
+come back in the new configuration when you unplug and replug the USB device
+after programming.  If you are a hacker and you really know what you are doing,
+you can suppress this logic with -n option - however, doing so is generally not
+recommended:
 
-* Both fteeprom-prog and fteeprom-erase support -d1, -d2 and -d4 options.  These
-  options instruct the tool to command the kernel to unbind from one, two or
-  four interfaces on the target chip - they should be used with FT232x, FT2232x
-  and FT4232x, respectively.
+* An unplug-replug manipulation is required for the new EEPROM programming to
+  take effect.  Removal of ttyUSB devices forces the user to unplug and replug
+  the USB device to get them to come back.
 
-* fteeprom-prog running with -r option (FT232R special mode) and no -d options
-  defaults to -d1.  This default was made because -r option is intended only for
-  FT232R, which is known to be a single-channel chip, and the special magic
-  sequence is invasive/disruptive to normal UART operation, hence it isn't
-  really compatible with ttyUSB sticking around.  If you are a hacker and you
-  really know what you are doing, you can defeat this logic with -r -d0.
+* In the case of FT232R, the special magic sequence it requires for EEPROM
+  programming (fteeprom-prog -r) is invasive/disruptive to normal UART
+  operation, hence it isn't really compatible with ttyUSB sticking around.
 
 Please refer to Replug-after-EEPROM-write article for additional notes.