FreeCalypso > hg > freecalypso-sw

comparison loadtools/README @ 107:8b44e806b6e1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
loadtools/README: documentation for loadtools should now be complete
author Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
date Fri, 13 Sep 2013 16:47:09 +0000
parents a2e793f6b8c4
children 3275c8881cb7
comparison
equal deleted inserted replaced
106:ae4921a3aa33 107:8b44e806b6e1
24 Once at the loadtool> prompt, you can peek and poke 24 Once at the loadtool> prompt, you can peek and poke
25 registers, and most importantly, dump (read) and load 25 registers, and most importantly, dump (read) and load
26 (program) the flash memory of the target device. 26 (program) the flash memory of the target device.
27 27
28 Loadagent 28 Loadagent
29 =========
29 30
30 Both fc-loadtool and fc-xram work by first feeding a FreeCalypso-developed 31 Both fc-loadtool and fc-xram work by first feeding a FreeCalypso-developed
31 program called loadagent to the Calypso ROM bootloader; all further operations 32 program called loadagent to the Calypso ROM bootloader; all further operations
32 (loading code into XRAM or flash) are done via this loadagent. An S-record 33 (loading code into XRAM or flash) are done via this loadagent. An S-record
33 image of the loadagent program is required for fc-loadtool and fc-xram to work. 34 image of the loadagent program is required for fc-loadtool and fc-xram to work.
42 non-developer users the nontrivial hurdle of having to build and install a 43 non-developer users the nontrivial hurdle of having to build and install a
43 special cross-compilation toolchain. The same loadagent binary is designed to 44 special cross-compilation toolchain. The same loadagent binary is designed to
44 work on all supported Calypso targets. 45 work on all supported Calypso targets.
45 46
46 Building and installing loadtools 47 Building and installing loadtools
48 =================================
47 49
48 Normally the machine on which you build and install fc-loadtools would be your 50 Normally the machine on which you build and install fc-loadtools would be your
49 PC/Linux desktop or laptop, the system you would use to program or otherwise 51 PC/Linux desktop or laptop, the system you would use to program or otherwise
50 interact with Calypso phones by way of appropriate USB-to-phone cables. Just 52 interact with Calypso phones by way of appropriate USB-to-phone cables. Just
51 like loadagent, the host utilities you are going to build and install aren't 53 like loadagent, the host utilities you are going to build and install aren't
73 at all. You still need working software on the GTA0x AP to do battery 75 at all. You still need working software on the GTA0x AP to do battery
74 management, to power the Calypso block on and off, and to enable the headset 76 management, to power the Calypso block on and off, and to enable the headset
75 jack "download" path, but it is much less burdensome than having to do the 77 jack "download" path, but it is much less burdensome than having to do the
76 actual FreeCalypso work from the AP. 78 actual FreeCalypso work from the AP.
77 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
78 2. If you are an end user who simply wishes to reflash a different GSM firmware 88 2. If you are an end user who simply wishes to reflash a different GSM firmware
79 image, it can be done from inside the phone (from the AP) without having to 89 image, it can be done from inside the phone (from the AP) without having to
80 acquire special hardware (as in the cable described above). However, the 90 acquire special hardware (as in the cable described above). However, the
81 trade-off is that in return for saving on the special hardware, you have to 91 trade-off is that in return for saving on the special hardware, you have to
82 do more work on the software. You will have to use a cross-compiler 92 do more work on the software. You will have to use a cross-compiler
83 targeting the ARM/Linux AP environment (*not* the ARM7 cross-compiler used 93 targeting the ARM/Linux AP environment (*not* the ARM7 cross-compiler used
84 for the GSM firmware itself!) to build fc-loadtools to run on the GTA0x AP. 94 for the GSM firmware itself!) to build fc-loadtools to run on the GTA0x AP.
85 95
86 Building loadtools for GTA0x AP 96 Building loadtools for GTA0x AP
97 ===============================
87 98
88 If you've decided to build loadtools for the GTA0x AP, you'll need to make the 99 If you've decided to build loadtools for the GTA0x AP, you'll need to make the
89 following modifications to the Makefile: 100 following modifications to the Makefile:
90 101
91 * Change the CC= line to point to the appropriate cross-compiler (which you'll 102 * Change the CC= line to point to the appropriate cross-compiler (which you'll
99 into gtapower.o) to the build. 110 into gtapower.o) to the build.
100 111
101 See gta-ap-build.sed for an example. 112 See gta-ap-build.sed for an example.
102 113
103 Running fc-loadtool 114 Running fc-loadtool
115 ===================
104 116
105 Once you've got loadtools built and installed, you can run fc-loadtool 117 Once you've got loadtools built and installed, you can run fc-loadtool
106 as follows: 118 as follows:
107 119
108 To operate on a Pirelli DP-L10 that appears as /dev/ttyUSB0: 120 To operate on a Pirelli DP-L10 that appears as /dev/ttyUSB0:
109 121
110 fc-loadtool -h pirelli /dev/ttyUSB0 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.
111 141
112 To operate on the Calypso block of a GTA02, accessing it from an external 142 To operate on the Calypso block of a GTA02, accessing it from an external
113 PC/Linux host via a USB-to-headset-jack serial cable that appears as 143 PC/Linux host via a USB-to-headset-jack serial cable that appears as
114 /dev/ttyUSB0: 144 /dev/ttyUSB0:
115 145
116 fc-loadtool -h gta02 /dev/ttyUSB0 146 fc-loadtool -h gta02 /dev/ttyUSB0
117 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
118 To operate on the Calypso block of a GTA02, running fc-loadtool from inside the 153 To operate on the Calypso block of a GTA02, running fc-loadtool from inside the
119 phone, i.e., from the AP of the same GTA02: 154 phone, i.e., from the AP of the same GTA02:
120 155
121 fc-loadtool -h gta02 /dev/ttySAC0 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 [runbaud]
174 fc-loadtool [options] ttyport
175
176 The last optional argument to fc-xram selects the serial line baud rate which
177 should be set just before the loaded XRAM image is jumped to; the default is
178 115200 baud.
179
180 The available options are common for all 3 utilities, with a few noted
181 exceptions:
182
183 -a /path/to/loadagent
184
185 This option applies only to fc-loadtool and fc-xram. It specifies the
186 pathname at which the required loadagent.srec image should be sought,
187 overriding the compiled-in default.
188
189 -b baud
190
191 This option is common for all 3 utilities. It selects the baud rate
192 to be used when pushing the IRAM image to the Calypso boot ROM. In the
193 case of fc-iram, the selected baud rate will be in effect when the
194 loaded IRAM image is jumped to and fc-iram drops into the serial tty
195 pass-thru mode; in the case of fc-loadtool, it will be the initial baud
196 rate for communicating with loadagent, which can be switched later with
197 the baud command. The default is 115200 baud.
198
199 -B baud
200
201 This option is specific to fc-xram. It selects the baud rate to be
202 used when pushing the XRAM image to loadagent. If no -B option is
203 specified, fc-xram will communicate with loadagent at the same baud
204 rate that was used to load loadagent itself via the Calypso boot ROM
205 download protocol, i.e., the rate selected with -b, defaulting to
206 115200 baud if no -b option was given either. Neither -b nor -B
207 affects the baud rate that will be in effect when the loaded XRAM image
208 is jumped to and fc-xram drops into the serial tty pass-thru mode: that
209 baud rate independently defaults to 115200 baud and can only be changed
210 by the last optional argument on the fc-xram command line.
211
212 -h hwtype
213
214 This option is common for all 3 utilities. It selects the specific
215 target device configuration to be used. More precisely, it constructs
216 a pathname of the form /usr/local/share/freecalypso/%s.config, where %s
217 is the argument given to this option, and uses that file as the hardware
218 parameters file.
219
220 The hardware configurations knows to the present release of FreeCalypso
221 loadtools are gta02 and pirelli.
222
223 -H /path/to/hwparam-file
224
225 This option is just like -h, except that the given argument is used
226 directly as the hardware parameter file pathname (absolute or relative)
227 without alteration.
228
229 -i num
230
231 This option is common for all 3 utilities. It specifies the interval
232 in milliseconds at which the tool will send "please interrupt the boot
233 process" beacons out the serial port, hoping to catch the Calypso
234 internal boot ROM. The default is 13 ms.
235
236 -n
237
238 This option does anything only when loadtools have been compiled to run
239 on GTA0x AP. If you've compiled loadtools with the -DGTA0x_AP_BUILD
240 option, it has an effect of making each tool automatically toggle the
241 modem power control upon startup, removing the need for manual
242 sequencing of the Calypso boot process. This -n option suppresses that
243 action, making the AP build behave like the standard build in this
244 regard.