FreeCalypso > hg > freecalypso-sw

annotate doc/Host-tools-overview @ 1001:5e73df562a7d

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