FreeCalypso > hg > freecalypso-tools

comparison loadtools/README.old @ 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
comparison
equal deleted inserted replaced
-1:000000000000 0:e7502631a0f9
1 You are looking at the source for the FreeCalypso loadtools package. You may
2 have downloaded it either as a separate package or as part of the larger
3 freecalypso-sw suite.
4
5 The tools in this package are written to run on some Unix/Linux machine
6 (normally a PC/Linux desktop or laptop) that acts as a host for operating on
7 Calypso target devices. All of these tools communicate with the Calypso target
8 through a serial port; each tool begins its operation by sending special byte
9 sequences to this serial port which are designed to interrupt the Calypso
10 device boot process in the ROM bootloader.
11
12 Three utilities are currently built as part of FreeCalypso loadtools:
13
14 fc-iram & fc-xram These utilities are intended for FreeCalypso developers
15 only. They load an S-record code image into IRAM or
16 XRAM, respectively, induce a transfer of control to the
17 loaded code, and then drop into a serial line pass-thru
18 mode for the operator to interact with the thus loaded
19 target code.
20
21 fc-loadtool This utility is intended for both developers and end
22 users. After establishing communication with the
23 target, fc-loadtool drops into interactive operation.
24 Once at the loadtool> prompt, you can peek and poke
25 registers, and most importantly, dump (read) and load
26 (program) the flash memory of the target device.
27
28 Loadagent
29 =========
30
31 Both fc-loadtool and fc-xram work by first feeding a FreeCalypso-developed
32 program called loadagent to the Calypso ROM bootloader; all further operations
33 (loading code into XRAM or flash) are done via this loadagent. An S-record
34 image of the loadagent program is required for fc-loadtool and fc-xram to work.
35 That program is in turn built with the ARM7 toolchain.
36
37 If you are working with the full freecalypso-sw suite, you presumably already
38 have the proper ARM7 toolchain built and installed. To build loadagent, simply
39 run 'make' in the ../target-utils tree.
40
41 If you have downloaded a separately-packaged version of FreeCalypso loadtools,
42 the package should have a prebuilt loadagent.srec image included, sparing
43 non-developer users the nontrivial hurdle of having to build and install a
44 special cross-compilation toolchain. The same loadagent binary is designed to
45 work on all supported Calypso targets.
46
47 Building and installing loadtools
48 =================================
49
50 Normally the machine on which you build and install fc-loadtools would be your
51 PC/Linux desktop or laptop, the system you would use to program or otherwise
52 interact with Calypso phones by way of appropriate USB-to-phone cables. Just
53 like loadagent, the host utilities you are going to build and install aren't
54 specific to a particular target device; instead you will select the target
55 device at run time via a command line option. Hence you can build and install
56 the host utilities (usual 'make' and 'make install') without limiting your
57 setup to just one target phone type.
58
59 However, if your intended target device is an Openmoko GTA02 (or GTA01)
60 smartphone, there is one additional complication: one cannot directly access
61 the Calypso part of these phones from the outside without going through the
62 phone's application processor first. If you would like to use fc-loadtool to
63 read or write the GSM flash memory of your GTA0x (load a different firmware
64 image, dump the flash file system for backup or examination, restore a previous
65 backup etc), there are two ways to do it:
66
67 1. The recommended way for FreeCalypso developers is to get a special serial
68 cable (low voltage, as in 3.3V or lower - *NOT* RS-232 levels - please don't
69 fry your precious phone!) that would plug into the 2.5mm jack on the left
70 side of the phone that is normally intended for a wired headset. This way
71 you can use your regular build of fc-loadtool (and fc-iram & fc-xram) on
72 your PC/Linux (or other) development host, no need to build anything for
73 GTA0x AP, and all communication happens directly between your development
74 host and the Calypso part of your target phone - not going through the AP
75 at all. You still need working software on the GTA0x AP to do battery
76 management, to power the Calypso block on and off, and to enable the headset
77 jack "download" path, but it is much less burdensome than having to do the
78 actual FreeCalypso work from the AP.
79
80 Having the headset jack do double duty as a programming port is actually a
81 standard practice in the world of basic (non-smart) cellular phones, and
82 furthermore, the pinout used by FIC on the GTA0x phones just happens to be
83 exactly the same as that used by Compal/Motorola - hence the same headset jack
84 serial cables that are used by OsmocomBB with the latter phones (the famous
85 "T191 unlock cable") will also work for connecting from an external host
86 directly to the Calypso part of GTA0x phones.
87
88 2. If you are an end user who simply wishes to reflash a different GSM firmware
89 image, it can be done from inside the phone (from the AP) without having to
90 acquire special hardware (as in the cable described above). However, the
91 trade-off is that in return for saving on the special hardware, you have to
92 do more work on the software. You will have to use a cross-compiler
93 targeting the ARM/Linux AP environment (*not* the ARM7 cross-compiler used
94 for the GSM firmware itself!) to build fc-loadtools to run on the GTA0x AP.
95
96 Building loadtools for GTA0x AP
97 ===============================
98
99 If you've decided to build loadtools for the GTA0x AP, you'll need to make the
100 following modifications to the Makefile:
101
102 * Change the CC= line to point to the appropriate cross-compiler (which you'll
103 need to provide yourself);
104
105 * Change the CFLAGS= line: add the right options to target the ARM920T core in
106 the GTA0x AP (e.g., -march=armv4t -mtune=arm920t), and add -DGTA0x_AP_BUILD
107 to enable some code that makes sense only when running on the GTA0x AP.
108
109 * Change EXTRA_OBJ= to EXTRA_OBJ=gtapower.o, i.e., add gtapower.c (compiling
110 into gtapower.o) to the build.
111
112 See gta-ap-build.sed for an example.
113
114 Running fc-loadtool
115 ===================
116
117 Once you've got loadtools built and installed, you can run fc-loadtool
118 as follows:
119
120 To operate on a Pirelli DP-L10 that appears as /dev/ttyUSB0:
121
122 fc-loadtool -h pirelli /dev/ttyUSB0
123
124 The usb2serial chip inside the phone is bus-powered and will be visible as
125 /dev/ttyUSBx whether the phone battery is present or not. There are two ways
126 to break into the bootloader:
127
128 1. Run the fc-loadtool command given above with the USB cable connected, but no
129 battery present. Once loadtool says "Sending beacons to <port>", insert the
130 battery.
131
132 2. Connect the USB cable to a powered-on phone running its original factory
133 firmware. (If the phone was off, it will power up and boot in the "charging
134 only" mode - it is not possible for a Calypso/Iota phone to be completely
135 off when both the battery and the charging voltage are present.) Run
136 fc-loadtool as above - it will start sending its beacons, which will be
137 ignored by the running fw. Then execute the "power off" operation from the
138 UI (unlock the keypad, then press and hold the red button). The presence of
139 USB VBUS (used as the charging power source on this phone) will turn the
140 power-off into a reboot, and you'll break into the bootloader.
141
142 To operate on the Calypso block of a GTA02, accessing it from an external
143 PC/Linux host via a USB-to-headset-jack serial cable that appears as
144 /dev/ttyUSB0:
145
146 fc-loadtool -h gta02 /dev/ttyUSB0
147
148 Run the above command first, then power on the GSM modem from the AP - or power
149 it off, then on if it was on already. The "download" path needs to be enabled
150 (controlled from the AP) and fc-loadtool needs to be running on the external
151 host when the modem is powered on.
152
153 To operate on the Calypso block of a GTA02, running fc-loadtool from inside the
154 phone, i.e., from the AP of the same GTA02:
155
156 fc-loadtool -h gta02 /dev/ttySAC0
157
158 In this last scenario the specially built version of fc-loadtool running on the
159 AP takes care of manipulating the modem power to induce entry into the
160 bootloader, thus no extra manual steps are needed.
161
162 See loadtool.help for a detailed description of the functionality and commands
163 that are available once loadtool is running and communicating with loadagent on
164 the target device.
165
166 Command line options
167 ====================
168
169 The fc-loadtool command lines shown above will usually be sufficient. However,
170 here is the complete command line description for all 3 tools:
171
172 fc-iram [options] ttyport iramimage.srec
173 fc-xram [options] ttyport xramimage.srec [2ndprog]
174 fc-loadtool [options] ttyport
175
176 The available options are common for all 3 utilities, with a few noted
177 exceptions:
178
179 -a /path/to/loadagent
180
181 This option applies only to fc-loadtool and fc-xram. It specifies the
182 pathname at which the required loadagent.srec image should be sought,
183 overriding the compiled-in default.
184
185 -b baud
186
187 This option is common for all 3 utilities. It selects the baud rate
188 to be used when pushing the IRAM image to the Calypso boot ROM. In the
189 case of fc-iram, the selected baud rate will be in effect when the
190 loaded IRAM image is jumped to and fc-iram drops into the serial tty
191 pass-thru mode; in the case of fc-loadtool, it will be the initial baud
192 rate for communicating with loadagent, which can be switched later with
193 the baud command. The default is 115200 baud.
194
195 -B baud
196
197 This option is specific to fc-xram. It selects the baud rate to be
198 used when pushing the XRAM image to loadagent. If no -B option is
199 specified, fc-xram will communicate with loadagent at the same baud
200 rate that was used to load loadagent itself via the Calypso boot ROM
201 download protocol, i.e., the rate selected with -b, defaulting to
202 115200 baud if no -b option was given either. Neither -b nor -B
203 affects the baud rate that will be in effect when the loaded XRAM image
204 is jumped to and fc-xram drops into the serial tty pass-thru mode: that
205 baud rate independently defaults to 115200 baud and can only be changed
206 with the -r option.
207
208 -h hwtype
209
210 This option is common for all 3 utilities. It selects the specific
211 target device configuration to be used. More precisely, it constructs
212 a pathname of the form /usr/local/share/freecalypso/%s.config, where %s
213 is the argument given to this option, and uses that file as the hardware
214 parameters file.
215
216 The hardware configurations known to the present release of FreeCalypso
217 loadtools are gta02 and pirelli.
218
219 -H /path/to/hwparam-file
220
221 This option is just like -h, except that the given argument is used
222 directly as the hardware parameter file pathname (absolute or relative)
223 without alteration.
224
225 -i num
226
227 This option is common for all 3 utilities. It specifies the interval
228 in milliseconds at which the tool will send "please interrupt the boot
229 process" beacons out the serial port, hoping to catch the Calypso
230 internal boot ROM. The default is 13 ms.
231
232 -n
233
234 This option does anything only when loadtools have been compiled to run
235 on GTA0x AP. If you've compiled loadtools with the -DGTA0x_AP_BUILD
236 option, it has an effect of making each tool automatically toggle the
237 modem power control upon startup, removing the need for manual
238 sequencing of the Calypso boot process. This -n option suppresses that
239 action, making the AP build behave like the standard build in this
240 regard.
241
242 -r baud
243
244 This option is specific to fc-xram. It selects the serial line baud
245 rate which should be set just before the loaded XRAM image is jumped
246 to; the default is 115200 baud.
247
248 fc-xram 2nd program invokation
249 ==============================
250
251 The fc-xram utility can take two possible actions after it has loaded the
252 specified S-record image into XRAM:
253
254 * The default action, in the absence of additional command line arguments, is
255 to drop into a serial tty pass-thru mode, just like fc-iram.
256
257 * The alternative action is to invoke a 2nd program and pass the serial
258 communication channel to it. This 2nd program invokation facility is intended
259 primarily for passing the serial communication channel to rvinterf or rvtdump
260 from the FreeCalypso software suite, not for launching any arbitrary 3rd-party
261 programs from fc-xram.
262
263 The intended usage scenario is that one builds a version of the FreeCalypso GSM
264 firmware (or some subset thereof, such as an "in vivo" FFS editing agent) in the
265 ramImage configuration, fc-xram is used to load that ramImage into the target
266 device, and then the serial communication channel (RVTMUX) is immediately taken
267 over by rvinterf or rvtdump.
268
269 More detailed usage instructions will be written when the rvinterf tools reach
270 a point of being usable by more than just the original developer; until then,
271 read the source code.