[Historical note: this document was originally written in 2014 when the vision of FreeCalypso was very different from what it is today. Since then we have transitioned from making aftermarket hacks on pre-existing Calypso phones and modems to producing and supporting our own FreeCalypso hardware products, and our firmware work has changed from a nebulous dream to stable production code. The ways in which we approach various technical aspects have changed accordingly, but much of our documentation has been slow to catch up. The documentation is now being updated, but there may still be some passages where the old world view shines through.]TI's Calypso GSM/GPRS baseband processor chip has not one but two UART serialports, called "MODEM" and "IrDA" in the hardware documentation. In hardwareterms, both support basic data-leads-only UART operation at a fixed baud rate,but their extended capabilities differ: the IrDA UART adds IrDA capability (nosurprise), whereas the MODEM UART adds hardware flow control and autobaud. Ifone is not implementing an actual IrDA interface, then the so-called "IrDA"UART becomes a strict subset of the MODEM one in terms of hw capabilities -just an extra UART, but a somewhat less capable one.In a classic modem design such as that present in the GTA0x smartphones made byFIC/Openmoko, the Calypso presents a standard AT command interface on its MODEMUART port. (In the case of GTA0x phones this serial channel is wired to thephone's application processor; in a standalone modem it would be wired to aUSB-serial chip or even to a classic RS-232 DB25 port.) However, what is lessknown is that the standard firmware for such modems simultaneously presents anentirely different interface on the IrDA UART - an interface intended fordevelopment, debugging and factory production testing (which includes RFcalibration and IMEI etc programming), rather than for "normal" end users.Normally this debug/development serial interface (called RVTMUX as will beexplained momentarily) is hidden from "ordinary" users - for example, on FICGTA0x phones it is wired to the analog headset jack through a hardware switchwhich needs to be enabled through a GPIO signal from the AP. On Mot C139 andits siblings the situation is similar: one needs to key in the secret magicsequence **16379#, and then the firmware presents a hidden menu for switchingthe analog headset jack between its "normal" function and the UART carryingRVTMUX.But there also exist some oddball devices on which the RVTMUX interface ispresented "in your face". The Pirelli DP-L10 phone has a USB charging portwhich is also wired (through a CP2102 USB-serial chip) to the IrDA UART on theCalypso - that's right, IrDA, not MODEM - a design decision with which thishacker strongly disagrees. (It'll definitely be wired to the MODEM UARTinstead on our own semi-clone of this phone, but I digress.) Apparently Foxconn(the designers of this phone) had no desire to provide a standard AT commandinterface, and instead the only "official" way to use the "data" function oftheir USB port (rather than the charging function) is for their "PC sync"feature, i.e., their proprietary Weendoze software. And guess what, theirproprietary "PC sync" feature works over TI's RVTMUX interface, as that iswhat's presented on Calypso's IrDA UART behind the CP2102!OK, so what is this RVTMUX? RV stands for RiViera, an application frameworkwhich TI added to their GSM firmware suite in the early 2000s, T stands fortrace, and MUX stands for multiplexor. It's a binary packet interface, althoughmany of these packets contain ASCII debug messages inside. The framing formatis the same in both directions: each packet begins and ends with an STX (0x02)byte, all payload bytes except 0x02 and 0x10 are sent literally, and there is aDLE (0x10) byte prepended before any 0x02 or 0x10 in the payload. It's the samegeneral principle as asynchronous HDLC (RFC 1662): packets can contain anybinary data, and the framing provides packet boundaries - although TI's versionis a little less robust than async-HDLC when it comes to recovering after lostsynchronization.The firmware suite component responsible for actually sending and receivingthese packets over the assigned UART port (usually IrDA, but can be MODEM too,as on Compal phones for example) is called RVT (RiViera Trace), and itimplements a MUX function. There are several logical channels multiplexed overone physical serial port, and the first byte of every packet indicates whichlogical channel it belongs to. Any component within the GSM firmware suite cansend packets to RVT for transmission on this serial interface, and can alsoregister to receive packets beginning with a particular type ID byte.Debug trace output==================All GSM device firmwares that are based on TI's Calypso chipset reference fwcontinuously emit quite voluminous debug trace output on their RVTMUX serialport, whether it is hidden or exposed on a given device. Like all RVTMUXtraffic, this debug trace output takes the form of binary packets as explainedabove, but the content of these packets is mostly ASCII with some binary headerbytes prepended. FreeCalypso host utility rvtdump captures all serial outputfrom a GSM device's RVTMUX port, parses the packet structure and displays thisoutput in line-oriented pure ASCII with all binary parts decoded.Test Mode commands==================The other major use of the RVTMUX interface is sending so-called Test Modecommands from an external host to a running GSM device. Depending on thefirmware version, a GSM device can be commanded to do any of the followingthings through this mechanism:* Exercise RF test modes, e.g., transmit continuously at a set frequency and power level;* Read and write arbitrary memory locations in the Calypso ARM7 address space;* Read and write ABB chip registers;* Reboot or power off;* Access and manipulate the device's flash file system (FFS).In the segment of history of interest to us TI has produced two differenttarget firmware components that can receive, interpret and act upon Test Modecommand packets:* The original Test Mode component of Layer 1, called L1TM or TML1: this component handles all RF test modes (needed for RF calibration on device production lines), and originally it also implemented memory and ABB register read and write commands, and provided access to TMFFS1 (see below). In the original implementation this component registered itself as the handler for the "TM" RVTMUX channel (RVT packet type 0x14), so it would receive all TM packets sent to the device.* Enhanced Test Mode (ETM) is a later invention. It registers itself (instead of the old TM in L1) with RVT as the handler for the "TM" RVTMUX channel, and then provides a registration service of its own, such that various components in the fw suite can register to receive external command packets passing first through RVT, then through ETM, and can send responses passing through ETM, then through RVT back to the external host. If a given fw version contains both ETM and L1TM, then L1TM registers itself with ETM; an external host would send exactly the same binary command packets to exercise RF test modes, but inside the firmware they now pass through ETM on their way to L1TM.The ETM_CORE module contained within ETM itself provides some low-level debugcommands: by sending the right binary command packets to the GSM device via theRVTMUX serial channel, an external host can examine or modify any memorylocation and any hardware register, cause the device to reset, etc. Prior toETM some of these functions (but not all) could be exercised through older TM3commands, but in FreeCalypso we became familiar with the ETM versions of thesecommands long before the older ones because we got the ETM component in fullsource form, whereas the sole surviving copy of TCS211 that serves as our goldenreference came with L1TM in binary object form like the rest of L1, and we gotto source-reconstructing it only much later.Our TCS211 reference fw has both ETM and L1TM, thus it accepts both ETM and TM3command packets; the same holds for our current production firmwares that arebased on this TCS211 reference. ETM commands (including TMFFS2, see below) alsowork on Pirelli's fw, but Mot/Compal's original fw for the C139 has only theoriginal non-enhanced Test Mode, not ETM.FFS access via TM/ETM=====================One of the essential facilities provided in one form or another in all knownincarnations of the Test Mode mechanism is the ability to access and manipulatethe GSM device's flash file system (FFS). See TIFFS-Overview for a descriptionof this file system. TI's TMFFS1 and TMFFS2 protocols provide a command andresponse packet interface to the FFS API functions inside the fw, and enable anexternal host connected to the GSM device via the RVTMUX channel to performarbitrary read and write operations on the device file system.In the segment of history of interest to us TI has produced two differentand entirely incompatible versions of the TMFFS protocol: TMFFS1 and TMFFS2.Or rather, what is now called TMFFS1 was originally just TMFFS, and then cameTMFFS2. TMFFS2 works only through ETM, whereas TMFFS1 predates ETM: in theoriginal implementation the tm_ffs() function in the FFS code was called fromL1TM code.Our copy of TCS211 reference fw includes the source for both TMFFS1 and TMFFS2;it is theoretically possible to build a firmware image that includes both TMFFSversions (they won't conflict because they respond to different commandpackets), but it is pretty clear that TI never intended to have both enabledat the same time. Our copy of TCS211 came with TMFFS1 enabled and we didn'tchange it when we made the moko12 (leo2moko-r1) fw release for the Openmokocommunity (the previous proprietary mokoN firmwares also implement TMFFS1),but we have subsequently switched to TMFFS2 for our current TCS211-based work.Our current production firmwares implement TMFFS2.Pirelli's fw implements TMFFS2: we don't have any source for this fw, but ourFreeCalypso host utilities written to talk the TMFFS2 protocol based on ouravailable TCS211 source work beautifully when run against Pirelli's fw.Use in FreeCalypso==================Our current production firmwares for FreeCalypso modems faithfully follow thearchitecture of TI's TCS211 without any fundamental changes. Thus thefunctionality which we present via RVTMUX is exactly the same as TI's original:our firmwares emit the same 3 kinds of debug traces (RV, L1 and GPF) as variouspre-existing ones, and for Test Mode functionality we have ETM, L1TM and TMFFS2.We have adopted ETM and TMFFS2 as the standard combination for FreeCalypso,i.e., ETM_CORE for memory and ABB register reads and writes and TMFFS2 forexternal FFS access. We needed to develop our own host tools for operating onGSM device FFS via one of the two TMFFS protocols, and after studying the fwsource implementing both, I (Space Falcon) came to the conclusion that TMFFS2is both more capable and more reliable; my guess is that TMFFS1 was likely keptaround only because some of TI's crappy Weendoze host software depended on it.(See chipsetsw/drivers/drv_app/ffs/board/tmffs.c in leo2moko or tcs211-fcmodemif you would like to judge for yourself.)We have the following host tools for communicating with TI-based GSM firmwares(both our own and some of the existing proprietary ones):rvtdump This tool produces a human-readable dump of all output emitted by a TI-based GSM fw in the form of RVTMUX binary packets. It can also log this dump to a file.rvinterf This tool is a superset of rvtdump: it not only dumps and/or logs all output from the GSM fw, but also provides a mechanism for sending command packets to it.Rvinterf is the engine behind the following host tools that send Test Modecommands to a target:fc-tmsh This is our basic tool for sending Test Mode commands to a running GSM fw. It is strictly asynchronous in that commands entered by the operator get sent to the target, and any response packets received from the target are displayed as they come in. The tool has no knowledge of any correspondence between commands being sent and whatever responses they should elicit, i.e., it is perfectly suited for experimental discovery of firmware behaviour in response to Test Mode commands. This tool was written before we realized that there was/is an older, more basic Test Mode predating ETM, hence in many place we say "ETM" when we really should have said "TM". Oh well...fc-fsio This tool speaks the TMFFS2 protocol and allows a user or developer to perform a wide range of operations on the file system of a GSM device. It operates synchronously, i.e., it sends ETM/TMFFS2 commands and expects responses in strict lock-step; a single user command may translate into a large number of ETM/TMFFS2 command packet exchanges.fc-shell This tool is asynchronous like fc-tmsh, but instead of talking and listening on the TM/ETM RVTMUX channel, it talks and listens on GPF's channel and on the new AT-over-RVTMUX channel which we added in FreeCalypso. fc-shell can be used to issue system primitive commands to GPF (and to see firmware responses to them), and to talk AT commands via RVTMUX.AT commands over RVTMUX=======================There is one more use to which we put the RVTMUX debug serial interface that isan original FreeCalypso invention: communicating with the AT command interpreter(ATI). TI's original architecture assumes that if a product is to offer astandard AT command interface (the product is either a GSM/GPRS modem for whichthis AT command interface is the sole mode of usage or a feature phone thatoffers a data port as one of its features), then it will be presented on adedicated UART separate from RVTMUX.However, in the case of our FreeCalypso family of projects about 2 years hadpassed between our first functional GSM fw attempts in 2015 and us successfullybuilding our own development board in 2017; during this time we had to work onvarious crippled pre-existing Calypso devices, and many of them had only oneUART practically accessible. In response to this situation we developed a wayto pass AT commands over RVTMUX. We created a new RVTMUX channel for thisinterface and assigned it RVT packet type 0x1A. Packets sent from an externalhost to the GSM device carry AT commands and SMS string input, whereas packetsflowing the other way carry ATI's responses to commands and asynchronousnotifications such as incoming calls. The host utility for talking AT commandsto a FreeCalypso GSM device via RVTMUX is fc-shell, described above.Now that we have built a proper FreeCalypso development board with two UARTs,the use of this AT-over-RVTMUX hack is deprecated for general usage: this hackdoes not support any data services (CSD or GPRS), and even for SMS it iscrippled because maximum-length messages cannot be sent in the more capable PDUmode. However, it still comes in handy during certain casual testing sessions,and it is required if one needs to run our FreeCalypso firmware on Mot C1xx orPirelli DP-L10 hardware.Keepalive mechanism===================Another FreeCalypso addition to TI's RVTMUX interface is our keepalive mechanismfor the voice pseudo-modem hack on Mot C1xx targets. The FreeCalypso familyincludes many subprojects, and one of these subprojects involves running modem-like firmware (control via AT commands only, no local UI) on Mot C1xx phones.Having a device that was originally made to be a phone with LCD and buttonsturn into a serially-controlled pseudo-modem (LCD stays dark, buttons donothing) feels quite weird, and this situation is exacerbated by the flashingrequirement: the only way to run our pseudo-modem fw on Mot C1xx phones is toflash it, there is no way to run it out of RAM without disturbing the phone'soriginal fw.When our Magnetite and Selenite firmwares are built for a C1xx target in theVPM configuration, they implement the following keepalive logic: if the phoneis powered on and running our fw, but the charging power source is not pluggedin, the fw sends periodic keepalive queries out the serial port to see if thereis a running rvinterf process on the other end of the wire, and automaticallypowers off if there is no keepalive response.Code has been added to rvinterf to respond with a keepalive answer packet whena keepalive query packet is received; the feature has been implemented on thervinterf side first, and then subsequently in our Magnetite fw for C1xx targets.