FreeCalypso > hg > freecalypso-tools

comparison doc/Host-tools-overview @ 216:7e3e3a958e3f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Host-tools-overview: updated and simplified
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 20 May 2017 12:48:38 +0000
parents 3c446058b5a6
children 97d6d593ffc6
comparison
equal deleted inserted replaced
215:1a658ab756fe 216:7e3e3a958e3f
1 FreeCalypso host tools suite features the following tools that are potentially 1 FreeCalypso host tools suite includes a large number of different tools, many
2 useful to end users: 2 of which are quite specialized and rarely needed. The following tools are the
3 most essential ones:
3 4
4 fc-loadtool This is the tool used to read and write the non-volatile flash 5 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 memory of supported GSM devices. It can be used to reflash
6 these devices with new firmware (whether pre-existing or new 7 these devices with new firmware (whether pre-existing or new
7 firmwares developed within our project), and to save and restore 8 firmwares developed within our project), and to save and restore
8 flash backups. This tool operates on the target device (phone 9 flash backups. This tool operates on the target device (phone
9 or modem) while its regular firmware is shut down. 10 or modem) while its regular firmware is shut down.
10 11
11 fc-fsio This tool connects to GSM devices running one of the supported 12 fc-iram, Reprogramming the non-volatile flash memory is not the only way
12 firmware versions while the fw is running (unlike fc-loadtool 13 fc-xram, to run your own code on a Calypso GSM device. If your code is
13 which operates on a device while its regular fw is shut down) 14 fc-compalram small enough to fit entirely into the available RAM on the
14 and allows you to manipulate (read and write) the device's 15 device, and you would like to just run it without flashing it
15 flash file system. It is thus a higher-level tool than 16 permanently, these tools do the job of loading code images into
16 fc-loadtool. It is intended primarily for working with our own 17 different kinds of RAM through different download protocols.
17 firmwares, but it also works with Pirelli's original fw. 18 Some phones have large enough RAM to allow a complete functional
19 firmware image to be run via fc-xram without flashing.
20
21 rvinterf This program is our engine for communicating with up & running
22 TI-based firmwares through the RVTMUX binary packet interface.
23 It receives and decodes all debug trace and other packets
24 emitted by the target fw, and allows the options of printing
25 them on the terminal, saving them to a log file, and/or passing
26 them to other programs that connect to rvinterf as local socket
27 clients. In the other direction those latter client programs
28 can send arbitrary command packets to the target fw.
29
30 fc-fsio Going through rvinterf, this tool connects to GSM devices
31 running one of the supported firmware versions while the fw is
32 running (unlike fc-loadtool which operates on a device while
33 its regular fw is shut down) and allows you to manipulate
34 (read and write) the device's flash file system. It is thus a
35 higher-level tool than fc-loadtool. It is intended primarily
36 for working with our own firmwares, but it also works with
37 Pirelli's original fw.
18 38
19 fc-shell FreeCalypso firmwares have a feature of our own invention (not 39 fc-shell FreeCalypso firmwares have a feature of our own invention (not
20 present in any pre-existing ones) to accept AT commands over 40 present in any pre-existing ones) to accept AT commands over
21 the RVTMUX interface. It is useful when no second UART is 41 the RVTMUX interface. It is useful when no second UART is
22 available for a dedicated standard AT command interface. 42 available for a dedicated standard AT command interface.
23 fc-shell is the tool that allows you to send AT commands to the 43 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 44 firmware in this manner; it also allows a few other kinds of
25 asynchronous commands to be sent. 45 asynchronous commands to be sent. It works through rvinterf.
26 46
27 tfc139 This tool breaks into Mot C1xx phones via shellcode injection, 47 And here is a listing of all other tools in mostly-alphabetical order:
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 48
35 imei-luhn A simple utility for computing or verifying the Luhn check 49 c139explore This is a run-from-RAM (no flashing) program for Mot C139/140
36 digit of an IMEI number. 50 phones that exercises their peripheral hardware: LCD, keypad
37 51 backlight, buzzer and vibrator.
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-serterm This tool is a trivial serial terminal program. Its special
60 feature is that any output coming from the serial port that
61 isn't printable ASCII is displayed as by cat -v. It is useful
62 for talking to serially-interfaced devices that mix ASCII with
63 binary in their serial talk.
64
65 The following tools are really just for developers:
66 52
67 ctracedec GSM firmwares built in TI's Windows environment (official ones 53 ctracedec GSM firmwares built in TI's Windows environment (official ones
68 as well as our own hacks based on the TCS211 semi-src) have a 54 as well as our own hacks based on the TCS211 semi-src) have a
69 "compressed trace" misfeature whereby many of the ASCII strings 55 "compressed trace" misfeature whereby many of the ASCII strings
70 in debug trace messages get replaced with numeric indices at 56 in debug trace messages get replaced with numeric indices at
72 on the RVTMUX serial channel. This numeric trace output can be 58 on the RVTMUX serial channel. This numeric trace output can be
73 turned back into ASCII strings if you have the str2ind.tab file 59 turned back into ASCII strings if you have the str2ind.tab file
74 corresponding to the fw version that emitted the output in 60 corresponding to the fw version that emitted the output in
75 question; this ctracedec utility performs that decoding. 61 question; this ctracedec utility performs that decoding.
76 62
77 fc-iram, Reprogramming the non-volatile flash memory is not the only way 63 fc-buzplay This program plays piezoelectic buzzer melodies on an actual
78 fc-xram, to run your own code on a Calypso GSM device. If your code is 64 Calypso device equipped with such a buzzer (Mot C1xx, TI's
79 fc-compalram small enough to fit entirely into the available RAM on the 65 D-Sample board, our planned future HSMBP) by loading a buzplayer
80 device, and you would like to just run it without flashing it 66 agent onto the target and feeding melodies to be played to it.
81 permanently, these tools do the job of loading code images into
82 different kinds of RAM through different download protocols.
83 67
84 fc-tmsh TI had a tool called TMSH that stood for "test mode shell". We 68 fc-cal2text This utility takes a dump of TI's /gsm/rf flash file system
85 don't know exactly how it worked, hence we make no claim of our 69 directory subtree as input (either extracted in vitro with tiffs
86 own test mode shell being anything like TI's original, but we 70 or read out in vivo with fc-fsio) and converts all RF tables
87 do have a test mode shell of our own. It sends command packets 71 found therein into a readable ASCII format. See the RF_tables
88 to the ETM (Enhanced Test Mode) component in the GSM firmware 72 article for more details.
89 and displays its responses in a purely asynchronous manner,
90 i.e., our tool has no knowledge of any correspondence between
91 the commands it sends and the responses they elicit. (In
92 contrast, fc-fsio described above also talks to ETM, but it
93 does so synchronously.)
94 73
95 fc-memdump This tool captures a memory dump from a GSM device whose 74 fc-dspapidump This utility uses ETM in synchronous mode (going through
96 firmware implements one of TI's Test Mode memory read commands, 75 rvinterf) to read and dump the contents of the DSP API RAM in a
97 either the old TM3 version or the new ETM one. It works with 76 target Calypso GSM device while the firmware is running.
98 FreeCalypso Citrine, with TCS211-based firmwares including
99 FreeCalypso Magnetite, with really old TI firmwares which
100 predate ETM, and with Mot C1xx original firmwares.
101 77
102 fc-rgbconv A simple aid for phone UI development that converts RGB color 78 fc-e1decode This utility decodes a melody in TI's Melody E1 format from the
103 values between human-intuitive 8:8:8 format and the 5:6:5 format 79 the native binary format to our own ASCII-based representation;
104 used by the color LCDs in the phones targeted by FreeCalypso. 80 see the Melody_E1 article for more information.
105 81
106 The following tools are really just special-purpose hacks: 82 fc-e1gen This utility compiles an E1 melody from our own ASCII source
83 format into binary bits to be loaded into a FreeCalypso phone;
84 see the Melody_E1 article for more information.
107 85
108 fc-dspapidump This utility uses ETM in synchronous mode to read and dump the 86 fc-fr2tch This hack-utility converts a GSM 06.10 speech sample from the
109 contents of the DSP API RAM in a target Calypso GSM device 87 de facto standard libgsm format (which can be recorded with
110 while the firmware is running. 88 standard tools like SoX) into an uplink play file that can be
89 played with the tch play command in fc-shell; see the
90 TCH-bit-access article for more information.
91
92 fc-gsm2vm This utility converts a GSM 06.10 speech sample from the same
93 libgsm source format into a voice memo file that can be
94 uploaded into the FFS of a FreeCalypso device and played with
95 the audio_vm_play_start() API or the AT@VMP command that
96 invokes the latter.
111 97
112 fc-lcdemu We have TI's TCS211 firmware semi-src that includes TI's 98 fc-lcdemu We have TI's TCS211 firmware semi-src that includes TI's
113 demo/prototype phone UI targeting the 176x220 pixel LCD on TI's 99 demo/prototype phone UI targeting the 176x220 pixel LCD on TI's
114 D-Sample development kit, but no suitable hardware on which we 100 D-Sample development kit, but no suitable hardware on which we
115 could run this fw with this UI and see it in action. We built 101 could run this fw with this UI and see it in action. We built
116 a hacked-up version of the fw that emits all raster blits 102 a hacked-up version of the fw that emits all raster blits
117 intended for the big LCD on the RVTMUX serial interface, and 103 intended for the big LCD on the RVTMUX serial interface, and
118 this fc-lcdemu utility is a plug-in for rvinterf that actually 104 this fc-lcdemu utility is a plug-in for rvinterf that actually
119 displays these LCD blits in an X11 window. 105 displays these LCD blits in an X11 window. This program is not
106 built by default as it requires libX11 to compile and an X11
107 display to run.
120 108
121 fc-fr2tch This hack-utility converts a GSM 06.10 speech sample from the 109 fc-memdump This tool captures a memory dump from a GSM device whose
122 de facto standard libgsm format (which can be recorded with 110 firmware implements one of TI's Test Mode memory read commands,
123 standard tools like SoX) into an uplink play file that can be 111 either the old TM3 version or the new ETM one. It works with
124 played with the tch play command in fc-shell; see the 112 FreeCalypso Citrine, with TCS211-based firmwares including
125 TCH-bit-access article for more information. 113 FreeCalypso Magnetite, with really old TI firmwares which
114 predate ETM, and with Mot C1xx original firmwares. It works
115 through rvinterf.
116
117 fc-rgbconv A simple aid for phone UI development that converts RGB color
118 values between human-intuitive 8:8:8 format and the 5:6:5 format
119 used by the color LCDs in the phones targeted by FreeCalypso.
120
121 fc-serterm This tool is a trivial serial terminal program. Its special
122 feature is that any output coming from the serial port that
123 isn't printable ASCII is displayed as by cat -v. It is useful
124 for talking to serially-interfaced devices that mix ASCII with
125 binary in their serial talk.
126 126
127 fc-tch2fr This hack-utility takes a TCH downlink recording produced with 127 fc-tch2fr This hack-utility takes a TCH downlink recording produced with
128 the tch record command in fc-shell and converts it to a playable 128 the tch record command in fc-shell and converts it to a playable
129 libgsm file which will most likely contain some garbage by 129 libgsm file which will most likely contain some garbage by
130 disregarding the non-understood DSP status words; see the 130 disregarding the non-understood DSP status words; see the
131 TCH-bit-access article for more information. 131 TCH-bit-access article for more information.
132
133 fc-tmsh TI-based GSM firmwares provide a rich set of Test Mode commands
134 that can be issued through the RVTMUX (debug trace) serial
135 channel, used for L1/RF test functions, production line RF
136 calibration, FFS (flash file system) access, audio configuration
137 and other miscellany. fc-tmsh is our test mode shell for
138 sending these Test Mode commands to targets and displaying
139 decoded target responses; it works through rvinterf. fc-tmsh
140 supports all Test Mode commands (both TM3 and ETM) implemented
141 in our target firmwares except FFS access; use fc-fsio for the
142 latter.
143
144 fc-vm2hex This utility converts the old-fashioned (non-AMR) voice memo
145 files read out of FFS into hex strings that can be analyzed by
146 a human or further fed to fc-tch2fr.
147
148 imei-luhn A simple utility for computing or verifying the Luhn check
149 digit of an IMEI number.
150
151 pirexplore This is a run-from-RAM (no flashing) program for Pirelli DP-L10
152 phones that exercises their peripheral hardware, primarily their
153 LCD.
154
155 rvtdump This tool produces a human-readable dump of all output emitted
156 by a TI-based GSM fw on the RVTMUX binary packet interface. It
157 can also log this dump to a file.
158
159 tfc139 This tool breaks into Mot C1xx phones via shellcode injection,
160 a method that works despite any bootloader locks, allowing you
161 to reflash locked phones with new firmware with fc-loadtool.
162 The name of the utility is historical: previously it was
163 specific to TFC139 phones (C139s sold with TracFone branding),
164 but the current version is expected to work with all Mot C1xx
165 firmware versions.
166
167 tiaud-decomp This utility decodes TI's audio mode configuration files read
168 out of FFS into our own ASCII format. The tool to perform the
169 opposite conversion (compile these audio mode config files
170 "in vitro" from an ASCII text source) is planned, but has not
171 been written yet.
172
173 tiffs, These tools perform "in vitro" analysis of flash file system
174 mokoffs, (FFS) images read out of GSM devices with TI-based firmwares.
175 pirffs You can list and extract the FFS content captured as a raw
176 flash image, and even perform a few "forensic" operations along
177 the lines of reading deleted files and seeing the history of
178 FFS modifications. tiffs is the main program, whereas mokoffs
179 and pirffs are convenience wrappers for the common FFS
180 configurations from Openmoko and Pirelli.