FreeCalypso > hg > freecalypso-sw

annotate doc/Host-tools-overview @ 984:8c83777f856c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
tfc139 reworked for the new "universal" break-in method
author Mychaela Falconia <falcon@ivan.Harhan.ORG>
date Sat, 12 Dec 2015 03:17:12 +0000
parents 6475a935e593
children 0b7abc72e49e
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
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
27 tfc139 This tool breaks into locked-down Mot C139 phones sold with
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
28 TracFone branding, allowing you to reflash them with new
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
29 firmware with fc-loadtool.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
30
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
31 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
32 digit of an IMEI number.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
33
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
34 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
35 end users as well:
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
36
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
37 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
38 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
39 can also log this dump to a file.
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 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
42 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
43 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
44 behind fc-fsio, fc-shell and fc-tmsh.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
45
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
46 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
47 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
48 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
49 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
50 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
51 FFS modifications. tiffs is the main program, whereas mokoffs
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
52 and pirffs are convenience wrappers for the common FFS
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
53 configurations from Openmoko and Pirelli.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
54
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
55 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
56 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
57 interface.
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-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
60 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
61 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
62 talking to serially-interfaced devices that mix ASCII with
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
63 binary in their serial talk.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
64
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
65 The following tools are really just for developers:
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
66
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
67 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
68 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
69 "compressed trace" misfeature whereby many of the ASCII strings
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
70 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
71 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
72 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
73 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
74 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
75 question; this ctracedec utility performs that decoding.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
76
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
77 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
78 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
79 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
80 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
81 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
82 different kinds of RAM through different download protocols.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
83
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
84 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
85 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
86 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
87 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
88 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
89 and displays its responses in a purely asynchronous manner,
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
90 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
91 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
92 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
93 does so synchronously.)
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
94
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
95 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
96 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
97 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
98
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
99 The following tools are really just special-purpose hacks:
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
100
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
101 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
102 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
103 while the firmware is running.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
104
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
105 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
106 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
107 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
108 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
109 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
110 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
111 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
112 displays these LCD blits in an X11 window.
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
113
6475a935e593 doc/Host-tools-overview written
Mychaela Falconia <falcon@ivan.Harhan.ORG>
parents:
diff changeset
114 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
115 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
116 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
117 FreeCalypso firmware.