FreeCalypso > hg > fc-am-toolkit

comparison doc/C1xx-flashing @ 23:2df287f4722c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/C1xx-flashing: article written
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 11 Jun 2023 09:55:27 +0000
parents
children b71216a5f3c3
comparison
equal deleted inserted replaced
22:873d5f33e8f3 23:2df287f4722c
1 Whether you are interested in FreeCalypso VPM firmware (the main use case for
2 FC aftermarket fw that has actual utility value for GSM network testing etc) or
3 the UI-enabled FC firmware for Mot C139 that is currently just a preview (and
4 is not expected to advance to actual usability any time soon), either way these
5 firmwares need to be flashed. All FC firmware offerings for Mot C1xx have
6 always required flashing, and various instructions have been published in the
7 past. However, old FC-on-C1xx flashing instructions should not be used with
8 current firmware versions, because of these new developments:
9
10 * Our current fw relies even more than it did before on having certain files in
11 FFS, hence populating the flash with not only the fw image, but also the FFS
12 content it needs has become more important than ever before.
13
14 * For FC-on-C1xx configurations with 4 MiB flash, including the most important
15 case of C139, the FFS location changed from the old one in Magnetite and
16 Selenite to a new one in Tourmaline. Therefore, old FFS instructions have to
17 be invalidated.
18
19 The present fc-am-toolkit package provides a new way to flash FC firmware images
20 and initialize their associated FFS in one go, and this document provides
21 instructions.
22
23 Step 1: install software on your host machine
24 =============================================
25
26 The host machine (PC or laptop) which you are going to use to drive the phone
27 flashing process will need to have the following FreeCalypso software packages
28 installed on it:
29
30 1) FC host tools base package:
31
32 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2
33
34 2) FFS data bundle add-on:
35
36 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-data-bundle-latest.tar.bz2
37
38 3) The present fc-am-toolkit package.
39
40 All 3 packages install all of their files under the /opt/freecalypso directory
41 tree defined by the Mother, and you only need to do this host software
42 installation once (or when updates come out), irrespective of how many phones
43 of various kinds you are going to flash or otherwise work with.
44
45 Step 2: read and save your phone's current flash
46 ================================================
47
48 You will need to create a dedicated project directory for each individual phone
49 you are going to reflash to FreeCalypso, or on which you may contemplate the
50 possibility of such reflashing. This per-phone project directory will contain
51 a record of the phone's IMEI, a dump (backup) of the original flash content,
52 bits of data extracted from that flash dump with tools in the present package,
53 generated command scripts for flashing FC firmware and for restoring the
54 original flash, and some other script-generated files - read the shell script
55 code if you want to know the full details.
56
57 In previous instructions I advised users to name this per-phone project
58 directory after the IMEI, i.e., to use the IMEI as the directory name. I no
59 longer recommend that approach, and it no longer makes sense with the current
60 fc-am-toolkit design as the IMEI will be stored in a text file inside the
61 per-phone project directory, rather than in the directory name. So please name
62 your project directories in whatever way makes sense for your situation.
63
64 Once you have created your per-phone project directory, please cd into it, and
65 with that directory as current, run fc-loadtool as appropriate for your C1xx
66 phone model:
67
68 fc-loadtool -h compal /dev/ttyXXX -- for C11x/12x
69 fc-loadtool -h compal -c 1004 /dev/ttyXXX -- for C139/140
70 fc-loadtool -h c155 /dev/ttyXXX -- for C155/156
71
72 These simple instructions are valid for C1xx phones with unlocked bootloaders.
73 If your bootloader is locked, you will need to break in with tfc139 instead.
74 There are other documentation articles in FreeCalypso that describe tfc139
75 break-in method.
76
77 These instructions also assume that you already know how to operate fc-loadtool
78 on a basic level. If not, here is a basic summary: to make an entry with
79 fc-loadtool, you need to start with the phone turned off - but the battery
80 needs to be inserted, and preferably have a full charge. You need to run the
81 fc-loadtool command shown above (change /dev/ttyXXX to the correct serial or
82 USB-serial device in your setup) with the cable connected between your PC/laptop
83 and your phone's headset jack _and with the phone turned off_. When you run
84 fc-loadtool in this state, it will sit there, waiting for PROMPT1 from the
85 phone's bootloader. Once fc-loadtool is running in that state and the cable is
86 correctly inserted on the phone end, press the red power button on the phone -
87 a momentary press is sufficient and recommended.
88
89 Once you have landed at the loadtool> prompt, make a dump of your flash as
90 follows:
91
92 loadtool> flash dump2bin flashdump.bin
93
94 The dump file needs to be named flashdump.bin - at least in the case of C11x/12x
95 subfamily, there is one script in the fc-am-toolkit shell script hierarchy that
96 looks for this original flash image under this specific name.
97
98 Once the flash dump operation finishes, issue this additional command:
99
100 loadtool> flash compal-imei IMEI
101
102 This command tells fc-loadtool to retrieve the phone's factory IMEI from OTP
103 cells (the flash chip's OTP protection register) and save it into a text file
104 named "IMEI". The file name is important - scripts that follow will look for
105 the IMEI in the file with this name.
106
107 IMEI retrieval needs to be done with this extra command because of the location
108 where this factory datum is stored. On Compal phones the factory IMEI is not
109 stored anywhere at all in the flash image (in the main byte array held by the
110 flash memory chip), instead it is stored in an out-of-band location (OTP cells,
111 meaning physically immutable once written) in the flash chip's protection
112 register. Therefore, this factory IMEI cannot be extracted from a captured
113 flash image - instead it needs to be read in a separate explicit step and saved
114 alongside the flash image.
115
116 Once you have captured both flashdump.bin and IMEI, close your fc-loadtool
117 session by issuing an "exit" command at the loadtool> prompt. The phone will
118 return to its powered-off state.
119
120 Step 3: analyze the flash image you just captured
121 =================================================
122
123 Run this command:
124
125 c1xx-analyze-image flashdump.bin
126
127 This command runs a shell script, which then invokes several different programs
128 that analyze various aspects of the flash image. Your current directory when
129 running the above script command needs to be the per-phone project directory,
130 and the script will create the following items:
131
132 * A subdirectory named rfasc will contain extracted RF calibration values in
133 FreeCalypso RF table ASCII format, which is both human- and machine-readable.
134 This directory is not used by any subsequent fc-am-toolkit scripts, but if
135 you have the mind of an engineer, you may find its content interesting.
136
137 * Another subdirectory named rfbin will contain the same data as rfasc, but in
138 the firmware's internal binary format. This subdir will be used by subsequent
139 scripts.
140
141 * A text file named restore-flash will contain a generated command script for
142 fc-loadtool - executing this script will restore the flash image in
143 flashdump.bin back into your phone's flash, i.e., restore your phone back to
144 its original state after playing with FreeCalypso.
145
146 Step 4: prepare FC firmware flashing command script
147 ===================================================
148
149 This step is the first one where you need the FC firmware image you seek to
150 flash - previous steps didn't need one. You can flash a firmware image which
151 you compiled yourself from source, or an official build you downloaded as part
152 of a tarball release - either way, you need the fwimage.bin file that
153 corresponds to your hardware model (c11x, c139 or c155) and your desired
154 functional configuration as in VPM or UI preview firmware.
155
156 VERY IMPORTANT: You need to be very certain of which C1xx subfamily your phone
157 belongs to; the 3 subfamilies known to us are C11x/12x, C139/140 and C155/156.
158 Firmware images are NOT interchangeable between these 3 hw subfamilies! C11x
159 and C139 are distinguished by their LCD type (monochrome on C11x, color on
160 C139); C155/156 have a distinct visual appearance, but they also have 8 MiB
161 flash which no other subfamily in this set uses, and our c1xx-analyze-image
162 script looks at the image size. Verbose notes printed by that script should
163 agree with your own knowledge of which phone subfamily you are working with -
164 if there is a discrepancy, STOP RIGHT HERE and ask for expert help.
165
166 Once you have confirmed your phone model/subfamily and selected the firmware
167 image you are going to flash, execute one of the following shell scripts:
168
169 c11x-gen-fc-script path/to/fwimage.bin
170 c139-gen-fc-script path/to/fwimage.bin
171 c155-gen-fc-script path/to/fwimage.bin
172
173 Each script variant works the same way for its respective C1xx subfamily, and
174 all have the same invokation rules: the current directory needs to be your
175 per-phone project directory containing flashdump.bin and IMEI files and the
176 rfbin subdirectory produced in steps 2 and 3, and the script adds to this
177 project directory.
178
179 The main result of executing the script command above will be a text file named
180 fc-flash-script; this text file is a command script for fc-loadtool that
181 reflashes your phone to the FreeCalypso fw image you have selected. The fw
182 image pathname you gave to {c11x,c139,c155}-gen-fc-script will be contained
183 inside the generated fc-flash-script - but in addition to referencing that fw
184 image, the generated loadtool command script also contains instructions for
185 programming fc-ffs.bin into the phone along with the firmware. This fc-ffs.bin
186 image is also generated by the shell script you just ran, and it is specific to
187 your individual phone: your IMEI and extracted RF calibration values go into it.
188
189 Step 5: actually flash your phone
190 =================================
191
192 This step is the actual surgery - all previous steps merely manipulated data in
193 files in your project directory on your host machine. To perform the flashing
194 surgery, do the following:
195
196 * Using the phone's original firmware as the charging agent (the thing you plug
197 in is not the charger, it is the charging power source; the charger circuit
198 is inside the phone, and the firmware is the entity that controls the flow of
199 current from the charging power source into the battery), make sure that your
200 battery is fully charged. The flashing process does not require a ton of
201 battery power, but the last thing you want is to have your battery run out
202 while you are in the middle of the flashing operation.
203
204 * Make entry with fc-loadtool just like you did in step 2, when you made a dump
205 of the original flash content.
206
207 * Once you are at the loadtool> prompt, issue this command:
208
209 exec fc-flash-script
210
211 In this step you are basically telling fc-loadtool to execute the command script
212 that was prepared in step 4. This script performs all necessary flash erasure
213 and programming operations - having a previously prepared script do everything
214 in one go greatly reduced the chances of leaving your phone in an invalid
215 partially flashed state due to operator distraction or other human errors.
216 Once the flashing script finishes executing, exit loadtool and your phone will
217 power off. Next time this reflashed phone executes hardware switch-on (power
218 button press or charging power plug-in while off), your firmware will boot!
219
220 Restoring the original firmware and full flash content
221 ======================================================
222
223 To restore the flash to its original state, do the same procedure as above, but
224 run 'exec restore-flash' instead of 'exec fc-flash-script' - just execute a
225 different flashing command script.
226
227 IMPORTANT NOTE: Do NOT attempt to transplant complete flash images (not just
228 the firmware portion, but the whole thing) from one phone to another! For
229 maximal restorative power, the loadtool command script generated by
230 c1xx-analyze-image (named restore-flash) restores the entire flash image, every
231 bit without exceptions - but this quality also makes the {flashdump.bin +
232 restore-flash script} package non-transplantable, i.e., it should NOT be
233 programmed into a different phone. Each individual phone has its own unique RF
234 calibration values and other factory tunings, stored in small sectors at the end
235 of the flash (after the firmware), and these bits should never be mindlessly
236 transplanted from one phone to another.
237
238 The firmware portion (part of the flash up to a certain model-dependent offset)
239 CAN be transplanted from one phone to another, and such copying of certain
240 "good" official Motorola fw versions is often quite useful - but such procedures
241 are a different topic from what the present document is addressing, which is
242 providing less expert users with a fool-proof way to play with FreeCalypso fw
243 and then restore their phones to the original state.
244
245 Flash process interruptions and recovery
246 ========================================
247
248 All C1xx phones are brickable: if you give wrong flash write commands to
249 fc-loadtool, it is quite easy to brick the phone's boot sector beyond recovery.
250 As a departure from previous FreeCalypso flashing instructions, in the present
251 flow you never enter any flash commands manually in loadtool - instead you
252 execute a loadtool command script that was generated by official shell scripts
253 in the present package.
254
255 Because the boot sector still needs to be rewritten (the command that does so
256 is part of the generated fc-flash-script and restore-flash scripts), a very
257 small bricking vulnerability window still exists - but this window is on the
258 order of a few tens of milliseconds. Furthermore, in order for the phone to
259 get bricked, the unfortunate event happening in that short vulnerability window
260 would have to be someone physically yanking the battery out of the phone at
261 that exact moment, or the battery running out or falling out, again at that
262 exact moment in a time window that spans maybe 100 ms at the most. There is
263 absolutely NO bricking vulnerability window in terms of the serial cable
264 disconnecting or the host machine crashing - those events can happen at any
265 moment in time and do NOT create bricking danger.
266
267 However, if the flashing process as a whole (on the order of a few minutes if
268 you are using "slow" 115200 baud rate) gets interrupted for whatever reason,
269 you will get a partially flashed phone, which may at first glance appear to be
270 bricked. But as long as the boot sector is good - and it will be good if you
271 haven't hit the worst-case scenario as above - you can still recover. To
272 recover from a flashing process that got interrupted in the middle, follow this
273 sequence:
274
275 * Return the phone to its powered-off state by removing and reinserting the
276 battery. Very important: do NOT press the power button or plug in charging
277 power after reinserting battery until instructed to do so below; if you mess
278 up, remove the battery again, reinsert it, and be careful this time to NOT
279 press the power button prematurely.
280
281 * With the phone off and the battery freshly removed and reinserted, connect
282 the headset jack serial cable and run fc-loadtool with the right arguments.
283
284 * Momentarily press the power button.
285
286 fc-loadtool should now make its entry and land you at the loadtool> prompt.
287 At this point you re-issue the 'exec fc-flash-script' or 'exec restore-flash'
288 command as per the direction of desired transition, and hopefully complete this
289 time.
290
291 Battery charging
292 ================
293
294 If your phone happens to be in the messed-up state caused by interrupted
295 flashing, charging will not work in this state: you can only use whatever power
296 is left in the battery, or swap in another battery, perhaps charged in another
297 phone. This consideration is the main reason why you should fully charge your
298 battery before starting a firmware flashing operation. Don't ever plug the
299 charging power source into a phone with (temporarily) messed-up firmware: it
300 won't do any actual charging (which requires charging control managed by fw),
301 but it will mess up your ability to make fc-loadtool entry for recovery.
302
303 One of the benefits of the current flashing procedure, with the firmware and a
304 fully prepared FFS image flashed in one go, is that once converted to
305 FreeCalypso, the phone regains its charging ability right away. With previous
306 instructions that called for flashing just the firmware and then formatting and
307 initializing FFS with fc-fsio, there was a longer window in which the phone is
308 not capable of charging its battery.
309
310 When the phone is in flashed FC firmware state, flashed correctly by following
311 the present instructions, it _is_ capable of charging: simply plug in charging
312 power, and charging will proceed much like it does in standard phones. This
313 aspect holds for VPM firmwares too, not just the UI-enabled version - although
314 the only way to see the progress state of the charging process is by watching
315 the debug trace output or querying the firmware with AT%CBC (a private AT
316 command) and knowing how to interpret the cryptic result it returns.
317
318 A warning is needed, however: FC-fw-driven battery charging on C1xx phones is
319 not carefully tuned, and what our fw aims for as "full charge" may actually be
320 either an undercharge or an overcharge. Significant overcharge appears to be
321 unlikely - the available evidence suggests that undercharge is a little more
322 likely - but the possibility of overcharge (which is very bad for battery
323 health) cannot be ruled out. You've been warned!