# HG changeset patch # User Mychaela Falconia # Date 1695935613 0 # Node ID 4f72e09fb698642da5d6232ef2115a9d8253099b # Parent ba741a1af0e3a968152e1b3b184d0ebc0400997d doc/CP2102-EEPROM-tools: complete for now diff -r ba741a1af0e3 -r 4f72e09fb698 doc/CP2102-EEPROM-tools --- 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.