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.

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

Using CP2102 adapters
=====================

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

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

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.