FreeCalypso > hg > freecalypso-sw

comparison loadtools/README @ 424:1ec83a5fa8b3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
loadtools: README update
author Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
date Thu, 19 Jun 2014 05:50:43 +0000
parents 3275c8881cb7
children e61eacecd319
comparison
equal deleted inserted replaced
423:2e699aa67f03 424:1ec83a5fa8b3
1 You are looking at the source for the FreeCalypso loadtools package. You may 1 The set of host tools built in this directory consists of:
2 have downloaded it either as a separate package or as part of the larger
3 freecalypso-sw suite.
4 2
5 The tools in this package are written to run on some Unix/Linux machine 3 fc-loadtool The tool for operating on Calypso GSM devices at a low
6 (normally a PC/Linux desktop or laptop) that acts as a host for operating on 4 level. After "breaking" into the target GSM device in
7 Calypso target devices. All of these tools communicate with the Calypso target 5 its boot process and getting FreeCalypso loadagent
8 through a serial port; each tool begins its operation by sending special byte 6 running on the target (out of Calypso internal RAM, aka
9 sequences to this serial port which are designed to interrupt the Calypso 7 IRAM), loadtool presents an interactive command prompt
10 device boot process in the ROM bootloader. 8 with commands for peeking and poking registers and most
11 9 importantly, reading and writing any part of the
12 Three utilities are currently built as part of FreeCalypso loadtools: 10 device's non-volatile flash memory.
13 11
14 fc-iram & fc-xram These utilities are intended for FreeCalypso developers 12 fc-iram & fc-xram These utilities are intended for FreeCalypso developers
15 only. They load an S-record code image into IRAM or 13 only. They load an S-record code image into IRAM or
16 XRAM, respectively, induce a transfer of control to the 14 XRAM, respectively, induce a transfer of control to the
17 loaded code, and then drop into a serial line pass-thru 15 loaded code, and then drop into a serial line pass-thru
18 mode for the operator to interact with the thus loaded 16 mode for the operator to interact with the thus loaded
19 target code. 17 target code.
20 18
21 fc-loadtool This utility is intended for both developers and end 19 The currently supported target devices are the Compal family of basic
22 users. After establishing communication with the 20 dumbphones, the Openmoko GTA0x GSM modem and the Pirelli DP-L10 feature phone.
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 21
28 Loadagent 22 All tools in the FreeCalypso loadtools suite work by feeding pieces of code to
29 ========= 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:
30 27
31 Both fc-loadtool and fc-xram work by first feeding a FreeCalypso-developed 28 loadagent This is the "agent" code that runs on the target device when
32 program called loadagent to the Calypso ROM bootloader; all further operations 29 fc-loadtool is operating on it: loadtool carries out its
33 (loading code into XRAM or flash) are done via this loadagent. An S-record 30 operations by sending commands to loadagent. There is only one
34 image of the loadagent program is required for fc-loadtool and fc-xram to work. 31 version of loadagent for all currently supported Calypso
35 That program is in turn built with the ARM7 toolchain. 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.
36 37
37 If you are working with the full freecalypso-sw suite, you presumably already 38 compalstage For Compal phones only: a little piece of code that is fed to
38 have the proper ARM7 toolchain built and installed. To build loadagent, simply 39 the original fw's bootloader via the serial download protocol
39 run 'make' in the ../target-utils tree. 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.
40 43
41 If you have downloaded a separately-packaged version of FreeCalypso loadtools, 44 If you are working with a development snapshot of the freecalypso-sw source
42 the package should have a prebuilt loadagent.srec image included, sparing 45 tree, you will need to compile and install a GNU cross-compiler toolchain
43 non-developer users the nontrivial hurdle of having to build and install a 46 targeting ARM7 (see ../toolchain) and then use that toolchain to compile
44 special cross-compilation toolchain. The same loadagent binary is designed to 47 loadagent and compalstage (see ../target-utils) before you can successfully use
45 work on all supported Calypso targets. 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.
46 51
47 Building and installing loadtools 52 Installing
48 ================================= 53 ==========
49 54
50 Normally the machine on which you build and install fc-loadtools would be your 55 Just run 'make' and 'make install' as usual. If the target-binaries directory
51 PC/Linux desktop or laptop, the system you would use to program or otherwise 56 is present, your installation will be complete and ready to use. If you are
52 interact with Calypso phones by way of appropriate USB-to-phone cables. Just 57 building these pieces yourself from source, do a 'make' and 'make install' in
53 like loadagent, the host utilities you are going to build and install aren't 58 ../target-utils, after you have the ARM7 gcc toolchain installed and working.
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
59 However, if your intended target device is an Openmoko GTA02 (or GTA01) 60 Basic usage
60 smartphone, there is one additional complication: one cannot directly access 61 ===========
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 62
67 1. The recommended way for FreeCalypso developers is to get a special serial 63 The steps for bringing up fc-loadtool to operate on a target Calypso device are
68 cable (low voltage, as in 3.3V or lower - *NOT* RS-232 levels - please don't 64 as follows:
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 65
80 Having the headset jack do double duty as a programming port is actually a 66 1. If you are using a USB serial adapter, or operating on a Pirelli phone that
81 standard practice in the world of basic (non-smart) cellular phones, and 67 has one built in, connect the USB side first so that the necessary
82 furthermore, the pinout used by FIC on the GTA0x phones just happens to be 68 /dev/ttyUSB* device node appears.
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 69
88 2. If you are an end user who simply wishes to reflash a different GSM firmware 70 2. Run fc-loadtool like this:
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 71
96 Building loadtools for GTA0x AP 72 fc-loadtool $TARGETOPT /dev/ttyXXX
97 ===============================
98 73
99 If you've decided to build loadtools for the GTA0x AP, you'll need to make the 74 Change /dev/ttyXXX to the actual serial port you are using, and change
100 following modifications to the Makefile: 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 For other fc-loadtool options and fc-[ix]ram usage details, see the slightly
104 outdated README.old file. For newer options added since that file was written,
105 see the source code. I hope to write some real man pages eventually.
106
107 Openmoko GTA0x
108 ==============
109
110 All of the above instructions assume that you are running these loadtools on a
111 general-purpose host system such as a GNU/Linux PC or laptop, and will
112 potentially use them to operate on multiple Calypso targets of different kinds.
113 If instead you are building loadtools to run on the application processor of a
114 smartphone such as Openmoko GTA0x, then it makes no sense for that special build
115 of loadtools to support any target other than the specific modem in that
116 smartphone. Loadtools can be built with compalstage support excluded and with
117 GTA0x-specific modem power control included instead. This build will still
118 include a bunch of functions of no relevance to GTA0x, but oh well..
119
120 To build loadtools for the GTA0x AP, you'll need to make the following
121 modifications to the Makefile:
101 122
102 * Change the CC= line to point to the appropriate cross-compiler (which you'll 123 * Change the CC= line to point to the appropriate cross-compiler (which you'll
103 need to provide yourself); 124 need to provide yourself);
104 125
105 * Change the CFLAGS= line: add the right options to target the ARM920T core in 126 * 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 127 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. 128 to enable some code that makes sense only when running on the GTA0x AP.
108 129
109 * Change EXTRA_OBJ= to EXTRA_OBJ=gtapower.o, i.e., add gtapower.c (compiling 130 * Change EXTRA_OBJ= from listing compalload.o to listing compaldummy.o and
110 into gtapower.o) to the build. 131 gtapower.o instead.
111 132
112 See gta-ap-build.sed for an example. 133 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.