FreeCalypso > hg > fc-usbser-tools

comparison doc/CP2102-EEPROM-tools @ 102:4f72e09fb698

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/CP2102-EEPROM-tools: complete for now
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 28 Sep 2023 21:13:33 +0000
parents ba741a1af0e3
children
comparison
equal deleted inserted replaced
101:ba741a1af0e3 102:4f72e09fb698
48 48
49 cp2102-update-eeprom -b std 49 cp2102-update-eeprom -b std
50 50
51 After this programming operation, unplug and replug the USB device - see 51 After this programming operation, unplug and replug the USB device - see
52 Replug-after-EEPROM-write article for more info. 52 Replug-after-EEPROM-write article for more info.
53
54 More detailed theory
55 ====================
56
57 FreeCalypso CP2102 EEPROM tools are built on a different principle than our FTDI
58 EEPROM tools. In the case of FTDI chips, our tools are designed to generate
59 EEPROM images de novo - this approach is necessary because in the case of
60 FT2232x and other FTDI chips that use external EEPROMs, those EEPROMs start out
61 blank. The internal EEPROM of CP2102 is different - this EEPROM already holds
62 a valid image as the chip leaves Silabs, and valid EEPROM content is required
63 for this chip to function - thus there is no use case for constructing CP2102
64 EEPROM images de novo. Instead we provide the following tools for CP2102:
65
66 * cp2102-read-eeprom reads the full EEPROM content out of the chip and saves it
67 in an Intel HEX file. The file format has been copied from Python-language
68 cp210x-program-1.0 and is suspected (without certain proof) of also being the
69 format used by Silabs' own tools.
70
71 * cp2102-write-eeprom programs the chip's EEPROM with a new image read from an
72 Intel HEX file.
73
74 * cp2102-decode-baudtab and cp2102-decode-ee-desc read Intel HEX images of
75 EEPROMs and decode portions of interest: the baud rate table and USB
76 descriptors, respectively.
77
78 * cp2102-patch-ee-image reads an Intel HEX EEPROM image, applies a set of
79 patches to it, and writes out a new Intel HEX EEPROM image.
80
81 * cp2102-update-eeprom applies a set of EEPROM patches directly in place: reads
82 current EEPROM content from a physical chip, applies the desired patches and
83 writes the new EEPROM image into the hardware. This utility replaces the
84 cumbersome sequence of cp2102-read-eeprom, cp2102-patch-ee-image and
85 cp2102-write-eeprom for most common workflows.
86
87 * cp2102-read-baudtab combines the steps of cp2102-read-eeprom and
88 cp2102-decode-baudtab into a single command that works without intermediate
89 files - an easy utility for the common use case of checking the current baud
90 rate table programming.
91
92 Selecting the device to operate on
93 ==================================
94
95 By default our CP2102 tools look for USB ID 10C4:EA60, which is the default ID
96 code for CP2102; if there is more than one USB device with this ID, the tool
97 hits the first matching device it finds. If you need to operate on a CP2102
98 chip whose ID code has been changed away from the default, or if you need to
99 select one of several USB devices with the same ID code, you can pass a device
100 selector string (see FTDI-EEPROM-tools article - we've implemented the same
101 mechanism for CP2102, even though it originates from libftdi) with -d option.
102 For example, to read the baud rate table from the CP2102 inside a Pirelli DP-L10
103 phone, run this command:
104
105 cp2102-read-baudtab -d i:0x0489:0xE003
106
107 EEPROM patch language
108 =====================
109
110 The "canonical" use case for patching CP2102 EEPROM config would be designing a
111 new custom hw gadget that contains a CP2102 chip and configuring that USB
112 interface chip with custom ID strings, or perhaps a custom VID:PID code or other
113 USB descriptor changes. However, it is now 2023, and we (FreeCalypso) are not
114 planning on building any new hw with CP2102 chips - thus in the present time
115 the only real use case for CP2102 EEPROM manipulation is programming the baud
116 rate table on already existing CP2102-based cables and adapters (particularly
117 those sold by Sysmocom) to switch between 230400/460800/921600 baud and
118 203125/406250/812500 baud configs, or perhaps configure other non-standard baud
119 rates for various hacking applications.
120
121 Nonetheless and for the sake of completeness, our cp2102-update-eeprom and
122 cp2102-patch-ee-image tools allow any part of the EEPROM structure to be
123 patched: the baud rate table can be replaced in whole or in part, any bytes in
124 any of the USB descriptors can be patched, and new textual ID strings can be
125 set.
126
127 Given the lack of real-life use cases beyond switching between two possible baud
128 rate tables of interest as described earlier in this article, the full EEPROM
129 patching mechanism is not currently documented in detail - read the source code
130 if you are interested.
131
132 Checking CP2102 chip version
133 ============================
134
135 To check if your CP2102 adapter is really classic CP2102 or CP2102N or some
136 other CP210x, run this command:
137
138 cp2102-read-partno
139
140 The result should be 0x02 on classic CP2102 or various codes (0x20, 0x21 or 0x22
141 depending on QFN package variant) on CP2102N. Note that at least on classic
142 CP2102 this byte is stored in the EEPROM and can be modified - but hopefully no
143 sane person will patch the EEPROM on a classic CP2102 to make it pretend to be
144 CP2102N.