# HG changeset patch # User Mychaela Falconia # Date 1446865310 0 # Node ID 6475a935e5932bf87ec2a7430b8d3b7064df53d5 # Parent 64cddafcd939029f230bda72556329dfb079331d doc/Host-tools-overview written diff -r 64cddafcd939 -r 6475a935e593 doc/Host-tools-overview --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Host-tools-overview Sat Nov 07 03:01:50 2015 +0000 @@ -0,0 +1,117 @@ +FreeCalypso host tools suite features the following tools that are potentially +useful to end users: + +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-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-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. + +tfc139 This tool breaks into locked-down Mot C139 phones sold with + TracFone branding, allowing you to reflash them with new + firmware with fc-loadtool. + +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. + +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-getpirimei This utility retrieves the factory-programmed IMEI of a Pirelli + DP-L10 phone by quering its running firmware over the RVTMUX + interface. + +fc-serterm This tool is a trivial serial terminal program. Its special + feature is that any output coming 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: + +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-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-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-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-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. + +fc-pirhackinit This fc-pirhackinit utility is highly specific to the + TCS211-on-Pirelli exercise. DO NOT run it against Pirelli's + stock firmware, nor is it needed when using our full-source + FreeCalypso firmware.