+
−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-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:
+
−
+
−* 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
+
−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.