--- a/doc/High-speed-serial	Sun Dec 10 01:24:14 2023 +0000
+++ b/doc/High-speed-serial	Sun Dec 10 23:42:12 2023 +0000
@@ -5,11 +5,25 @@
 though these high baud rates aren't supported by "standard" RS-232 serial ports
 on PCs, they *are* supported by some of the better USB to serial adapters,
 namely CP2102 (USB to single UART) and the FT2232x family (USB to two UARTs).
-The Pirelli DP-L10 phone supported by FreeCalypso host tools has a CP2102 built
-in, the officially recommended 2.5 mm headset jack USB-serial cables for working
-with Motorola C1xx and Openmoko GTA01/02 phones also use CP2102 adapters,
-whereas our FreeCalypso development boards (FCDEV3B) are typically used with an
-FT2232D or other FT2232x USB to dual UART adapter.
+Both FTDI and CP2102 USB-serial adapters are officially endorsed in FreeCalypso
+queendom:
+
+* FreeCalypso DUART28 adapter (USB to dual UART at 2.8V, electrically optimized
+  for direct connection to Calypso UARTs) is based on FT2232D;
+
+* For working with older Calypso devboards such as TI D-Sample and iWOW DSK
+  (two RS-232 UARTs), FTDI board USB-COM232-PLUS2 (based on FT2232H) is
+  officially recommended;
+
+* Future FreeCalypso development boards will likely include a built-in FT2232H
+  subsystem;
+
+* For working with Motorola C1xx and Openmoko GTA01/02 phones (Calypso UART
+  access via 2.5 mm headset jack), the cable we officially recommend is based
+  on CP2102;
+
+* Pirelli DP-L10 is a Calypso phone with a built-in CP2102 USB-serial interface,
+  supported since the beginning of FreeCalypso project.
 
 FreeCalypso tools can use these high serial baud rates in the following ways:
 
@@ -33,8 +47,8 @@
   utilities support this mode of operation by providing options to select
   different baud rates.
 
-Recent changes for better FTDI adapter support
-==============================================
+FreeCalypso host tools approach to FTDI adapter support
+=======================================================
 
 There is one fundamental difference between the way CP2102 adapters support
 non-standard baud rates (like the high GSM baud rates of interest to us) and
@@ -58,13 +72,13 @@
 by way of a hacky patch to the ftdi_sio driver in the Linux kernel to achieve
 the same effect with rarely-needed FTDI adapters.
 
-The situation has changed with the introduction of our own FreeCalypso
-development boards (currently FCDEV3B, possibly others in the future) which
-bring out both Calypso UARTs to the user, rather than just one.  The most
-convenient serial adapters for working with these dual UARTs are FT2232x (our
-current official adapter is FT2232D), thus we now have a strong need to support
-the use of these FTDI adapters, including the use of high GSM baud rates, in a
-manner which does not fight against the mainline Linux kernel.
+The situation has changed as our project transitioned from hacking on Motorola,
+Openmoko and Pirelli phones to proper Calypso GSM MS development boards,
+bringing out both Calypso UARTs rather than just one.  The most convenient
+serial adapters for working with these dual UARTs are FT2232x, thus we now have
+a strong need to support the use of these FTDI adapters, including the use of
+high GSM baud rates, in a manner which does not fight against the mainline
+Linux kernel.
 
 In a radical change from fc-host-tools-r6 and earlier, the present version of
 FreeCalypso host tools uses new libserial code that differs from the old code
@@ -78,13 +92,12 @@
 * When the user requests 203125, 406250 or 812500 baud, these are the actual
   baud rates requested from the kernel, not 230400/460800/921600 baud.
 
-This change is expected to have no adverse effect on the existing CP2102 users,
+This change is expected to have no adverse effect on existing CP2102 users,
 as the cp210x driver in Linux appears to cope fine with the strange baud rate
 requests from userspace and the correct CP2102 EEPROM baud rate entry still
-gets selected (tested on Slackware 13.37 and Debian 9), but when working with
-FTDI adapters such as our FT2232D adapter for the FCDEV3B this change makes the
-high GSM baud rates work without needing the dirty kernel patch which the
-Mother has been using up until now.
+gets selected (tested on Slackware 13.37, Slackware 14.2 and Debian 9), but
+when working with FTDI adapters, this change makes our high GSM baud rates work
+without needing the dirty kernel patch which we used in the early part of 2017.
 
 Support for other Unix flavors
 ==============================
@@ -110,7 +123,7 @@
 
 * If you don't need high GSM baud rates or need them only with CP2102 adapters
   which "magically" remap them, you should be able to use libserial-posix.  You
-  can also completely remove the entries for the high GSM baud rates from
+  can also completely remove the entries for high GSM baud rates from
   libserial-posix/baudtab.c if you don't need these high baud rates and your
   version of termios does not have B230400/B460800/B921600 baud rate constants.
 
@@ -125,6 +138,14 @@
 Using CP2102 adapters with Mot C1xx and Openmoko phones
 =======================================================
 
+For the special USB-serial cable that connects to the 2.5 mm headset jack on
+these phones, our current official recommendation is this one:
+
+https://shop.sysmocom.de/Sysmocom-USB-serial-cable-CP2102-with-2.5mm-stereo-jack/cp2102-25
+
+(In the past we also worked with a different vendor, UberWaves, but that vendor
+ appears to be no longer active as of 2023-12.)
+
 As already mentioned above, CP2102 chips have a built-in EEPROM that contains
 (among other things) a 32-entry table in which the supported serial baud rates
 are programmed.  In order to support the special GSM baud rates, these rates
@@ -133,26 +154,29 @@
 at the factory for GSM baud rates) is that 203120 baud takes the place of
 230400, 406250 takes the place of 460800, and 812500 takes the place of 921600.
 
-Because you need a special cable anyway to make the necessary physical
-connection to the debug/programming serial port presented on a 2.5 mm headset
-jack, you will probably be buying the requisite cable from a specialized
-professional vendor.  In that case it is that vendor's responsibility to sell
-you the cable with the CP2102 chip already programmed with GSM baud rates:
-because the physical construction of the cable (2.5 mm headset jack on the
-serial end) makes it specific to GSM devices, and all known GSM devices use a
-13 MHz clock or some integer multiple thereof, it is pointless for a
-physically-GSM-specific cable to be set up for 230400/460800/921600 baud when
-all known GSM devices will need 203125/406250/812500 baud instead.
+If you are working with CP2102 adapters from any vendor, or headset jack serial
+cables that incorporate such adapters, you should install this companion tools
+package from FreeCalypso:
+
+https://www.freecalypso.org/pub/GSM/FreeCalypso/fc-usbser-tools-latest.tar.bz2
 
-If you are making a CP2102-based serial cable yourself (either for your own
-personal use or professionally/commercially), please follow these instructions
-for baud rate programming:
+Because Sysmocom CP2102-25 adapters have been repurposed for various other uses
+"in the Osmocom universe" (literal quote from the vendor's product description
+page) beyond the original purpose of connecting to Mot C1xx and Openmoko
+GTA01/02 phones, the shipping state of the adapter's internal EEPROM cannot be
+depended on: they may ship with the EEPROM programmed for 203125/406250/812500
+baud or for 230400/460800/921600 baud depending on which year you bought the
+product and other unknown factors.  Fortunately though, our cp2102-read-baudtab
+utility (included in fc-usbser-tools package linked above) replaces guesswork
+with clarity: you run this command, and it shows you the current programming of
+the baud rate table in the EEPROM.  Programming this EEPROM to the desired
+configuration is then as simple as:
 
-http://osmocom.org/projects/baseband/wiki/HardwareCP210xTutorial
+cp2102-update-eeprom -b gsm	# program EEPROM for high GSM baud rates
 
-If you follow the procedure given on that page, your CP2102 will be programmed
-the same way as the one in the Pirelli DP-L10 (Foxconn's original factory
-programming).
+or
+
+cp2102-update-eeprom -b std	# program EEPROM for "standard" baud rates
 
 Using adapters built into phones
 ================================