+
−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-pulse-dtr	This trivial utility opens a serial port, asserts DTR for 50 ms,
+
−		then negates it and exits.  See the DUART28-boot-control article
+
−		for the explanation.
+
−
+
−fc-pulse-rts	This trivial utility opens a serial port, asserts RTS for 50 ms,
+
−		then negates it and exits.  See the DUART28-boot-control article
+
−		for the explanation.
+
−
+
−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
+
−tiffs-8m	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,
+
−		pirffs and tiffs-8m are convenience wrappers for the common FFS
+
−		configurations from Openmoko, Pirelli and Tango.
+
−
+
−tiffs-mkfs	This utility constructs a TI flash file system (TIFFS) image
+
−		completely from scratch "in vitro", containing initial directory
+
−		and file content given by a Unix directory and file tree on the
+
−		host system.  The resulting image can then be flashed into a
+
−		Calypso GSM device running FreeCalypso firmware.