FreeCalypso > hg > freecalypso-tools

comparison doc/Host-tools-overview @ 0:e7502631a0f9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial import from freecalypso-sw rev 1033:5ab737ac3ad7
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 11 Jun 2016 00:13:35 +0000
parents
children 10b71f01f4ff
comparison
equal deleted inserted replaced
-1:000000000000 0:e7502631a0f9
1 FreeCalypso host tools suite features the following tools that are potentially
2 useful to end users:
3
4 fc-loadtool This is the tool used to read and write the non-volatile flash
5 memory of supported GSM devices. It can be used to reflash
6 these devices with new firmware (whether pre-existing or new
7 firmwares developed within our project), and to save and restore
8 flash backups. This tool operates on the target device (phone
9 or modem) while its regular firmware is shut down.
10
11 fc-fsio This tool connects to GSM devices running one of the supported
12 firmware versions while the fw is running (unlike fc-loadtool
13 which operates on a device while its regular fw is shut down)
14 and allows you to manipulate (read and write) the device's
15 flash file system. It is thus a higher-level tool than
16 fc-loadtool. It is intended primarily for working with our own
17 firmwares, but it also works with Pirelli's original fw.
18
19 fc-shell FreeCalypso firmwares have a feature of our own invention (not
20 present in any pre-existing ones) to accept AT commands over
21 the RVTMUX interface. It is useful when no second UART is
22 available for a dedicated standard AT command interface.
23 fc-shell is the tool that allows you to send AT commands to the
24 firmware in this manner; it also allows a few other kinds of
25 asynchronous commands to be sent.
26
27 tfc139 This tool breaks into Mot C1xx phones via shellcode injection,
28 a method that works despite any bootloader locks, allowing you
29 to reflash locked phones with new firmware with fc-loadtool.
30 The name of the utility is historical: previously it was
31 specific to TFC139 phones (C139s sold with TracFone branding),
32 but the current version is expected to work with all Mot C1xx
33 firmware versions.
34
35 imei-luhn A simple utility for computing or verifying the Luhn check
36 digit of an IMEI number.
37
38 The following host tools are primarily for developers, but may be useful to
39 end users as well:
40
41 rvtdump This tool produces a human-readable dump of all output emitted
42 by a TI-based GSM fw on the RVTMUX binary packet interface. It
43 can also log this dump to a file.
44
45 rvinterf This tool is a superset of rvtdump: it not only dumps and/or
46 logs all output from the GSM fw, but also provides a mechanism
47 for sending command packets to it. Rvinterf is the engine
48 behind fc-fsio, fc-shell and fc-tmsh.
49
50 tiffs, These tools perform "in vitro" analysis of flash file system
51 mokoffs, (FFS) images read out of GSM devices with TI-based firmwares.
52 pirffs You can list and extract the FFS content captured as a raw
53 flash image, and even perform a few "forensic" operations along
54 the lines of reading deleted files and seeing the history of
55 FFS modifications. tiffs is the main program, whereas mokoffs
56 and pirffs are convenience wrappers for the common FFS
57 configurations from Openmoko and Pirelli.
58
59 fc-getpirimei This utility retrieves the factory-programmed IMEI of a Pirelli
60 DP-L10 phone by quering its running firmware over the RVTMUX
61 interface.
62
63 fc-serterm This tool is a trivial serial terminal program. Its special
64 feature is that any output coming the serial port that isn't
65 printable ASCII is displayed as by cat -v. It is useful for
66 talking to serially-interfaced devices that mix ASCII with
67 binary in their serial talk.
68
69 The following tools are really just for developers:
70
71 ctracedec GSM firmwares built in TI's Windows environment (official ones
72 as well as our own hacks based on the TCS211 semi-src) have a
73 "compressed trace" misfeature whereby many of the ASCII strings
74 in debug trace messages get replaced with numeric indices at
75 build time, and these numeric indices are all that gets emitted
76 on the RVTMUX serial channel. This numeric trace output can be
77 turned back into ASCII strings if you have the str2ind.tab file
78 corresponding to the fw version that emitted the output in
79 question; this ctracedec utility performs that decoding.
80
81 fc-iram, Reprogramming the non-volatile flash memory is not the only way
82 fc-xram, to run your own code on a Calypso GSM device. If your code is
83 fc-compalram small enough to fit entirely into the available RAM on the
84 device, and you would like to just run it without flashing it
85 permanently, these tools do the job of loading code images into
86 different kinds of RAM through different download protocols.
87
88 fc-tmsh TI had a tool called TMSH that stood for "test mode shell". We
89 don't know exactly how it worked, hence we make no claim of our
90 own test mode shell being anything like TI's original, but we
91 do have a test mode shell of our own. It sends command packets
92 to the ETM (Enhanced Test Mode) component in the GSM firmware
93 and displays its responses in a purely asynchronous manner,
94 i.e., our tool has no knowledge of any correspondence between
95 the commands it sends and the responses they elicit. (In
96 contrast, fc-fsio described above also talks to ETM, but it
97 does so synchronously.)
98
99 fc-olddump This tool captures a memory dump from a GSM device whose
100 firmware implements the old non-enhanced Test Mode memory read
101 command. It works with Mot C1xx original firmwares.
102
103 fc-rgbconv A simple aid for phone UI development that converts RGB color
104 values between human-intuitive 8:8:8 format and the 5:6:5 format
105 used by the color LCDs in the phones targeted by FreeCalypso.
106
107 The following tools are really just special-purpose hacks:
108
109 fc-dspapidump This utility uses ETM in synchronous mode to read and dump the
110 contents of the DSP API RAM in a target Calypso GSM device
111 while the firmware is running.
112
113 fc-lcdemu We have TI's TCS211 firmware semi-src that includes TI's
114 demo/prototype phone UI targeting the 176x220 pixel LCD on TI's
115 D-Sample development kit, but no suitable hardware on which we
116 could run this fw with this UI and see it in action. We built
117 a hacked-up version of the fw that emits all raster blits
118 intended for the big LCD on the RVTMUX serial interface, and
119 this fc-lcdemu utility is a plug-in for rvinterf that actually
120 displays these LCD blits in an X11 window.
121
122 fc-pirhackinit This fc-pirhackinit utility is highly specific to the
123 TCS211-on-Pirelli exercise. DO NOT run it against Pirelli's
124 stock firmware, nor is it needed when using our full-source
125 FreeCalypso firmware.