FreeCalypso > hg > freecalypso-tools
view doc/Host-tools-overview @ 216:7e3e3a958e3f
doc/Host-tools-overview: updated and simplified
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sat, 20 May 2017 12:48:38 +0000 |
parents | 3c446058b5a6 |
children | 97d6d593ffc6 |
line wrap: on
line source
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 these devices with new firmware (whether pre-existing or new firmwares developed within our project), and to save and restore flash backups. This tool operates on the target device (phone or modem) while its regular firmware is shut down. 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 the RVTMUX interface. It is useful when no second UART is 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. It works through rvinterf. And here is a listing of all other tools in mostly-alphabetical order: 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 "compressed trace" misfeature whereby many of the ASCII strings in debug trace messages get replaced with numeric indices at build time, and these numeric indices are all that gets emitted on the RVTMUX serial channel. This numeric trace output can be turned back into ASCII strings if you have the str2ind.tab file corresponding to the fw version that emitted the output in question; this ctracedec utility performs that decoding. 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-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-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-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 D-Sample development kit, but no suitable hardware on which we could run this fw with this UI and see it in action. We built 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. This program is not built by default as it requires libX11 to compile and an X11 display to run. 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.