--- a/doc/High-speed-serial	Fri Sep 22 22:36:13 2017 +0000
+++ b/doc/High-speed-serial	Thu Sep 28 07:53:50 2017 +0000
@@ -1,16 +1,15 @@
 The highest baud rate supported by "standard" PC serial ports is 115200 bps,
 but Calypso UARTs can go quite a bit faster.  Being clocked with 13 MHz (a
 standard frequency in the GSM world), these UARTs can produce non-standard
-(outside of the GSM world) baud rates of 203125, 406250 and 812500 bps.  When
-working with Motorola C1xx and Openmoko GTA01/02 phones which present a debug
-and programming serial interface on a 2.5 mm headset jack, one can make use of
-these high serial baud rates by using a USB to headset jack programming cable
-based on one of the better USB-serial chips that can support these GSM special
-baud rates well above 115200.  The two USB-serial chips that are known to work
-in this manner are CP2102 and FTDI, although each of the two requires its own
-special quirks described below.  Other USB to serial cables use chips which
-don't support the high baud rates in question, and therefore are limited to
-115200 baud max like a "standard" PC serial port.
+(outside of the GSM world) baud rates of 203125, 406250 and 812500 bps.  Even
+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.
 
 FreeCalypso tools can use these high serial baud rates in the following ways:
 
@@ -23,26 +22,116 @@
   image entirely from RAM without flashing - very handy for development and
   experimentation.  The tool used to run these RAM-based images is fc-xram,
   and it also supports the option of using high serial baud rates for the image
-  transfer for the same reason: repeatedly transferring 1.5 MiB images over
+  transfer for the same reason: repeatedly transferring >2 MiB images over
   115200 baud gets tiresome.
 
-* If you are building your own GSM firmware (either FC GSM fw or one of our
-  TCS211-based hacks), you can make it run its RVTMUX interface at 406250 or
-  812500 baud.  We used this trick when we tried to make TCS211 with D-Sample-
-  targeting UI (176x220 pix LCD, 16 bits per pixel) send its virtual LCD raster
-  blits out the serial port.  Our rvtdump and rvinterf utilities support this
-  mode of operation by providing options to select different baud rates.
+* If you are building your own FreeCalypso-based or TI-based GSM firmware in a
+  special non-standard configuration, you can make it run its RVTMUX interface
+  at 406250 or 812500 baud.  We used this trick when we tried to make TCS211
+  with D-Sample-targeting UI (176x220 pix LCD, 16 bits per pixel) send its
+  virtual LCD raster blits out the serial port.  Our rvtdump and rvinterf
+  utilities support this mode of operation by providing options to select
+  different baud rates.
+
+Recent changes for better 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
+the way in which FTDI adapters support them.  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, and the programming of this EEPROM
+effects a remapping: a Linux userspace process can request B230400, B460800 or
+B921600 from termios, but magically get 203125, 406250 or 812500 as the actual
+resulting serial baud rate instead.  In contrast, FTDI adapters have no such
+magic remapping mechanism in hardware, thus in order to get 203125, 406250 or
+812500 baud with an FTDI adapter, the userspace process has to explicitly
+request these special baud rates from the serial driver in the kernel, and
+doing the latter requires foregoing the standard termios API and using Linux-
+specific <asm/...> header files and raw ioctl calls instead.
+
+When support for high GSM baud rates was first added to FreeCalypso host tools
+back in 2013, there was no need to support the more difficult FTDI adapters as
+the easier to work with CP2102 was fully sufficient for our needs, hence our
+original FC host tools implementation required "magic" baud rate remapping
+somewhere below, usually in form of CP2102 EEPROM programming but also possibly
+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.
+
+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
+as follows:
+
+* Linux-specific <asm/...> headers are used instead of <termios.h>;
+
+* Linux-specific raw ioctl calls are used instead of tcsetattr() for serial
+  port setup;
+
+* When the user requests 203125, 406250 or 812500 baud, these are the actual
+  baud rates requested from the kernel, not 230400/460800/921600 baud.
 
-Using CP2102 adapters
-=====================
+This change is expected to have no adverse effect on the 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.
+
+Support for other Unix flavors
+==============================
+
+The serial port handling code for all of FC host tools has been factored out
+into a common library called libserial.  We have two versions of libserial:
+
+* libserial-orig uses the standard and presumably portable termios API, but
+  requires "magic" remapping of baud rates by some invisible genie below (like
+  CP2102 EEPROM programming) in order to get 203125/406250/812500 baud.
+
+* libserial-newlnx uses Linux-specific header files and raw ioctl calls to
+  request the actual desired baud rates.
+
+If you would like to run FreeCalypso host tools under FreeBSD, illumos or some
+other alternative-to-Linux OS, you have two basic choices:
 
-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 need to be added to
-that table, displacing some other entries.  The convention established by the
-Pirelli DP-L10 phone (has a CP2102 built in and programmed 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.
+* If you wish to use high GSM baud rates with non-remapping FTDI adapters or
+  other serial interfaces which support the baud rates in question without
+  remapping, you will need to figure out how to request non-standard serial
+  baud rates from the underlying drivers under your OS, and create your own
+  version of libserial ported to use that method.
+
+* 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-orig.  You
+  can also completely remove the entries for the high GSM baud rates from
+  libserial-orig/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.
+
+It is assumed that any system on which someone may desire to run our FC host
+tools supports at least 115200 baud.  The Mother remembers the days when this
+baud rate was considered very high and non-standard and even has some of those
+lovely old systems still running; fc-loadtool and friends going through the
+Calypso boot ROM (not through Compal's bootloader) can be made to work with a
+host system whose UARTs max out at 19200 baud, but most Calypso GSM device
+firmwares including our own use the 115200 baud rate.
+
+Using CP2102 adapters with Mot C1xx and Openmoko phones
+=======================================================
+
+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
+need to be added to that table, displacing some other entries.  The convention
+established by the Pirelli DP-L10 phone (has a CP2102 built in and programmed
+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
@@ -55,50 +144,16 @@
 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 making a CP2102-based serial cable yourself (either for your own personal
-use or professionally/commercially), please follow these instructions for baud
-rate programming:
+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:
 
-http://bb.osmocom.org/trac/wiki/Hardware/CP210xTutorial
+http://osmocom.org/projects/baseband/wiki/HardwareCP210xTutorial
 
 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).
 
-The serial port handling code in FreeCalypso host tools is written to request
-B230400 from termios when 203125 baud is desired, likewise B460800 for 406250
-baud and B921600 for 812500 baud.  Therefore, if you have a CP2102-based cable
-with properly programmed EEPROM, everything will Just Work.
-
-Using FTDI adapters
-===================
-
-Unlike CP2102, FTDI adapters don't require any non-volatile EEPROM programming
-for GSM baud rates, but they have a different pain point - arguably a worse one
-- that is entirely a software issue.  The API which the Linux kernel provides
-to userspace applications for opening and configuring serial ports provides no
-clean, sensible way for an application to request a particular baud rate that
-is not in the predefined-once-and-for-all list, and to make it unambiguous to
-the in-kernel driver exactly what it wants.
-
-The method provided by the ftdi_sio driver in the standard Linux kernel is
-gross, and I (Space Falcon) refuse to use it.  The serial port handling code in
-FreeCalypso host tools is written for the clean CP2102 way, and is *not* muddied
-with the muck that would be necessary to get the high GSM baud rates with an
-unpatched ftdi_sio driver.  Therefore, if you would like to use one of the high
-GSM baud rates with FreeCalypso with an FTDI adapter, you will need to dirty
-your Linux host system with a hacky kernel patch.  The patch provided in
-linux-2.6.37.6-ftdi_sio.c.patch (made against Linux 2.6.37.6, which is what I
-use - came with Slackware 13.37 - adapt as necessary for your kernel version)
-makes the ftdi_sio driver behave like a GSM-programmed CP2102: termios B230400
-turns into 203125 baud, B460800 turns into 406250 and B921600 turns into 812500.
-
-This patch won't break other software (*cough* osmocom-bb *cough*) that does
-use the "standard" ftdi_sio way of requesting high GSM baud rates, i.e., both
-ways of selecting these baud rates should still work, but if you have other
-(non-GSM) serial devices on the same system which need 230400, 460800 or 921600
-baud, those will break.
-
 Using adapters built into phones
 ================================