view doc/Host-tools-overview @ 388:3d45660f78f0

doc/User-phone-tools article written
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 11 Mar 2018 06:32:00 +0000
parents b84bc65e7f86
children 53b474e7e590
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.

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-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-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-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-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.

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-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.