FreeCalypso > hg > freecalypso-sw

annotate doc/Host-tools-overview @ 992:a7b0b426f9ca

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
target-utils: boot ROM UART autodetection revamped The new implementation should work with both the familiar Calypso C035 boot ROM version found in our regular targets as well as the older Calypso F741979B version found on the vintage D-Sample board.
author Mychaela Falconia <falcon@ivan.Harhan.ORG>
date Wed, 30 Dec 2015 21:28:41 +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.