FreeCalypso > hg > freecalypso-tools
view doc/Host-tools-overview @ 631:bdb69847c809
CHANGES: updates for fc-loadtool and setserial mystery
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sat, 29 Feb 2020 21:34:03 +0000 |
parents | 46d17c346511 |
children | 9b0ad72184e3 |
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. c1xx-calextr This utility extracts the factory RF calibration values for Mot C1xx phones from the records contained in a special sector of their flash and converts them to FreeCalypso format, to be used when running our own firmware on these phones. See the Compal-calibration article for more details. compile-fc-batt This utility compiles a table of battery thresholds for the new FreeCalypso battery management code from ASCII source into the binary form suitable for uploading into /etc/batterytab on a FreeCalypso device. It is rarely used directly, instead fc-fsio write-battery-table command invokes compile-fc-batt behind the scenes. compile-fc-chg This utility compiles a FreeCalypso battery charging configuration file from ASCII source into the binary form suitable for uploading into /etc/charging on a FreeCalypso device. It is rarely used directly, instead fc-fsio write-charging-config command invokes compile-fc-chg behind the scenes. 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-bin2rftab This program is a developer tool: it reads a binary RF table of the user-specified type from a binary file (at a user-specified offset, allowing extraction of tables from alien firmwares and whatnot) and emits it in FreeCalypso ASCII format. 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-cal2bin This utility takes an RF table in FreeCalypso ASCII format and converts it to the firmware's native binary format. See the RF_tables article for more details. 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-dspromdump This utility feeds a dump agent program (dspdump) to the target Calypso device's ARM boot ROM and then commands this dump agent program to perform a complete dump of the chip's DSP ROM. See the DSP-ROM-dump article for more details. 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 Moved to freecalypso-ui-dev repository; look there for more info. fc-lcdpoll New companion utility to fc-lcdemu; look in freecalypso-ui-dev for more info. 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-readcal This program attempts to read a bunch of RF calibration tables out of a running firmware through Test Mode commands: first tms 1, then rfpw 7 for each band, then rftr and ttr commands to read various tables. The primary intended purpose is extracting RF calibration or static configuration data from alien firmwares. Please beware that the tms 1 and rfpw 7 commands sent by this tool are highly disruptive to normal GSM operation. fc-rftab2c This program is a developer tool: it takes an RF parameter table of one of the supported types in FreeCalypso ASCII format and converts it into a C code snippet suitable for insertion into the firmware source in the L1 RF "customization" code where compiled-in default RF parameter tables are defined. 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-tmsh is fully asynchronous in that the issuance of commands to the target and the handling of target responses are fully decoupled. fc-tmsync This program reimplements a small subset of fc-tmsh commands in a synchronous manner; it was written together with fc-readcal for the same purpose of extracting "in vivo" data from alien firmwares. 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. fcup-* FreeCalypso User Phone Tools; see the User-phone-tools article. imei-luhn A simple utility for computing or verifying the Luhn check digit of an IMEI number. mokosrec2bin This utility converts "moko-style" S-record files (those produced by TI's hex470 tool with -memwidth 16 -romwidth 16 options) to straight binary. pcm-sms-decode Some TI-based vendor firmwares (not TI's original and not FreeCalypso) implement SMS storage in their FFS in a file named /pcm/SMS in the same format in which SMS records are stored in SIM cards (EF_SMS elementary file). Pirelli's firmware is one major user of this mechanism. This /pcm/SMS file can be read out in vivo via fc-fsio or extracted in vitro via tiffs; the new pcm-sms-decode utility decodes the stored SMS content from this binary file similarly to sms-pdu-decode. 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. sms-pdu-decode This utility is part of FC User Phone Tools; see the User-phone-tools article. srec-regions This utility parses a firmware image file in S-record format, identifies the set of discontiguous regions into which this SREC image deposits bits, and lists these identified regions. 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-compile This utility compiles an audio mode configuration table for TI's Audio Service from our own ASCII source format into the binary format for uploading into FreeCalypso GSM device FFS with fc-fsio. tiaud-decomp This utility decodes TI's audio mode configuration files read out of FFS into our own ASCII format. It is the reverse of the operation performed by tiaud-compile. tiaud-mkvol This utility is a companion to tiaud-compile that generates the *.vol binary files which need to accompany the main *.cfg ones. 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.