FreeCalypso > hg > freecalypso-tools

comparison doc/High-speed-serial @ 258:00805e7c4c45

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/High-speed-serial: update/rewrite for the new FTDI support
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 28 Sep 2017 07:53:50 +0000
parents e7502631a0f9
children 9edb7c07bb29
comparison
equal deleted inserted replaced
257:62724d4928c2 258:00805e7c4c45
1 The highest baud rate supported by "standard" PC serial ports is 115200 bps, 1 The highest baud rate supported by "standard" PC serial ports is 115200 bps,
2 but Calypso UARTs can go quite a bit faster. Being clocked with 13 MHz (a 2 but Calypso UARTs can go quite a bit faster. Being clocked with 13 MHz (a
3 standard frequency in the GSM world), these UARTs can produce non-standard 3 standard frequency in the GSM world), these UARTs can produce non-standard
4 (outside of the GSM world) baud rates of 203125, 406250 and 812500 bps. When 4 (outside of the GSM world) baud rates of 203125, 406250 and 812500 bps. Even
5 working with Motorola C1xx and Openmoko GTA01/02 phones which present a debug 5 though these high baud rates aren't supported by "standard" RS-232 serial ports
6 and programming serial interface on a 2.5 mm headset jack, one can make use of 6 on PCs, they *are* supported by some of the better USB to serial adapters,
7 these high serial baud rates by using a USB to headset jack programming cable 7 namely CP2102 (USB to single UART) and the FT2232x family (USB to two UARTs).
8 based on one of the better USB-serial chips that can support these GSM special 8 The Pirelli DP-L10 phone supported by FreeCalypso host tools has a CP2102 built
9 baud rates well above 115200. The two USB-serial chips that are known to work 9 in, the officially recommended 2.5 mm headset jack USB-serial cables for working
10 in this manner are CP2102 and FTDI, although each of the two requires its own 10 with Motorola C1xx and Openmoko GTA01/02 phones also use CP2102 adapters,
11 special quirks described below. Other USB to serial cables use chips which 11 whereas our FreeCalypso development boards (FCDEV3B) are typically used with an
12 don't support the high baud rates in question, and therefore are limited to 12 FT2232D or other FT2232x USB to dual UART adapter.
13 115200 baud max like a "standard" PC serial port.
14 13
15 FreeCalypso tools can use these high serial baud rates in the following ways: 14 FreeCalypso tools can use these high serial baud rates in the following ways:
16 15
17 * When you use fc-loadtool to dump and program GSM device flash memory 16 * When you use fc-loadtool to dump and program GSM device flash memory
18 (flashing firmware images), the transfers get annoyingly slow at 115200 baud 17 (flashing firmware images), the transfers get annoyingly slow at 115200 baud
21 20
22 * Some of our target devices have large enough RAM to execute a GSM firmware 21 * Some of our target devices have large enough RAM to execute a GSM firmware
23 image entirely from RAM without flashing - very handy for development and 22 image entirely from RAM without flashing - very handy for development and
24 experimentation. The tool used to run these RAM-based images is fc-xram, 23 experimentation. The tool used to run these RAM-based images is fc-xram,
25 and it also supports the option of using high serial baud rates for the image 24 and it also supports the option of using high serial baud rates for the image
26 transfer for the same reason: repeatedly transferring 1.5 MiB images over 25 transfer for the same reason: repeatedly transferring >2 MiB images over
27 115200 baud gets tiresome. 26 115200 baud gets tiresome.
28 27
29 * If you are building your own GSM firmware (either FC GSM fw or one of our 28 * If you are building your own FreeCalypso-based or TI-based GSM firmware in a
30 TCS211-based hacks), you can make it run its RVTMUX interface at 406250 or 29 special non-standard configuration, you can make it run its RVTMUX interface
31 812500 baud. We used this trick when we tried to make TCS211 with D-Sample- 30 at 406250 or 812500 baud. We used this trick when we tried to make TCS211
32 targeting UI (176x220 pix LCD, 16 bits per pixel) send its virtual LCD raster 31 with D-Sample-targeting UI (176x220 pix LCD, 16 bits per pixel) send its
33 blits out the serial port. Our rvtdump and rvinterf utilities support this 32 virtual LCD raster blits out the serial port. Our rvtdump and rvinterf
34 mode of operation by providing options to select different baud rates. 33 utilities support this mode of operation by providing options to select
34 different baud rates.
35 35
36 Using CP2102 adapters 36 Recent changes for better FTDI adapter support
37 ===================== 37 ==============================================
38 38
39 CP2102 chips have a built-in EEPROM that contains (among other things) a 39 There is one fundamental difference between the way CP2102 adapters support
40 32-entry table in which the supported serial baud rates are programmed. In 40 non-standard baud rates (like the high GSM baud rates of interest to us) and
41 order to support the special GSM baud rates, these rates need to be added to 41 the way in which FTDI adapters support them. CP2102 chips have a built-in
42 that table, displacing some other entries. The convention established by the 42 EEPROM that contains (among other things) a 32-entry table in which the
43 Pirelli DP-L10 phone (has a CP2102 built in and programmed at the factory for 43 supported serial baud rates are programmed, and the programming of this EEPROM
44 GSM baud rates) is that 203120 baud takes the place of 230400, 406250 takes the 44 effects a remapping: a Linux userspace process can request B230400, B460800 or
45 place of 460800, and 812500 takes the place of 921600. 45 B921600 from termios, but magically get 203125, 406250 or 812500 as the actual
46 resulting serial baud rate instead. In contrast, FTDI adapters have no such
47 magic remapping mechanism in hardware, thus in order to get 203125, 406250 or
48 812500 baud with an FTDI adapter, the userspace process has to explicitly
49 request these special baud rates from the serial driver in the kernel, and
50 doing the latter requires foregoing the standard termios API and using Linux-
51 specific <asm/...> header files and raw ioctl calls instead.
52
53 When support for high GSM baud rates was first added to FreeCalypso host tools
54 back in 2013, there was no need to support the more difficult FTDI adapters as
55 the easier to work with CP2102 was fully sufficient for our needs, hence our
56 original FC host tools implementation required "magic" baud rate remapping
57 somewhere below, usually in form of CP2102 EEPROM programming but also possibly
58 by way of a hacky patch to the ftdi_sio driver in the Linux kernel to achieve
59 the same effect with rarely-needed FTDI adapters.
60
61 The situation has changed with the introduction of our own FreeCalypso
62 development boards (currently FCDEV3B, possibly others in the future) which
63 bring out both Calypso UARTs to the user, rather than just one. The most
64 convenient serial adapters for working with these dual UARTs are FT2232x (our
65 current official adapter is FT2232D), thus we now have a strong need to support
66 the use of these FTDI adapters, including the use of high GSM baud rates, in a
67 manner which does not fight against the mainline Linux kernel.
68
69 In a radical change from fc-host-tools-r6 and earlier, the present version of
70 FreeCalypso host tools uses new libserial code that differs from the old code
71 as follows:
72
73 * Linux-specific <asm/...> headers are used instead of <termios.h>;
74
75 * Linux-specific raw ioctl calls are used instead of tcsetattr() for serial
76 port setup;
77
78 * When the user requests 203125, 406250 or 812500 baud, these are the actual
79 baud rates requested from the kernel, not 230400/460800/921600 baud.
80
81 This change is expected to have no adverse effect on the existing CP2102 users,
82 as the cp210x driver in Linux appears to cope fine with the strange baud rate
83 requests from userspace and the correct CP2102 EEPROM baud rate entry still
84 gets selected (tested on Slackware 13.37 and Debian 9), but when working with
85 FTDI adapters such as our FT2232D adapter for the FCDEV3B this change makes the
86 high GSM baud rates work without needing the dirty kernel patch which the
87 Mother has been using up until now.
88
89 Support for other Unix flavors
90 ==============================
91
92 The serial port handling code for all of FC host tools has been factored out
93 into a common library called libserial. We have two versions of libserial:
94
95 * libserial-orig uses the standard and presumably portable termios API, but
96 requires "magic" remapping of baud rates by some invisible genie below (like
97 CP2102 EEPROM programming) in order to get 203125/406250/812500 baud.
98
99 * libserial-newlnx uses Linux-specific header files and raw ioctl calls to
100 request the actual desired baud rates.
101
102 If you would like to run FreeCalypso host tools under FreeBSD, illumos or some
103 other alternative-to-Linux OS, you have two basic choices:
104
105 * If you wish to use high GSM baud rates with non-remapping FTDI adapters or
106 other serial interfaces which support the baud rates in question without
107 remapping, you will need to figure out how to request non-standard serial
108 baud rates from the underlying drivers under your OS, and create your own
109 version of libserial ported to use that method.
110
111 * If you don't need high GSM baud rates or need them only with CP2102 adapters
112 which "magically" remap them, you should be able to use libserial-orig. You
113 can also completely remove the entries for the high GSM baud rates from
114 libserial-orig/baudtab.c if you don't need these high baud rates and your
115 version of termios does not have B230400/B460800/B921600 baud rate constants.
116
117 It is assumed that any system on which someone may desire to run our FC host
118 tools supports at least 115200 baud. The Mother remembers the days when this
119 baud rate was considered very high and non-standard and even has some of those
120 lovely old systems still running; fc-loadtool and friends going through the
121 Calypso boot ROM (not through Compal's bootloader) can be made to work with a
122 host system whose UARTs max out at 19200 baud, but most Calypso GSM device
123 firmwares including our own use the 115200 baud rate.
124
125 Using CP2102 adapters with Mot C1xx and Openmoko phones
126 =======================================================
127
128 As already mentioned above, CP2102 chips have a built-in EEPROM that contains
129 (among other things) a 32-entry table in which the supported serial baud rates
130 are programmed. In order to support the special GSM baud rates, these rates
131 need to be added to that table, displacing some other entries. The convention
132 established by the Pirelli DP-L10 phone (has a CP2102 built in and programmed
133 at the factory for GSM baud rates) is that 203120 baud takes the place of
134 230400, 406250 takes the place of 460800, and 812500 takes the place of 921600.
46 135
47 Because you need a special cable anyway to make the necessary physical 136 Because you need a special cable anyway to make the necessary physical
48 connection to the debug/programming serial port presented on a 2.5 mm headset 137 connection to the debug/programming serial port presented on a 2.5 mm headset
49 jack, you will probably be buying the requisite cable from a specialized 138 jack, you will probably be buying the requisite cable from a specialized
50 professional vendor. In that case it is that vendor's responsibility to sell 139 professional vendor. In that case it is that vendor's responsibility to sell
53 serial end) makes it specific to GSM devices, and all known GSM devices use a 142 serial end) makes it specific to GSM devices, and all known GSM devices use a
54 13 MHz clock or some integer multiple thereof, it is pointless for a 143 13 MHz clock or some integer multiple thereof, it is pointless for a
55 physically-GSM-specific cable to be set up for 230400/460800/921600 baud when 144 physically-GSM-specific cable to be set up for 230400/460800/921600 baud when
56 all known GSM devices will need 203125/406250/812500 baud instead. 145 all known GSM devices will need 203125/406250/812500 baud instead.
57 146
58 If you making a CP2102-based serial cable yourself (either for your own personal 147 If you are making a CP2102-based serial cable yourself (either for your own
59 use or professionally/commercially), please follow these instructions for baud 148 personal use or professionally/commercially), please follow these instructions
60 rate programming: 149 for baud rate programming:
61 150
62 http://bb.osmocom.org/trac/wiki/Hardware/CP210xTutorial 151 http://osmocom.org/projects/baseband/wiki/HardwareCP210xTutorial
63 152
64 If you follow the procedure given on that page, your CP2102 will be programmed 153 If you follow the procedure given on that page, your CP2102 will be programmed
65 the same way as the one in the Pirelli DP-L10 (Foxconn's original factory 154 the same way as the one in the Pirelli DP-L10 (Foxconn's original factory
66 programming). 155 programming).
67
68 The serial port handling code in FreeCalypso host tools is written to request
69 B230400 from termios when 203125 baud is desired, likewise B460800 for 406250
70 baud and B921600 for 812500 baud. Therefore, if you have a CP2102-based cable
71 with properly programmed EEPROM, everything will Just Work.
72
73 Using FTDI adapters
74 ===================
75
76 Unlike CP2102, FTDI adapters don't require any non-volatile EEPROM programming
77 for GSM baud rates, but they have a different pain point - arguably a worse one
78 - that is entirely a software issue. The API which the Linux kernel provides
79 to userspace applications for opening and configuring serial ports provides no
80 clean, sensible way for an application to request a particular baud rate that
81 is not in the predefined-once-and-for-all list, and to make it unambiguous to
82 the in-kernel driver exactly what it wants.
83
84 The method provided by the ftdi_sio driver in the standard Linux kernel is
85 gross, and I (Space Falcon) refuse to use it. The serial port handling code in
86 FreeCalypso host tools is written for the clean CP2102 way, and is *not* muddied
87 with the muck that would be necessary to get the high GSM baud rates with an
88 unpatched ftdi_sio driver. Therefore, if you would like to use one of the high
89 GSM baud rates with FreeCalypso with an FTDI adapter, you will need to dirty
90 your Linux host system with a hacky kernel patch. The patch provided in
91 linux-2.6.37.6-ftdi_sio.c.patch (made against Linux 2.6.37.6, which is what I
92 use - came with Slackware 13.37 - adapt as necessary for your kernel version)
93 makes the ftdi_sio driver behave like a GSM-programmed CP2102: termios B230400
94 turns into 203125 baud, B460800 turns into 406250 and B921600 turns into 812500.
95
96 This patch won't break other software (*cough* osmocom-bb *cough*) that does
97 use the "standard" ftdi_sio way of requesting high GSM baud rates, i.e., both
98 ways of selecting these baud rates should still work, but if you have other
99 (non-GSM) serial devices on the same system which need 230400, 460800 or 921600
100 baud, those will break.
101 156
102 Using adapters built into phones 157 Using adapters built into phones
103 ================================ 158 ================================
104 159
105 The Calypso chip has no native USB capabilities, thus if a Calypso phone 160 The Calypso chip has no native USB capabilities, thus if a Calypso phone