--- a/doc/FTDI-EEPROM-format	Tue Sep 26 01:37:33 2023 +0000
+++ b/doc/FTDI-EEPROM-format	Tue Sep 26 02:44:52 2023 +0000
@@ -336,6 +336,8 @@
 
 Setting		Format	Meaning
 -------------------------------
+ftdi-chip	keyword	Type of FTDI chip this config source was written for
+eeprom		keyword	EEPROM size selector (not in ftee-gen232r)
 vid		hex	USB vendor ID
 pid		hex	USB product ID
 manuf		string	Manufacturer ID string
@@ -388,3 +390,58 @@
 Byte 0A bit 3 is always overridden by the generator tool based on the serial
 number command line argument: set if a serial number is given and cleared if
 this argument is omitted.
+
+FTDI chip type matching
+-----------------------
+
+The design of FreeCalypso FTDI EEPROM tools calls for mostly manual matching
+between EEPROM config files and generator tools: the operator is responsible
+for selecting the correct tool (ftee-gen2232c, ftee-gen2232h or ftee-gen232r)
+for the actual FTDI chip on the board of interest, and also responsible for
+feeding correct EEPROM config files to this tool.  However, now that we are
+starting to give EEPROM programming instructions to end users in the form of
+"please run this shell pipeline", there is a natural desire to reduce potential
+for operator error: if someone takes an EEPROM config file written for one FTDI
+chip and feeds it to an ftee-gen* tool for a different chip, it would be nice
+for this invalid combination to be detected and rejected.
+
+Toward this end, the following optional settings may be included in EEPROM
+config source files:
+
+ftdi-chip FT2232C	# config valid only for ftee-gen2232c
+ftdi-chip FT2232D	# same as FT2232C
+ftdi-chip FT2232H	# config valid only for ftee-gen2232h
+ftdi-chip FT2232x	# config valid for ftee-gen2232c and ftee-gen2232h
+ftdi-chip FT232R	# config valid only for ftee-gen232r
+
+EEPROM size selection
+---------------------
+
+In the case of EEPROM generator tools for FTDI chips with external EEPROMs,
+one of the following settings may be included in the config source:
+
+eeprom 93C46
+eeprom 93C56
+eeprom 93C66
+
+If one of these settings is included, the EEPROM size is fixed; if an EEPROM
+size option (-s, -b or -B) is included on the command line, it must match the
+config-set EEPROM size, otherwise the tool bails out with an error.  If no
+eeprom setting is included in the config file, then any EEPROM size may be
+selected with command line options, and if no such options are included on the
+command line either, then the final default is 93C46.
+
+Preparing config files for boards
+---------------------------------
+
+If you have a specific board design with an FTDI chip and are preparing an
+EEPROM config file for your board, our recommendation is to include ftdi-chip
+and eeprom lines in your config file, naming the specific FTDI chip and the
+specific EEPROM size on your board.  By doing so, you reduce the possibility
+that someone will misprogram your EEPROM by selecting the wrong generator tool
+or the wrong EEPROM size.
+
+The alternative approach of leaving these settings unspecified or underspecified
+should be used for unfinished EEPROM config templates or examples, or configs
+that can be sensibly loaded into many different boards that may vary in FT2232x
+chip choice and EEPROM size.