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

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

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.

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

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

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.