view doc/Host-tools-overview @ 22:aa20bdae9e53

doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 22 Oct 2016 16:21:22 +0000
parents e7502631a0f9
children 10b71f01f4ff
line wrap: on
line source

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

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-olddump	This tool captures a memory dump from a GSM device whose
		firmware implements the old non-enhanced Test Mode memory read
		command.  It works with Mot C1xx original firmwares.

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.