FreeCalypso > hg > freecalypso-tools

comparison loadtools/README @ 0:e7502631a0f9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial import from freecalypso-sw rev 1033:5ab737ac3ad7
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 11 Jun 2016 00:13:35 +0000
parents
children 65939f352fad
comparison
equal deleted inserted replaced
-1:000000000000 0:e7502631a0f9
1 The set of host tools built in this directory 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 the Compal family of basic
20 dumbphones, the Openmoko GTA0x GSM modem and the Pirelli DP-L10 feature phone.
21
22 All tools in the FreeCalypso loadtools suite work by feeding pieces of code to
23 the target device as it boots, preventing the booting of its regular firmware
24 and diverting control to these externally-loaded code pieces. These pieces of
25 ARM7 target code need to be installed on the host system running loadtools,
26 normally in /usr/local/share/freecalypso:
27
28 loadagent This is the "agent" code that runs on the target device when
29 fc-loadtool is operating on it: loadtool carries out its
30 operations by sending commands to loadagent. There is only one
31 version of loadagent for all currently supported Calypso
32 targets: loadagent does not access any resources outside of the
33 Calypso chip itself unless commanded to do so, and loadtool
34 supports different target devices with different hardware
35 configurations by sending different commands to loadagent as
36 appropriate.
37
38 compalstage For Compal phones only: a little piece of code that is fed to
39 the original fw's bootloader via the serial download protocol
40 provided by the latter; it re-enables the Calypso chip boot ROM
41 and jumps to it, allowing our loadagent to be loaded in the
42 same way as on freedom-enabled devices.
43
44 If you are working with a development snapshot of the freecalypso-sw source
45 tree, you will need to compile and install a GNU cross-compiler toolchain
46 targeting ARM7 (see ../toolchain) and then use that toolchain to compile
47 loadagent and compalstage (see ../target-utils) before you can successfully use
48 loadtools to operate on a target device. End-user oriented releases of
49 FreeCalypso host tools will include prebuilt loadagent and compalstage binaries
50 in the target-binaries subdirectory.
51
52 Installing
53 ==========
54
55 Just run 'make' and 'make install' as usual. If the target-binaries directory
56 is present, your installation will be complete and ready to use. If you are
57 building these pieces yourself from source, do a 'make' and 'make install' in
58 ../target-utils, after you have the ARM7 gcc toolchain installed and working.
59
60 Basic usage
61 ===========
62
63 The steps for bringing up fc-loadtool to operate on a target Calypso device are
64 as follows:
65
66 1. If you are using a USB serial adapter, or operating on a Pirelli phone that
67 has one built in, connect the USB side first so that the necessary
68 /dev/ttyUSB* device node appears.
69
70 2. Run fc-loadtool like this:
71
72 fc-loadtool $TARGETOPT /dev/ttyXXX
73
74 Change /dev/ttyXXX to the actual serial port you are using, and change
75 $TARGETOPT to:
76
77 Device Needed options
78 -----------------------------------
79 Mot C11x/123 -h compal
80 Mot C139/140 -h compal -c 1003
81 Mot C155/156 -h c155
82 Openmoko GTA02 -h gta02
83 Pirelli DP-L10 -h pirelli
84
85 3. Cause the target device to execute its boot path. Openmoko GTA0x and
86 Pirelli DP-L10 targets have the Calypso boot ROM enabled, and will interrupt
87 and divert their normal boot path when they "hear" the beacons which
88 fc-loadtool will be sending down the serial line. Compal phones have this
89 boot ROM disabled at the board level, but their standard firmware includes a
90 flash-resident bootloader that offers a different way of interrupting the
91 boot path and loading code over the serial line; fc-loadtool will be set up
92 to speak the latter protocol when run with the corresponding options from
93 the table above.
94
95 You will see messages showing fc-loadtool's progress with feeding first
96 compalstage (if needed), then loadagent (always needed) to the target device,
97 followed by some target-specific initialization done via loadagent commands.
98 If all of the above succeeds, you will land at a loadtool> prompt. Type
99 'help', and it will guide you from there. Alternatively, you can familiarize
100 yourself with loadtool commands and operations without actually running it by
101 reading the loadtool.help text file.
102
103 Command line options
104 ====================
105
106 The fc-loadtool command lines shown above will usually be sufficient. However,
107 here is the complete command line description for all 3 tools:
108
109 fc-iram [options] ttyport iramimage.srec
110 fc-xram [options] ttyport xramimage.srec [2ndprog]
111 fc-loadtool [options] ttyport
112
113 The available options are common for all 3 utilities, with a few noted
114 exceptions:
115
116 -a /path/to/loadagent
117
118 This option applies only to fc-loadtool and fc-xram. It specifies the
119 pathname at which the required loadagent.srec image should be sought,
120 overriding the compiled-in default.
121
122 -b baud
123
124 This option is common for all 3 utilities. It selects the baud rate
125 to be used when pushing the IRAM image to the Calypso boot ROM. In the
126 case of fc-iram, the selected baud rate will be in effect when the
127 loaded IRAM image is jumped to and fc-iram drops into the serial tty
128 pass-thru mode; in the case of fc-loadtool, it will be the initial baud
129 rate for communicating with loadagent, which can be switched later with
130 the baud command. The default is 115200 baud.
131
132 -B baud
133
134 This option is specific to fc-xram. It selects the baud rate to be
135 used when pushing the XRAM image to loadagent. If no -B option is
136 specified, fc-xram will communicate with loadagent at the same baud
137 rate that was used to load loadagent itself via the Calypso boot ROM
138 download protocol, i.e., the rate selected with -b, defaulting to
139 115200 baud if no -b option was given either. Neither -b nor -B
140 affects the baud rate that will be in effect when the loaded XRAM image
141 is jumped to and fc-xram drops into the serial tty pass-thru mode: that
142 baud rate independently defaults to 115200 baud and can only be changed
143 with the -r option.
144
145 -c <compalstage flavor>
146
147 This option is common for all 3 utilities. It directs the tools to
148 perform the Compal loading stage before proceeding with the Calypso
149 boot ROM serial protocol, and selects the "flavor" of compalstage to
150 use. As you can see in the source, compalstage is built in 3 different
151 versions, for different C1xx models which exhibit different quirks.
152
153 This option overrides the compal-stage setting given in the hardware
154 parameter file selected with -h or -H; the -c or -C option must be given
155 after -h or -H in order to take effect. -c none disables the Compal
156 stage and causes the tools to proceed directly to the Calypso boot ROM
157 phase, even on targets for which the hardware parameter file specifies
158 compal-stage.
159
160 -C /path/to/compalstage-binary
161
162 This option is just like -c, except that the given argument is used
163 directly as the compalstage binary file pathname (absolute or relative)
164 without checking or alteration.
165
166 -h hwtype
167
168 This option is common for all 3 utilities. It selects the specific
169 target device configuration to be used. More precisely, it constructs
170 a pathname of the form /usr/local/share/freecalypso/%s.config, where %s
171 is the argument given to this option, and uses that file as the hardware
172 parameter file.
173
174 The hardware configurations known to the present release of FreeCalypso
175 loadtools are listed in the "Basic usage" section above.
176
177 -H /path/to/hwparam-file
178
179 This option is just like -h, except that the given argument is used
180 directly as the hardware parameter file pathname (absolute or relative)
181 without alteration.
182
183 -i num
184
185 This option is common for all 3 utilities. It specifies the interval
186 in milliseconds at which the tool will send "please interrupt the boot
187 process" beacons out the serial port, hoping to catch the Calypso
188 internal boot ROM. The default is 13 ms.
189
190 -n
191
192 This option does anything only when loadtools have been compiled to run
193 on GTA0x AP (see the corresponding section below). If you've compiled
194 loadtools with the -DGTA0x_AP_BUILD option, it has an effect of making
195 each tool automatically toggle the modem power control upon startup,
196 removing the need for manual sequencing of the Calypso boot process.
197 This -n option suppresses that action, making the AP build behave like
198 the standard build in this regard.
199
200 -r baud (fc-loadtool)
201
202 This option is specific to fc-loadtool. It causes the tool to skip its
203 normal steps of feeding loadagent and possibly compalstage to the target
204 via special serial protocols, and instead assume that the target is
205 already running loadagent, communicating at the specified baud rate.
206 In other words, reattach to an already running loadagent. Use this
207 option if your fc-loadtool session has been terminated ungracefully and
208 you would like to reattach and resume, rather than forcibly reset the
209 target by yanking and reinserting the battery and restart from the
210 beginning.
211
212 -r baud (fc-xram)
213
214 This option is specific to fc-xram. It selects the serial line baud
215 rate which should be set just before the loaded XRAM image is jumped
216 to; the default is 115200 baud.
217
218 fc-xram 2nd program invokation
219 ==============================
220
221 The fc-xram utility can take two possible actions after it has loaded the
222 specified S-record image into XRAM:
223
224 * The default action, in the absence of additional command line arguments, is
225 to drop into a serial tty pass-thru mode, just like fc-iram.
226
227 * The alternative action is to invoke a 2nd program and pass the serial
228 communication channel to it. This 2nd program invokation facility is intended
229 primarily for passing the serial communication channel to rvinterf or rvtdump
230 from the FreeCalypso software suite, not for launching any arbitrary 3rd-party
231 programs from fc-xram.
232
233 The intended usage scenario is that one builds a version of the FreeCalypso GSM
234 firmware (or some subset thereof, such as an "in vivo" FFS editing agent) in the
235 ramImage configuration, fc-xram is used to load that ramImage into the target
236 device, and then the serial communication channel (RVTMUX) is immediately taken
237 over by rvinterf or rvtdump.
238
239 Openmoko GTA0x
240 ==============
241
242 All of the above instructions assume that you are running these loadtools on a
243 general-purpose host system such as a GNU/Linux PC or laptop, and will
244 potentially use them to operate on multiple Calypso targets of different kinds.
245 If instead you are building loadtools to run on the application processor of a
246 smartphone such as Openmoko GTA0x, then it makes no sense for that special build
247 of loadtools to support any target other than the specific modem in that
248 smartphone. Loadtools can be built with compalstage support excluded and with
249 GTA0x-specific modem power control included instead. This build will still
250 include a bunch of functions of no relevance to GTA0x, but oh well..
251
252 To build loadtools for the GTA0x AP, you'll need to make the following
253 modifications to the Makefile:
254
255 * Change the CC= line to point to the appropriate cross-compiler (which you'll
256 need to provide yourself);
257
258 * Change the CFLAGS= line: add the right options to target the ARM920T core in
259 the GTA0x AP (e.g., -march=armv4t -mtune=arm920t), and add -DGTA0x_AP_BUILD
260 to enable some code that makes sense only when running on the GTA0x AP.
261
262 * Change EXTRA_OBJ= from listing compalload.o to listing compaldummy.o and
263 gtapower.o instead.
264
265 See gta-ap-build.sed for an example.