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.  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).
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:

* When you use fc-loadtool to dump and program GSM device flash memory
  (flashing firmware images), the transfers get annoyingly slow at 115200 baud
  if you have to do it a lot.  Switching to 406250 or even better 812500 baud
  makes them go considerably faster.

* Some of our target devices have large enough RAM to execute a GSM firmware
  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 >2 MiB images over
  115200 baud gets tiresome.

* 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.

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
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 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
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.

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, 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
==============================

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-posix 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-linux 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:

* 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-posix.  You
  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.

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
=======================================================

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
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 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

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:

cp2102-update-eeprom -b gsm	# program EEPROM for high GSM baud rates

or

cp2102-update-eeprom -b std	# program EEPROM for "standard" baud rates

Using adapters built into phones
================================

The Calypso chip has no native USB capabilities, thus if a Calypso phone
presents a USB charging+data port to the user, it must have a USB to serial
converter built in.  The only phone we currently know of that does this is
Pirelli DP-L10, and its built-in USB-serial adapter chip is CP2102.  It has
already been programmed with the correct GSM baud rates on Foxconn's original
production line, thus one can always use 812500 baud with FreeCalypso tools on
this phone and it will Just Work.