# HG changeset patch # User Mychaela Falconia # Date 1495284518 0 # Node ID 7e3e3a958e3f507cd52191ca575166162647182b # Parent 1a658ab756fe645607bbf6b2a6ba4ebaa1818750 doc/Host-tools-overview: updated and simplified diff -r 1a658ab756fe -r 7e3e3a958e3f doc/Host-tools-overview --- a/doc/Host-tools-overview Fri May 19 06:57:19 2017 +0000 +++ b/doc/Host-tools-overview Sat May 20 12:48:38 2017 +0000 @@ -1,5 +1,6 @@ -FreeCalypso host tools suite features the following tools that are potentially -useful to end users: +FreeCalypso host tools suite includes a large number of different tools, many +of which are quite specialized and rarely needed. The following tools are the +most essential ones: fc-loadtool This is the tool used to read and write the non-volatile flash memory of supported GSM devices. It can be used to reflash @@ -8,13 +9,32 @@ flash backups. This tool operates on the target device (phone or modem) while its regular firmware is shut down. -fc-fsio This tool connects to GSM devices running one of the supported - firmware versions while the fw is running (unlike fc-loadtool - which operates on a device while its regular fw is shut down) - and allows you to manipulate (read and write) the device's - flash file system. It is thus a higher-level tool than - fc-loadtool. It is intended primarily for working with our own - firmwares, but it also works with Pirelli's original fw. +fc-iram, Reprogramming the non-volatile flash memory is not the only way +fc-xram, to run your own code on a Calypso GSM device. If your code is +fc-compalram small enough to fit entirely into the available RAM on the + device, and you would like to just run it without flashing it + permanently, these tools do the job of loading code images into + different kinds of RAM through different download protocols. + Some phones have large enough RAM to allow a complete functional + firmware image to be run via fc-xram without flashing. + +rvinterf This program is our engine for communicating with up & running + TI-based firmwares through the RVTMUX binary packet interface. + It receives and decodes all debug trace and other packets + emitted by the target fw, and allows the options of printing + them on the terminal, saving them to a log file, and/or passing + them to other programs that connect to rvinterf as local socket + clients. In the other direction those latter client programs + can send arbitrary command packets to the target fw. + +fc-fsio Going through rvinterf, this tool connects to GSM devices + running one of the supported firmware versions while the fw is + running (unlike fc-loadtool which operates on a device while + its regular fw is shut down) and allows you to manipulate + (read and write) the device's flash file system. It is thus a + higher-level tool than fc-loadtool. It is intended primarily + for working with our own firmwares, but it also works with + Pirelli's original fw. fc-shell FreeCalypso firmwares have a feature of our own invention (not present in any pre-existing ones) to accept AT commands over @@ -22,47 +42,13 @@ available for a dedicated standard AT command interface. fc-shell is the tool that allows you to send AT commands to the firmware in this manner; it also allows a few other kinds of - asynchronous commands to be sent. - -tfc139 This tool breaks into Mot C1xx phones via shellcode injection, - a method that works despite any bootloader locks, allowing you - to reflash locked phones with new firmware with fc-loadtool. - The name of the utility is historical: previously it was - specific to TFC139 phones (C139s sold with TracFone branding), - but the current version is expected to work with all Mot C1xx - firmware versions. + asynchronous commands to be sent. It works through rvinterf. -imei-luhn A simple utility for computing or verifying the Luhn check - digit of an IMEI number. - -The following host tools are primarily for developers, but may be useful to -end users as well: - -rvtdump This tool produces a human-readable dump of all output emitted - by a TI-based GSM fw on the RVTMUX binary packet interface. It - can also log this dump to a file. +And here is a listing of all other tools in mostly-alphabetical order: -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 fc-fsio, fc-shell and fc-tmsh. - -tiffs, These tools perform "in vitro" analysis of flash file system -mokoffs, (FFS) images read out of GSM devices with TI-based firmwares. -pirffs You can list and extract the FFS content captured as a raw - flash image, and even perform a few "forensic" operations along - the lines of reading deleted files and seeing the history of - FFS modifications. tiffs is the main program, whereas mokoffs - and pirffs are convenience wrappers for the common FFS - configurations from Openmoko and Pirelli. - -fc-serterm This tool is a trivial serial terminal program. Its special - feature is that any output coming from the serial port that - isn't printable ASCII is displayed as by cat -v. It is useful - for talking to serially-interfaced devices that mix ASCII with - binary in their serial talk. - -The following tools are really just for developers: +c139explore This is a run-from-RAM (no flashing) program for Mot C139/140 + phones that exercises their peripheral hardware: LCD, keypad + backlight, buzzer and vibrator. ctracedec GSM firmwares built in TI's Windows environment (official ones as well as our own hacks based on the TCS211 semi-src) have a @@ -74,40 +60,40 @@ corresponding to the fw version that emitted the output in question; this ctracedec utility performs that decoding. -fc-iram, Reprogramming the non-volatile flash memory is not the only way -fc-xram, to run your own code on a Calypso GSM device. If your code is -fc-compalram small enough to fit entirely into the available RAM on the - device, and you would like to just run it without flashing it - permanently, these tools do the job of loading code images into - different kinds of RAM through different download protocols. +fc-buzplay This program plays piezoelectic buzzer melodies on an actual + Calypso device equipped with such a buzzer (Mot C1xx, TI's + D-Sample board, our planned future HSMBP) by loading a buzplayer + agent onto the target and feeding melodies to be played to it. + +fc-cal2text This utility takes a dump of TI's /gsm/rf flash file system + directory subtree as input (either extracted in vitro with tiffs + or read out in vivo with fc-fsio) and converts all RF tables + found therein into a readable ASCII format. See the RF_tables + article for more details. + +fc-dspapidump This utility uses ETM in synchronous mode (going through + rvinterf) to read and dump the contents of the DSP API RAM in a + target Calypso GSM device while the firmware is running. -fc-tmsh TI had a tool called TMSH that stood for "test mode shell". We - don't know exactly how it worked, hence we make no claim of our - own test mode shell being anything like TI's original, but we - do have a test mode shell of our own. It sends command packets - to the ETM (Enhanced Test Mode) component in the GSM firmware - and displays its responses in a purely asynchronous manner, - i.e., our tool has no knowledge of any correspondence between - the commands it sends and the responses they elicit. (In - contrast, fc-fsio described above also talks to ETM, but it - does so synchronously.) +fc-e1decode This utility decodes a melody in TI's Melody E1 format from the + the native binary format to our own ASCII-based representation; + see the Melody_E1 article for more information. + +fc-e1gen This utility compiles an E1 melody from our own ASCII source + format into binary bits to be loaded into a FreeCalypso phone; + see the Melody_E1 article for more information. -fc-memdump This tool captures a memory dump from a GSM device whose - firmware implements one of TI's Test Mode memory read commands, - either the old TM3 version or the new ETM one. It works with - FreeCalypso Citrine, with TCS211-based firmwares including - FreeCalypso Magnetite, with really old TI firmwares which - predate ETM, and with Mot C1xx original firmwares. +fc-fr2tch This hack-utility converts a GSM 06.10 speech sample from the + de facto standard libgsm format (which can be recorded with + standard tools like SoX) into an uplink play file that can be + played with the tch play command in fc-shell; see the + TCH-bit-access article for more information. -fc-rgbconv A simple aid for phone UI development that converts RGB color - values between human-intuitive 8:8:8 format and the 5:6:5 format - used by the color LCDs in the phones targeted by FreeCalypso. - -The following tools are really just special-purpose hacks: - -fc-dspapidump This utility uses ETM in synchronous mode to read and dump the - contents of the DSP API RAM in a target Calypso GSM device - while the firmware is running. +fc-gsm2vm This utility converts a GSM 06.10 speech sample from the same + libgsm source format into a voice memo file that can be + uploaded into the FFS of a FreeCalypso device and played with + the audio_vm_play_start() API or the AT@VMP command that + invokes the latter. fc-lcdemu We have TI's TCS211 firmware semi-src that includes TI's demo/prototype phone UI targeting the 176x220 pixel LCD on TI's @@ -116,16 +102,79 @@ a hacked-up version of the fw that emits all raster blits intended for the big LCD on the RVTMUX serial interface, and this fc-lcdemu utility is a plug-in for rvinterf that actually - displays these LCD blits in an X11 window. + displays these LCD blits in an X11 window. This program is not + built by default as it requires libX11 to compile and an X11 + display to run. -fc-fr2tch This hack-utility converts a GSM 06.10 speech sample from the - de facto standard libgsm format (which can be recorded with - standard tools like SoX) into an uplink play file that can be - played with the tch play command in fc-shell; see the - TCH-bit-access article for more information. +fc-memdump This tool captures a memory dump from a GSM device whose + firmware implements one of TI's Test Mode memory read commands, + either the old TM3 version or the new ETM one. It works with + FreeCalypso Citrine, with TCS211-based firmwares including + FreeCalypso Magnetite, with really old TI firmwares which + predate ETM, and with Mot C1xx original firmwares. It works + through rvinterf. + +fc-rgbconv A simple aid for phone UI development that converts RGB color + values between human-intuitive 8:8:8 format and the 5:6:5 format + used by the color LCDs in the phones targeted by FreeCalypso. + +fc-serterm This tool is a trivial serial terminal program. Its special + feature is that any output coming from the serial port that + isn't printable ASCII is displayed as by cat -v. It is useful + for talking to serially-interfaced devices that mix ASCII with + binary in their serial talk. fc-tch2fr This hack-utility takes a TCH downlink recording produced with the tch record command in fc-shell and converts it to a playable libgsm file which will most likely contain some garbage by disregarding the non-understood DSP status words; see the TCH-bit-access article for more information. + +fc-tmsh TI-based GSM firmwares provide a rich set of Test Mode commands + that can be issued through the RVTMUX (debug trace) serial + channel, used for L1/RF test functions, production line RF + calibration, FFS (flash file system) access, audio configuration + and other miscellany. fc-tmsh is our test mode shell for + sending these Test Mode commands to targets and displaying + decoded target responses; it works through rvinterf. fc-tmsh + supports all Test Mode commands (both TM3 and ETM) implemented + in our target firmwares except FFS access; use fc-fsio for the + latter. + +fc-vm2hex This utility converts the old-fashioned (non-AMR) voice memo + files read out of FFS into hex strings that can be analyzed by + a human or further fed to fc-tch2fr. + +imei-luhn A simple utility for computing or verifying the Luhn check + digit of an IMEI number. + +pirexplore This is a run-from-RAM (no flashing) program for Pirelli DP-L10 + phones that exercises their peripheral hardware, primarily their + LCD. + +rvtdump This tool produces a human-readable dump of all output emitted + by a TI-based GSM fw on the RVTMUX binary packet interface. It + can also log this dump to a file. + +tfc139 This tool breaks into Mot C1xx phones via shellcode injection, + a method that works despite any bootloader locks, allowing you + to reflash locked phones with new firmware with fc-loadtool. + The name of the utility is historical: previously it was + specific to TFC139 phones (C139s sold with TracFone branding), + but the current version is expected to work with all Mot C1xx + firmware versions. + +tiaud-decomp This utility decodes TI's audio mode configuration files read + out of FFS into our own ASCII format. The tool to perform the + opposite conversion (compile these audio mode config files + "in vitro" from an ASCII text source) is planned, but has not + been written yet. + +tiffs, These tools perform "in vitro" analysis of flash file system +mokoffs, (FFS) images read out of GSM devices with TI-based firmwares. +pirffs You can list and extract the FFS content captured as a raw + flash image, and even perform a few "forensic" operations along + the lines of reading deleted files and seeing the history of + FFS modifications. tiffs is the main program, whereas mokoffs + and pirffs are convenience wrappers for the common FFS + configurations from Openmoko and Pirelli.