# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1695600262 0
# Node ID 6dc3aa777fd6c16110b7c3f4615bc3cccd4f9322
# Parent  0b37be8b23ca34ac6bce04d94355b6daee0f8e45
doc/FTDI-EEPROM-format: document config file language

diff -r 0b37be8b23ca -r 6dc3aa777fd6 doc/FTDI-EEPROM-format
--- a/doc/FTDI-EEPROM-format	Sun Sep 24 22:27:38 2023 +0000
+++ b/doc/FTDI-EEPROM-format	Mon Sep 25 00:04:22 2023 +0000
@@ -326,3 +326,65 @@
 EEPROM to include longer strings - but designing a product with unnaturally
 long ID strings, so long that FTDI's official tools won't support them, seems
 like a bad idea.
+
+ftee-gen* tools: config file language
+=====================================
+
+The format of EEPROM config files read by our ftee-gen* tools is line-based.
+Each non-blank, non-comment line defines or tweaks one setting.  The following
+settings are common to all ftee-gen* chip variants:
+
+Setting		Format	Meaning
+-------------------------------
+vid		hex	USB vendor ID
+pid		hex	USB product ID
+manuf		string	Manufacturer ID string
+product		string	Product ID string
+byte00		hex	Raw setting of byte 00
+byte01		hex	Raw setting of byte 01
+byte08		hex	Raw setting of byte 08
+byte0A		hex	Raw setting of byte 0A
+maxpower	decimal	bMaxPower declaration, number in mA
+usbver		hex	bcdUSB word (ftee-gen2232c and ftee-gen232r only)
+
+Additional settings for FT2232H (ftee-gen2232h):
+
+group0		hex	I/O electrical config for ADBUSx
+group1		hex	I/O electrical config for ACBUSx
+group2		hex	I/O electrical config for BDBUSx
+group3		hex	I/O electrical config for BCBUSx
+
+Additional settings for FT232R (ftee-gen232r):
+
+byte0B		hex	Raw setting of byte 0B
+cbus0		hex	CBUS0 config code
+cbus1		hex	CBUS1 config code
+cbus2		hex	CBUS2 config code
+cbus3		hex	CBUS3 config code
+cbus4		hex	CBUS4 config code
+
+Only two settings are strictly mandatory: manuf and product strings.  For all
+other settings the EEPROM generator tool provides chip-matching defaults:
+
+* ftee-gen2232[ch] defaults match the configuration attained by the chip
+  with a blank or missing EEPROM;
+
+* ftee-gen232r defaults match FTDI's default factory programming of the
+  chip-internal EEPROM.
+
+As one can see, the config language is very low-level, most bits are set in raw
+hex.  This design is justified by the paradigm of writing each config file once:
+if you are designing a new board with an FTDI chip on it, and you need to change
+some setting away from the FTDI chip's default, you research it once, figure out
+the right bits, code the needed byte-level configuration in an EEPROM config
+file, and then you just run a standard command line every time you need to
+program a board.
+
+The serial number string is never specified in the config file, instead it is
+specified on the command line - this tool design is in accord with factory
+production paradigm, where each EEPROM config is written once for a given board
+design, and then a shell pipeline is executed for each board to be programmed.
+
+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.