FreeCalypso > hg > fc-magnetite

comparison doc/C1xx-Howto @ 383:43dbedde9d80

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/C1xx-Howto written
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 14 Jan 2018 20:45:51 +0000
parents
children 6530fc550836
comparison
equal deleted inserted replaced
382:7bdd370f6f59 383:43dbedde9d80
1 Running FreeCalypso firmware on Motorola C1xx phones
2 ====================================================
3
4 Before we begin, it needs to be noted that running FreeCalypso fw on a C1xx
5 phone is very much akin to xenotransplantation: Mot C1xx hardware is an alien
6 to our FreeCalypso family (our native hw targets are those made by TI, Openmoko
7 and us, not Motorola or Compal), and our non-Compal-based, non-Mot-based
8 FreeCalypso fw is equally alien to the C1xx phones. The xenotransplantation
9 procedure of converting a C1xx phone to FreeCalypso is highly unnatural, and
10 involves a large number of cumbersome manual steps - you've been warned.
11
12 Preparing the host system
13 =========================
14
15 Firmware flashing on Mot C1xx phones is accomplished through the headset jack
16 via a special cable. There is no need to disassemble the phone in any way or
17 to do any soldering or other hardware surgery, but you will need a host system
18 to run the multitude of special software tools that are involved in the
19 procedure. You will need to begin by installing FreeCalypso host tools, and
20 the current version of the FC-C1xx xenotransplantation procedure (the additions
21 from the previous version are RF calibration data migration and battery
22 charging configuration) requires the use of some new features that (as of this
23 writing) have not yet made it in a packaged release of FC host tools - hence
24 you will need to install and use the current "bleeding edge" development
25 version from:
26
27 https://bitbucket.org/falconian/freecalypso-tools
28
29 You will also need the battery charging configuration files:
30
31 https://bitbucket.org/falconian/fc-battery-conf
32
33 Run 'make install' in the fc-battery-conf tree to add the battery charging
34 configuration files to your FC host tools installation under /opt/freecalypso.
35
36 Flash backup and data gathering
37 ===============================
38
39 Before you begin the actual conversion of your C1xx phone to FreeCalypso, you
40 will need to gather the following pieces of information:
41
42 * The phone's IMEI - we don't know how to extract it out of Mot/Compal's non-TI
43 flash data structures, so you will have to reset it manually after the
44 firmware change. Of course you can set your "new" FreeCalypso IMEI to
45 whatever you feel like, but if you wish to keep the original factory-assigned
46 one, you will need to note it down manually, either from the sticker inside
47 the battery compartment (*very* hard to read!) or by booting the phone up
48 with its original fw prior to the conversion, entering *#06# and reading it
49 from the display.
50
51 * Your specific phone's factory RF calibration values: you will need to make a
52 dump of your phone's flash memory (also serves as a backup, always a good
53 thing to have) with fc-loadtool and extract the numbers of interest with our
54 c1xx-calextr utility, which is part of the new FC host tools.
55
56 * You need to know whether your phone has 900+1800 MHz or 850+1900 MHz bands -
57 you will need to communicate this information to the new fw after the
58 conversion. To the best of our knowledge, all C11x/12x and C140 phones have
59 900+1800 MHz bands, but C139 phones have been made in both versions. On the
60 phones that have passed through our hands so far, the first two digits of the
61 IMEI have been 35 on 900+1800 MHz phones and 01 on 850+1900 MHz ones.
62
63 * You need to know whether your phone has 2 MiB or 4 MiB flash. To the best of
64 our knowledge, all C139/140 phones have 4 MiB flash, but C11x have been seen
65 with both 2 MiB and 4 MiB flashes. The flash memory size will be autodetected
66 by fc-loadtool as part of making the flash dump.
67
68 The Mother's method for keeping track of these per-phone bits of information is
69 to create a separate directory for each phone with the IMEI as the directory
70 name; the flash dump and the RF calibration bits extracted from it will then
71 reside in that directory, while the IMEI is in the name of the directory itself.
72
73 Once you have created your per-phone directory and cd'ed into it, you are ready
74 to run fc-loadtool to capture the flash dump. The phone needs to be off, but
75 the battery needs to be present and have some charge in it; with the phone off,
76 connect the serial cable between your host computer and the phone's headset
77 jack, and run fc-loadtool as follows:
78
79 fc-loadtool -h compal -c 1004 /dev/ttyXXX
80
81 Change /dev/ttyXXX to the serial or USB-serial device corresponding to your
82 serial cable. The -c 1004 option (adds a little inefficiency which is required
83 for C139/140) phones can be omitted if your phone is C11x/12x, but it is also
84 harmless to always add it. With the serial cable connected, the phone in the
85 powered-off state and the fc-loadtool process running and waiting for the phone,
86 press the red power button on the phone - a momentary press is sufficient and
87 recommended.
88
89 Once the phone boots the loadagent code fed to it serially by fc-loadtool and
90 you land at the loadtool> prompt, issue the following command:
91
92 flash dump2bin flashdump.bin
93
94 Given this command, fc-loadtool will autodetect whether your phone has 2 MiB or
95 4 MiB flash, then make a dump of the complete content of this flash memory and
96 save it in a file named flashdump.bin in the current directory. When this
97 operation completes, exit the loadtool session with the exit command - it will
98 also cleanly power the phone off.
99
100 The next step is to extract the RF calibration values. Run a command of the
101 following form:
102
103 c1xx-calextr -b rfbin flashdump.bin <offset>
104
105 Change <offset> to 0x1FC000 if your phone has 2 MiB flash (the size of
106 flashdump.bin is 2097152 bytes) or 0x3FC000 if it has 4 MiB flash (the size of
107 flashdump.bin is 4194304 bytes). The stdout scribbles from c1xx-calextr will
108 indicate which per-band calibration records it finds (from which you can tell
109 if the phone has 900+1800 MHz or 850+1900 MHz bands if you didn't have this
110 knowledge already), and a directory named rfbin will be created, containing the
111 correct subtree of directories and files which will need to be uploaded into
112 the new FreeCalypso flash file system (FFS) under /gsm/rf after the firmware
113 change.
114
115 Selecting and building the desired firmware config
116 ==================================================
117
118 There is only one FC Magnetite firmware configuration for C11x/12x phones, but
119 for the better C139/140 phones there are 3 to choose from:
120
121 hybrid-vpm This config is available for both C11x/12x and C139/140
122 subfamilies, although the actual fw images are different
123 between the two. In this configuration the converted phone
124 acts not as an end user phone, but as a voice pseudo-modem that
125 needs to be controlled by a host computer via a serial cable to
126 do anything interesting. See the Voice-pseudo-modem article
127 for more information.
128
129 l1reconst-chg This config is available only for the C139/140 subfamily - its
130 XRAM usage won't fit into C11x's 256 KiB even if your phone has
131 4 MiB flash. This config is also a voice pseudo-modem just like
132 hybrid-vpm, but it uses the older TCS2 version of the G23M PS
133 and ACI firmware components, which may be needed for debugging.
134
135 2092 This config is not a voice pseudo-modem, but includes the demo
136 or prototype or proof-of-concept UI code we've got with our
137 version of TI's TCS211 fw. However, please be warned that this
138 proof-of-concept UI is nowhere close to being practically
139 usable - see the Handset-goal article for more info. Like
140 l1reconst-chg, this config is only available for the C139/140
141 subfamily, not for C11x/12x: not only does it has the same
142 issue of needing large flash and XRAM, but also we have the LCD
143 driver implemented only for the SPI/MicroWire LCD on the C139,
144 not for the I2C one on C11x.
145
146 Thus we have a total of 4 possible build configurations, one for the C11x
147 target and 3 for the C139:
148
149 ./configure.sh c11x hybrid-vpm
150 ./configure.sh c139 hybrid-vpm
151 ./configure.sh c139 l1reconst-chg
152 ./configure.sh c139 2092
153
154 See the Compiling article for more information on how to compile your own
155 firmware image in one of the above configurations.
156
157 If this is your first time converting a given C1xx phone from its original
158 firmware to FreeCalypso (as opposed to updating from an earlier FC firmware
159 version), you will also need the compal-flash-boot-for-fc.bin bootloader image
160 in addition to the main fw image you just built:
161
162 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/compal-flash-boot-for-fc.bin
163
164 Mot C1xx phones are brickable - because the Calypso boot ROM is disabled by PCB
165 wiring, the ability to reflash a phone with new firmware critically depends on
166 there being a particular kind of boot code in flash sector 0 at all times - a
167 particular kind of boot code that allows the boot process to be interrupted and
168 diverted to external code loaded via the headset jack serial port.
169
170 The FreeCalypso family of projects has adopted one specific version of the
171 flash sector 0 boot code (produced by applying a binary patch to one of
172 Compal/Motorola's original versions) for use with all of our firmwares for
173 these phones. We use the same FC-C1xx bootloader on both C11x/12x and C139/140
174 phones: the official bootloader versions are different between the two (and
175 moreover, each particular official fw version comes with its own bootloader
176 version), but the simpler bootloader version which we took from one particular
177 C11x fw version works perfectly well on the C139 as well, hence we've adopted
178 it for all combinations.
179
180 Once you have our compal-flash-boot-for-fc.bin image flashed in sector 0, you
181 can then flash whichever FC firmware image you like at offset 0x10000 without
182 having to touch the dangerous boot sector.
183
184 Converting the phone to FreeCalypso fw
185 ======================================
186
187 If you are starting with an unhacked C1xx phone running one of the official
188 firmware versions, the procedure for flashing and bringing up FreeCalypso for
189 the first time is as follows - *after* you have done all of the preparatory
190 steps described in the preceding sections:
191
192 * Have your phone's battery fully charged - although you will regain the
193 ability to charge it with FreeCalypso fw when the conversion is fully
194 complete (not just the flashing part, but also the subsequent FFS
195 initialization), your phone will not have this charging ability while you are
196 in the middle of the xenotransplantation procedure.
197
198 * Get in with fc-loadtool just like you did when you made the dump of your
199 phone's flash memory for backup and RF calibration data extraction.
200
201 * Once you are in with fc-loadtool, i.e., at the loadtool> prompt, reflash the
202 boot sector with the FreeCalypso version:
203
204 loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
205
206 * To flash whichever FreeCalypso firmware image you would like to play with,
207 execute the flashing script which the fw build system produced along with the
208 actual image:
209
210 loadtool> exec flash-script
211
212 * Erase the flash sectors to be used for the FFS (flash file system) by
213 FreeCalypso firmwares; the specific command depends on whether your phone has
214 2 MiB or 4 MiB flash. On 2 MiB flash phones:
215
216 loadtool> flash erase 0x1C0000 0x30000
217
218 Or on 4 MiB flash phones:
219
220 loadtool> flash erase 0x3C0000 0x30000
221
222 * Exiting fc-loadtool cleanly will cause it to power off the phone:
223
224 loadtool> exit
225
226 Reflashing between different FreeCalypso firmwares
227 ==================================================
228
229 By the conventions established in the FreeCalypso family of projects, all of
230 our firmwares for C11x and C139 targets have the following in common:
231
232 * They all stay out of the boot sector and expect to receive control from the
233 boot code in the same manner (boot entry point at 0x10058, exception vectors
234 at 0x10000), thus there is no need to reflash the dangerous boot sector when
235 going from one FC firmware to another.
236
237 * They all use the same aftermarket FFS configuration of 3 sectors of 64 KiB
238 each (64x3) at 0x3C0000 on 4 MiB flash phones, or at 0x1C0000 on 2 MiB flash
239 phones. This FFS location is deliberately different from the one used by
240 Mot/Compal's firmwares, eliminating the possibility of one fw trying to use
241 the FFS created by the other, and by putting our FFS toward the end of the
242 flash we maximize the amount of flash space available for our firmware code
243 images. But even though we don't share our FFS with Mot/Compal's official
244 firmwares, we do share the same FFS between all of FreeCalypso firmware
245 projects - thus once you have initialized your FFS (see below) with one FC
246 firmware version, it will work with the others as well.
247
248 If you need to reflash your C1xx phone from one FC firmware version to another,
249 simply get in with fc-loadtool -h compal (no more need for the inefficient
250 -c 1003 or -c 1004 options or for tfc139) and reflash just the fw image part:
251
252 loadtool> exec flash-script
253
254 First boot of the firmware
255 ==========================
256
257 Connect the serial cable, but instead of running fc-loadtool, run rvinterf.
258 Press the red power button on the phone briefly just like you would for
259 fc-loadtool entry. Because there is no fc-loadtool running on the host end of
260 the serial cable, the boot path will *not* be diverted in the bootloader, and
261 the main fw image will run - and this time it will be the FreeCalypso firmware
262 you have compiled and flashed. If the fw you have flashed is the UI demo
263 configuration, the phone must have *NO* SIM in it the first time you boot it.
264 UI-enabled fw configurations automatically bring up the GSM radio and try to
265 connect to the default network on boot if there is a SIM present, and you don't
266 want your firmware trying to connect to a real live GSM network when you haven't
267 initialized your FFS yet. If the fw you have flashed is one of the AT-command-
268 controlled pseudo-modem configurations, then you don't need to worry if the SIM
269 is there or not on your first boot - just don't command it to connect to a
270 network until you have initialized the FFS.
271
272 If you have flashed a non-UI firmware version, the phone's LCD will remain dark
273 as there is no LCD driver code in this firmware, but you will see trace output
274 in the rvinterf window, telling you that the fw is running.
275
276 Before you do anything else, you will need to run fc-fsio and initialize the
277 aftermarket FFS for our firmware:
278
279 fsio> format /
280 fsio> mk-std-dirs
281 fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
282 fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
283 or
284 fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)
285
286 then additionally:
287
288 fsio> upload-subtree rfbin /gsm/rf
289 fsio> write-charging-config /opt/freecalypso/charging/c1xx/standard
290
291 The last two commands are new with the 2018-01 revision of the FC-to-C1xx
292 xenotransplantation procedure. The upload-subtree command uploads the RF
293 calibration values which you had extracted earlier with c1xx-calextr (the
294 instructions assume that you are running from the same directory where the
295 rfbin directory subtree had been created earlier), and this step is necessary
296 in order for your phone to continue to transmit at the correct power levels
297 after the conversion. The write-charging-config command uploads the
298 configuration settings for the FCHG battery charging driver, without which it
299 cannot charge the battery; you must have the charging config files from the
300 fc-battery-conf tree installed under /opt/freecalypso in order for this command
301 to work as given.
302
303 It needs to be noted that the battery charging config settings uploaded with
304 fc-fsio write-charging-config take effect only on the next boot cycle of the
305 firmware, i.e., until the next reboot after the write-charging-config operation,
306 the firmware won't charge the battery even if there is a charging power source
307 plugged in.
308
309 After you've initialized your FFS as above, you should exit fc-fsio, and your
310 next steps will depend on which fw configuration you are playing with. If it's
311 the sans-UI pseudo-modem configuration, run fc-shell and try some AT commands:
312
313 AT+CMEE=2 -- enable verbose error responses
314 AT+CFUN=1 -- enable radio and SIM interfaces
315 AT+COPS=0 -- register to the default GSM network
316
317 When you are done, you can power the phone off by sending a 'poweroff' command
318 through fc-shell, or you can kill rvinterf and wait for the firmware to power
319 off by the keepalive timeout after some 60 to 80 s.
320
321 If you are playing with the UI demo firmware, after you have initialized your
322 FFS, you can power the phone off with the power button, insert a SIM, power it
323 back on and play with the primitive UI.
324
325 Updating from previous versions
326 ===============================
327
328 If you had previously initialized your aftermarket FFS using an earlier version
329 of these instructions, before we added the RF calibration and charging config
330 upload steps, you need to add these bits to your FFS. Update to the latest FC
331 host tools, extract the factory RF calibration values from a dump of your
332 phone's flash with c1xx-calextr, add the battery charging config files to your
333 /opt/freecalypso installation, boot the phone with rvinterf, get in with fc-fsio
334 and run the last two upload-subtree and write-charging-config commands as above.
335
336 Recalibration
337 =============
338
339 In the interest of completeness, it needs to be noted that extracting Motorola's
340 original factory RF calibration values and reusing them for FreeCalypso is not
341 the only way: the other alternative is to perform a fresh calibration using a
342 Rohde&Schwarz CMU200 RF test machine and FreeCalypso RF calibration software
343 (fc-rfcal-tools). This approach will yield superior results, but the
344 requirement of having a CMU200 instrument which is itself properly calibrated
345 and a cabling setup with the right adapters whose insertion loss at particular
346 GSM frequencies is precisely known makes this approach feasible only for
347 professional FreeCalypso service shops, not for ordinary individual users.