--- a/doc/CP2102-EEPROM-tools	Thu Sep 28 06:35:39 2023 +0000
+++ b/doc/CP2102-EEPROM-tools	Thu Sep 28 21:13:33 2023 +0000
@@ -50,3 +50,95 @@
 
 After this programming operation, unplug and replug the USB device - see
 Replug-after-EEPROM-write article for more info.
+
+More detailed theory
+====================
+
+FreeCalypso CP2102 EEPROM tools are built on a different principle than our FTDI
+EEPROM tools.  In the case of FTDI chips, our tools are designed to generate
+EEPROM images de novo - this approach is necessary because in the case of
+FT2232x and other FTDI chips that use external EEPROMs, those EEPROMs start out
+blank.  The internal EEPROM of CP2102 is different - this EEPROM already holds
+a valid image as the chip leaves Silabs, and valid EEPROM content is required
+for this chip to function - thus there is no use case for constructing CP2102
+EEPROM images de novo.  Instead we provide the following tools for CP2102:
+
+* cp2102-read-eeprom reads the full EEPROM content out of the chip and saves it
+  in an Intel HEX file.  The file format has been copied from Python-language
+  cp210x-program-1.0 and is suspected (without certain proof) of also being the
+  format used by Silabs' own tools.
+
+* cp2102-write-eeprom programs the chip's EEPROM with a new image read from an
+  Intel HEX file.
+
+* cp2102-decode-baudtab and cp2102-decode-ee-desc read Intel HEX images of
+  EEPROMs and decode portions of interest: the baud rate table and USB
+  descriptors, respectively.
+
+* cp2102-patch-ee-image reads an Intel HEX EEPROM image, applies a set of
+  patches to it, and writes out a new Intel HEX EEPROM image.
+
+* cp2102-update-eeprom applies a set of EEPROM patches directly in place: reads
+  current EEPROM content from a physical chip, applies the desired patches and
+  writes the new EEPROM image into the hardware.  This utility replaces the
+  cumbersome sequence of cp2102-read-eeprom, cp2102-patch-ee-image and
+  cp2102-write-eeprom for most common workflows.
+
+* cp2102-read-baudtab combines the steps of cp2102-read-eeprom and
+  cp2102-decode-baudtab into a single command that works without intermediate
+  files - an easy utility for the common use case of checking the current baud
+  rate table programming.
+
+Selecting the device to operate on
+==================================
+
+By default our CP2102 tools look for USB ID 10C4:EA60, which is the default ID
+code for CP2102; if there is more than one USB device with this ID, the tool
+hits the first matching device it finds.  If you need to operate on a CP2102
+chip whose ID code has been changed away from the default, or if you need to
+select one of several USB devices with the same ID code, you can pass a device
+selector string (see FTDI-EEPROM-tools article - we've implemented the same
+mechanism for CP2102, even though it originates from libftdi) with -d option.
+For example, to read the baud rate table from the CP2102 inside a Pirelli DP-L10
+phone, run this command:
+
+cp2102-read-baudtab -d i:0x0489:0xE003
+
+EEPROM patch language
+=====================
+
+The "canonical" use case for patching CP2102 EEPROM config would be designing a
+new custom hw gadget that contains a CP2102 chip and configuring that USB
+interface chip with custom ID strings, or perhaps a custom VID:PID code or other
+USB descriptor changes.  However, it is now 2023, and we (FreeCalypso) are not
+planning on building any new hw with CP2102 chips - thus in the present time
+the only real use case for CP2102 EEPROM manipulation is programming the baud
+rate table on already existing CP2102-based cables and adapters (particularly
+those sold by Sysmocom) to switch between 230400/460800/921600 baud and
+203125/406250/812500 baud configs, or perhaps configure other non-standard baud
+rates for various hacking applications.
+
+Nonetheless and for the sake of completeness, our cp2102-update-eeprom and
+cp2102-patch-ee-image tools allow any part of the EEPROM structure to be
+patched: the baud rate table can be replaced in whole or in part, any bytes in
+any of the USB descriptors can be patched, and new textual ID strings can be
+set.
+
+Given the lack of real-life use cases beyond switching between two possible baud
+rate tables of interest as described earlier in this article, the full EEPROM
+patching mechanism is not currently documented in detail - read the source code
+if you are interested.
+
+Checking CP2102 chip version
+============================
+
+To check if your CP2102 adapter is really classic CP2102 or CP2102N or some
+other CP210x, run this command:
+
+cp2102-read-partno
+
+The result should be 0x02 on classic CP2102 or various codes (0x20, 0x21 or 0x22
+depending on QFN package variant) on CP2102N.  Note that at least on classic
+CP2102 this byte is stored in the EEPROM and can be modified - but hopefully no
+sane person will patch the EEPROM on a classic CP2102 to make it pretend to be
+CP2102N.