# HG changeset patch # User Mychaela Falconia # Date 1506585230 0 # Node ID 00805e7c4c4520e9b932568acbb0dd855da020ec # Parent 62724d4928c2028e8d66edfb38f601935af701da doc/High-speed-serial: update/rewrite for the new FTDI support diff -r 62724d4928c2 -r 00805e7c4c45 doc/High-speed-serial --- 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 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 headers are used instead of ; + +* 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 ================================