freecalypso-tools: doc/High-speed-serial annotate

annotate doc/High-speed-serial @ 1011:6d9b10633f10

etmsync Pirelli IMEI retrieval: fix poor use of printf() Bug reported by Vadim Yanitskiy <fixeria@osmocom.org>: the construct where a static-allocated string was passed to printf() without any format arguments causes newer compilers to report a security problem. Given that formatted output is not needed here, just fixed string output, change printf() to fputs(), and direct the error message to stderr while at it.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Thu, 23 May 2024 17:29:57 +0000
parents	2b4c3e0f73fc
children

rev	line source
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 The highest baud rate supported by "standard" PC serial ports is 115200 bps,
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 but Calypso UARTs can go quite a bit faster. Being clocked with 13 MHz (a
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3 standard frequency in the GSM world), these UARTs can produce non-standard
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	4 (outside of the GSM world) baud rates of 203125, 406250 and 812500 bps. Even
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	5 though these high baud rates aren't supported by "standard" RS-232 serial ports
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	6 on PCs, they are supported by some of the better USB to serial adapters,
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	7 namely CP2102 (USB to single UART) and the FT2232x family (USB to two UARTs).
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	8 Both FTDI and CP2102 USB-serial adapters are officially endorsed in FreeCalypso
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	9 queendom:
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	10
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	11 * FreeCalypso DUART28 adapter (USB to dual UART at 2.8V, electrically optimized
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	12 for direct connection to Calypso UARTs) is based on FT2232D;
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	13
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	14 * For working with older Calypso devboards such as TI D-Sample and iWOW DSK
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	15 (two RS-232 UARTs), FTDI board USB-COM232-PLUS2 (based on FT2232H) is
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	16 officially recommended;
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	17
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	18 * Future FreeCalypso development boards will likely include a built-in FT2232H
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	19 subsystem;
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	20
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	21 * For working with Motorola C1xx and Openmoko GTA01/02 phones (Calypso UART
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	22 access via 2.5 mm headset jack), the cable we officially recommend is based
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	23 on CP2102;
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	24
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	25 * Pirelli DP-L10 is a Calypso phone with a built-in CP2102 USB-serial interface,
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	26 supported since the beginning of FreeCalypso project.
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28 FreeCalypso tools can use these high serial baud rates in the following ways:
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 * When you use fc-loadtool to dump and program GSM device flash memory
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 (flashing firmware images), the transfers get annoyingly slow at 115200 baud
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32 if you have to do it a lot. Switching to 406250 or even better 812500 baud
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33 makes them go considerably faster.
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35 * Some of our target devices have large enough RAM to execute a GSM firmware
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 image entirely from RAM without flashing - very handy for development and
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37 experimentation. The tool used to run these RAM-based images is fc-xram,
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38 and it also supports the option of using high serial baud rates for the image
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	39 transfer for the same reason: repeatedly transferring >2 MiB images over
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40 115200 baud gets tiresome.
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	42 * If you are building your own FreeCalypso-based or TI-based GSM firmware in a
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	43 special non-standard configuration, you can make it run its RVTMUX interface
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	44 at 406250 or 812500 baud. We used this trick when we tried to make TCS211
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	45 with D-Sample-targeting UI (176x220 pix LCD, 16 bits per pixel) send its
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	46 virtual LCD raster blits out the serial port. Our rvtdump and rvinterf
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	47 utilities support this mode of operation by providing options to select
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	48 different baud rates.
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	49
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	50 FreeCalypso host tools approach to FTDI adapter support
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	51 =======================================================
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	52
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	53 There is one fundamental difference between the way CP2102 adapters support
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	54 non-standard baud rates (like the high GSM baud rates of interest to us) and
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	55 the way in which FTDI adapters support them. CP2102 chips have a built-in
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	56 EEPROM that contains (among other things) a 32-entry table in which the
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	57 supported serial baud rates are programmed, and the programming of this EEPROM
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	58 effects a remapping: a Linux userspace process can request B230400, B460800 or
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	59 B921600 from termios, but magically get 203125, 406250 or 812500 as the actual
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	60 resulting serial baud rate instead. In contrast, FTDI adapters have no such
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	61 magic remapping mechanism in hardware, thus in order to get 203125, 406250 or
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	62 812500 baud with an FTDI adapter, the userspace process has to explicitly
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	63 request these special baud rates from the serial driver in the kernel, and
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	64 doing the latter requires foregoing the standard termios API and using Linux-
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	65 specific <asm/...> header files and raw ioctl calls instead.
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	66
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	67 When support for high GSM baud rates was first added to FreeCalypso host tools
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	68 back in 2013, there was no need to support the more difficult FTDI adapters as
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	69 the easier to work with CP2102 was fully sufficient for our needs, hence our
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	70 original FC host tools implementation required "magic" baud rate remapping
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	71 somewhere below, usually in form of CP2102 EEPROM programming but also possibly
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	72 by way of a hacky patch to the ftdi_sio driver in the Linux kernel to achieve
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	73 the same effect with rarely-needed FTDI adapters.
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	74
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	75 The situation has changed as our project transitioned from hacking on Motorola,
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	76 Openmoko and Pirelli phones to proper Calypso GSM MS development boards,
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	77 bringing out both Calypso UARTs rather than just one. The most convenient
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	78 serial adapters for working with these dual UARTs are FT2232x, thus we now have
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	79 a strong need to support the use of these FTDI adapters, including the use of
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	80 high GSM baud rates, in a manner which does not fight against the mainline
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	81 Linux kernel.
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	82
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	83 In a radical change from fc-host-tools-r6 and earlier, the present version of
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	84 FreeCalypso host tools uses new libserial code that differs from the old code
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	85 as follows:
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	86
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	87 * Linux-specific <asm/...> headers are used instead of <termios.h>;
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	88
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	89 * Linux-specific raw ioctl calls are used instead of tcsetattr() for serial
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	90 port setup;
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	91
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	92 * When the user requests 203125, 406250 or 812500 baud, these are the actual
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	93 baud rates requested from the kernel, not 230400/460800/921600 baud.
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	94
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	95 This change is expected to have no adverse effect on existing CP2102 users,
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	96 as the cp210x driver in Linux appears to cope fine with the strange baud rate
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	97 requests from userspace and the correct CP2102 EEPROM baud rate entry still
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	98 gets selected (tested on Slackware 13.37, Slackware 14.2 and Debian 9), but
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	99 when working with FTDI adapters, this change makes our high GSM baud rates work
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	100 without needing the dirty kernel patch which we used in the early part of 2017.
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	101
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	102 Support for other Unix flavors
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	103 ==============================
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	104
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	105 The serial port handling code for all of FC host tools has been factored out
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	106 into a common library called libserial. We have two versions of libserial:
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	107
694 9edb7c07bb29 doc/High-speed-serial updated for libserial rename Mychaela Falconia <falcon@freecalypso.org> parents: 258 diff changeset	108 * libserial-posix uses the standard and presumably portable termios API, but
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	109 requires "magic" remapping of baud rates by some invisible genie below (like
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	110 CP2102 EEPROM programming) in order to get 203125/406250/812500 baud.
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	111
694 9edb7c07bb29 doc/High-speed-serial updated for libserial rename Mychaela Falconia <falcon@freecalypso.org> parents: 258 diff changeset	112 * libserial-linux uses Linux-specific header files and raw ioctl calls to
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	113 request the actual desired baud rates.
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	114
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	115 If you would like to run FreeCalypso host tools under FreeBSD, illumos or some
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	116 other alternative-to-Linux OS, you have two basic choices:
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	117
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	118 * If you wish to use high GSM baud rates with non-remapping FTDI adapters or
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	119 other serial interfaces which support the baud rates in question without
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	120 remapping, you will need to figure out how to request non-standard serial
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	121 baud rates from the underlying drivers under your OS, and create your own
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	122 version of libserial ported to use that method.
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	123
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	124 * If you don't need high GSM baud rates or need them only with CP2102 adapters
694 9edb7c07bb29 doc/High-speed-serial updated for libserial rename Mychaela Falconia <falcon@freecalypso.org> parents: 258 diff changeset	125 which "magically" remap them, you should be able to use libserial-posix. You
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	126 can also completely remove the entries for high GSM baud rates from
694 9edb7c07bb29 doc/High-speed-serial updated for libserial rename Mychaela Falconia <falcon@freecalypso.org> parents: 258 diff changeset	127 libserial-posix/baudtab.c if you don't need these high baud rates and your
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	128 version of termios does not have B230400/B460800/B921600 baud rate constants.
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	129
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	130 It is assumed that any system on which someone may desire to run our FC host
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	131 tools supports at least 115200 baud. The Mother remembers the days when this
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	132 baud rate was considered very high and non-standard and even has some of those
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	133 lovely old systems still running; fc-loadtool and friends going through the
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	134 Calypso boot ROM (not through Compal's bootloader) can be made to work with a
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	135 host system whose UARTs max out at 19200 baud, but most Calypso GSM device
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	136 firmwares including our own use the 115200 baud rate.
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	137
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	138 Using CP2102 adapters with Mot C1xx and Openmoko phones
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	139 =======================================================
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	140
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	141 For the special USB-serial cable that connects to the 2.5 mm headset jack on
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	142 these phones, our current official recommendation is this one:
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	143
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	144 https://shop.sysmocom.de/Sysmocom-USB-serial-cable-CP2102-with-2.5mm-stereo-jack/cp2102-25
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	145
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	146 (In the past we also worked with a different vendor, UberWaves, but that vendor
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	147 appears to be no longer active as of 2023-12.)
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	148
258 00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	149 As already mentioned above, CP2102 chips have a built-in EEPROM that contains
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	150 (among other things) a 32-entry table in which the supported serial baud rates
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	151 are programmed. In order to support the special GSM baud rates, these rates
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	152 need to be added to that table, displacing some other entries. The convention
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	153 established by the Pirelli DP-L10 phone (has a CP2102 built in and programmed
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	154 at the factory for GSM baud rates) is that 203120 baud takes the place of
00805e7c4c45 doc/High-speed-serial: update/rewrite for the new FTDI support Mychaela Falconia <falcon@freecalypso.org> parents: 0 diff changeset	155 230400, 406250 takes the place of 460800, and 812500 takes the place of 921600.
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	156
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	157 If you are working with CP2102 adapters from any vendor, or headset jack serial
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	158 cables that incorporate such adapters, you should install this companion tools
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	159 package from FreeCalypso:
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	160
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	161 https://www.freecalypso.org/pub/GSM/FreeCalypso/fc-usbser-tools-latest.tar.bz2
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	162
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	163 Because Sysmocom CP2102-25 adapters have been repurposed for various other uses
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	164 "in the Osmocom universe" (literal quote from the vendor's product description
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	165 page) beyond the original purpose of connecting to Mot C1xx and Openmoko
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	166 GTA01/02 phones, the shipping state of the adapter's internal EEPROM cannot be
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	167 depended on: they may ship with the EEPROM programmed for 203125/406250/812500
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	168 baud or for 230400/460800/921600 baud depending on which year you bought the
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	169 product and other unknown factors. Fortunately though, our cp2102-read-baudtab
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	170 utility (included in fc-usbser-tools package linked above) replaces guesswork
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	171 with clarity: you run this command, and it shows you the current programming of
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	172 the baud rate table in the EEPROM. Programming this EEPROM to the desired
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	173 configuration is then as simple as:
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	174
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	175 cp2102-update-eeprom -b gsm # program EEPROM for high GSM baud rates
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	176
1008 2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	177 or
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	178
2b4c3e0f73fc doc/High-speed-serial: update for current situation Mychaela Falconia <falcon@freecalypso.org> parents: 694 diff changeset	179 cp2102-update-eeprom -b std # program EEPROM for "standard" baud rates
0 e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	180
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	181 Using adapters built into phones
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	182 ================================
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	183
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	184 The Calypso chip has no native USB capabilities, thus if a Calypso phone
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	185 presents a USB charging+data port to the user, it must have a USB to serial
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	186 converter built in. The only phone we currently know of that does this is
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	187 Pirelli DP-L10, and its built-in USB-serial adapter chip is CP2102. It has
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	188 already been programmed with the correct GSM baud rates on Foxconn's original
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	189 production line, thus one can always use 812500 baud with FreeCalypso tools on
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7 Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	190 this phone and it will Just Work.

FreeCalypso > hg > freecalypso-tools

annotate doc/High-speed-serial @ 1011:6d9b10633f10