FreeCalypso > hg > freecalypso-tools

comparison doc/Loadtools-usage @ 209:5433349a6e2c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Loadtools-usage: replacing loadtools/README
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 18 May 2017 22:52:12 +0000
parents
children 1a658ab756fe
comparison
equal deleted inserted replaced
208:4022bfbaafd4 209:5433349a6e2c
1 The loadtools subset of FreeCalypso host tools consists of:
2
3 fc-loadtool The tool for operating on Calypso GSM devices at a low
4 level. After "breaking" into the target GSM device in
5 its boot process and getting FreeCalypso loadagent
6 running on the target (out of Calypso internal RAM, aka
7 IRAM), loadtool presents an interactive command prompt
8 with commands for peeking and poking registers and most
9 importantly, reading and writing any part of the
10 device's non-volatile flash memory.
11
12 fc-iram & fc-xram These utilities are intended for FreeCalypso developers
13 only. They load an S-record code image into IRAM or
14 XRAM, respectively, induce a transfer of control to the
15 loaded code, and then drop into a serial line pass-thru
16 mode for the operator to interact with the thus loaded
17 target code.
18
19 The currently supported target devices are (in the order of decreasing
20 preference) official Calypso development boards (TI's D-Sample and our own
21 FCDEV3B), Openmoko's GTA0x GSM modem, and two "alien" Calypso phone families:
22 Mot C1xx by Compal and Pirelli DP-L10 by Foxconn.
23
24 All tools in the FreeCalypso loadtools suite work by feeding pieces of code to
25 the target device as it boots, preventing the booting of its regular firmware
26 and diverting control to these externally-loaded code pieces. These pieces of
27 ARM7 target code need to be installed on the host system running loadtools,
28 normally in /opt/freecalypso/target-bin:
29
30 loadagent This is the "agent" code that runs on the target device when
31 fc-loadtool is operating on it: loadtool carries out its
32 operations by sending commands to loadagent. There is only one
33 version of loadagent for all currently supported Calypso
34 targets: loadagent does not access any resources outside of the
35 Calypso chip itself unless commanded to do so, and loadtool
36 supports different target devices with different hardware
37 configurations by sending different commands to loadagent as
38 appropriate.
39
40 compalstage For Compal phones only: a little piece of code that is fed to
41 the original fw's bootloader via the serial download protocol
42 provided by the latter; it re-enables the Calypso chip boot ROM
43 and jumps to it, allowing our loadagent to be loaded in the
44 same way as on freedom-enabled devices.
45
46 If you are working with a development snapshot of the freecalypso-tools source
47 tree, you will need to compile and install a GNU cross-compiler toolchain
48 targeting ARM7 (see ../toolchain) and then use that toolchain to compile
49 loadagent and compalstage (see ../target-utils) before you can successfully use
50 loadtools to operate on a target device. End-user oriented releases of
51 FreeCalypso host tools include prebuilt loadagent and compalstage binaries.
52
53 Basic usage
54 ===========
55
56 The steps for bringing up fc-loadtool to operate on a target Calypso device are
57 as follows:
58
59 1. If you are using a USB serial adapter, or operating on a Pirelli phone that
60 has one built in, connect the USB side first so that the necessary
61 /dev/ttyUSB* device node appears. If you are working with a target such as
62 FCDEV3B or D-Sample on which both Calypso UARTs are equally accessible with
63 equal convenience, you can arbitrarily pick either one for fc-loadtool - it
64 will work exactly the same through either port.
65
66 2. Run fc-loadtool like this:
67
68 fc-loadtool $TARGETOPT /dev/ttyXXX
69
70 Change /dev/ttyXXX to the actual serial port you are using, and change
71 $TARGETOPT to:
72
73 Device Needed options
74 -----------------------------------
75 FreeCalypso FCDEV3B -h fcfam
76 Mot C11x/123 -h compal
77 Mot C139/140 -h compal -c 1004
78 Mot C155/156 -h c155
79 Openmoko GTA02 -h gta02
80 Pirelli DP-L10 -h pirelli
81 TI D-Sample -h dsample
82
83 3. Cause the target device to execute its boot path. TI/Openmoko/FreeCalypso
84 and Pirelli targets have the Calypso boot ROM enabled, and will interrupt
85 and divert their normal boot path when they "hear" the beacons which
86 fc-loadtool will be sending down the serial line. Compal phones have this
87 boot ROM disabled at the board level, but their standard firmware includes a
88 flash-resident bootloader that offers a different way of interrupting the
89 boot path and loading code over the serial line; fc-loadtool will be set up
90 to speak the latter protocol when run with the corresponding options from
91 the table above.
92
93 You will see messages showing fc-loadtool's progress with feeding first
94 compalstage (if needed), then loadagent (always needed) to the target device,
95 followed by some target-specific initialization done via loadagent commands.
96 If all of the above succeeds, you will land at a loadtool> prompt. Type
97 'help', and it will guide you from there. Alternatively, you can familiarize
98 yourself with loadtool commands and operations without actually running it by
99 reading the loadtool.help text file.
100
101 Command line options
102 ====================
103
104 The fc-loadtool command lines shown above will usually be sufficient. However,
105 here is the complete command line description for all 3 tools:
106
107 fc-iram [options] ttyport iramimage.srec [2ndprog]
108 fc-xram [options] ttyport xramimage.srec [2ndprog]
109 fc-loadtool [options] ttyport
110
111 The available options are common for all 3 utilities, with a few noted
112 exceptions:
113
114 -a /path/to/loadagent
115
116 This option applies only to fc-loadtool and fc-xram. It specifies the
117 pathname at which the required loadagent.srec image should be sought,
118 overriding the compiled-in default.
119
120 -b baud
121
122 This option is common for all 3 utilities. It selects the baud rate
123 to be used when pushing the IRAM image to the Calypso boot ROM. In the
124 case of fc-iram, the selected baud rate will be in effect when the
125 loaded IRAM image is jumped to and fc-iram drops into the serial tty
126 pass-thru mode; in the case of fc-loadtool, it will be the initial baud
127 rate for communicating with loadagent, which can be switched later with
128 the baud command. The default is 115200 baud.
129
130 -B baud
131
132 This option is specific to fc-xram. It selects the baud rate to be
133 used when pushing the XRAM image to loadagent. If no -B option is
134 specified, fc-xram will communicate with loadagent at the same baud
135 rate that was used to load loadagent itself via the Calypso boot ROM
136 download protocol, i.e., the rate selected with -b, defaulting to
137 115200 baud if no -b option was given either. Neither -b nor -B
138 affects the baud rate that will be in effect when the loaded XRAM image
139 is jumped to and fc-xram drops into the serial tty pass-thru mode: that
140 baud rate independently defaults to 115200 baud and can only be changed
141 with the -r option.
142
143 -c <compalstage flavor>
144
145 This option is common for all 3 utilities. It directs the tools to
146 perform the Compal loading stage before proceeding with the Calypso
147 boot ROM serial protocol, and selects the "flavor" of compalstage to
148 use. As you can see in the source, compalstage is built in 3 different
149 versions, for different C1xx models which exhibit different quirks.
150
151 This option overrides the compal-stage setting given in the hardware
152 parameter file selected with -h or -H; the -c or -C option must be given
153 after -h or -H in order to take effect. -c none disables the Compal
154 stage and causes the tools to proceed directly to the Calypso boot ROM
155 phase, even on targets for which the hardware parameter file specifies
156 compal-stage.
157
158 -C /path/to/compalstage-binary
159
160 This option is just like -c, except that the given argument is used
161 directly as the compalstage binary file pathname (absolute or relative)
162 without checking or alteration.
163
164 -h hwtype
165
166 This option is common for all 3 utilities. It selects the specific
167 target device configuration to be used. More precisely, it constructs
168 a pathname of the form /opt/freecalypso/loadtools/%s.config, where %s
169 is the argument given to this option, and uses that file as the hardware
170 parameter file.
171
172 The hardware configurations known to the present release of FreeCalypso
173 loadtools are listed in the "Basic usage" section above.
174
175 -H /path/to/hwparam-file
176
177 This option is just like -h, except that the given argument is used
178 directly as the hardware parameter file pathname (absolute or relative)
179 without alteration.
180
181 -i num
182
183 This option is common for all 3 utilities. It specifies the interval
184 in milliseconds at which the tool will send "please interrupt the boot
185 process" beacons out the serial port, hoping to catch the Calypso
186 internal boot ROM. The default is 13 ms.
187
188 -n
189
190 This option does anything only when loadtools have been compiled to run
191 on GTA0x AP (see the corresponding section below). If you've compiled
192 loadtools with the -DGTA0x_AP_BUILD option, it has an effect of making
193 each tool automatically toggle the modem power control upon startup,
194 removing the need for manual sequencing of the Calypso boot process.
195 This -n option suppresses that action, making the AP build behave like
196 the standard build in this regard.
197
198 -r baud (fc-loadtool)
199
200 This option is specific to fc-loadtool. It causes the tool to skip its
201 normal steps of feeding loadagent and possibly compalstage to the target
202 via special serial protocols, and instead assume that the target is
203 already running loadagent, communicating at the specified baud rate.
204 In other words, reattach to an already running loadagent. Use this
205 option if your fc-loadtool session has been terminated ungracefully and
206 you would like to reattach and resume, rather than forcibly reset the
207 target by yanking and reinserting the battery and restart from the
208 beginning.
209
210 -r baud (fc-xram)
211
212 This option is specific to fc-xram. It selects the serial line baud
213 rate which should be set just before the loaded XRAM image is jumped
214 to; the default is 115200 baud.
215
216 fc-iram & fc-xram 2nd program invokation
217 ========================================
218
219 Our fc-iram and fc-xram utilities can take two possible actions after they have
220 loaded the specified S-record image into RAM:
221
222 * The default action, in the absence of additional command line arguments, is
223 to drop into a serial tty pass-thru mode.
224
225 * The alternative action is to invoke a 2nd program and pass the serial
226 communication channel to it. This 2nd program invokation facility is intended
227 primarily for passing the serial communication channel to rvinterf or rvtdump
228 from the FreeCalypso host tools suite, not for launching any arbitrary
229 3rd-party programs from fc-xram or fc-iram.
230
231 This feature was originally implemented in fc-xram only, and the intended usage
232 scenario is that one builds a version of one of our FreeCalypso GSM firmwares
233 (or some subset thereof, such as an "in vivo" FFS editing agent) in the ramImage
234 configuration, fc-xram is used to load that ramImage into the target device,
235 and then the serial communication channel (RVTMUX) is immediately taken over by
236 rvinterf or rvtdump.
237
238 This second program invokation capability was later extended to fc-iram for no
239 purpose other than to support a hack described in the Flash-boot-defect article.