# HG changeset patch # User Mychaela Falconia # Date 1686477327 0 # Node ID 2df287f4722c1237eb303d5f431ddd5da2432edf # Parent 873d5f33e8f34307cbf840d6e771655b9fbc6ce9 doc/C1xx-flashing: article written diff -r 873d5f33e8f3 -r 2df287f4722c doc/C1xx-flashing --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/C1xx-flashing Sun Jun 11 09:55:27 2023 +0000 @@ -0,0 +1,323 @@ +Whether you are interested in FreeCalypso VPM firmware (the main use case for +FC aftermarket fw that has actual utility value for GSM network testing etc) or +the UI-enabled FC firmware for Mot C139 that is currently just a preview (and +is not expected to advance to actual usability any time soon), either way these +firmwares need to be flashed. All FC firmware offerings for Mot C1xx have +always required flashing, and various instructions have been published in the +past. However, old FC-on-C1xx flashing instructions should not be used with +current firmware versions, because of these new developments: + +* Our current fw relies even more than it did before on having certain files in + FFS, hence populating the flash with not only the fw image, but also the FFS + content it needs has become more important than ever before. + +* For FC-on-C1xx configurations with 4 MiB flash, including the most important + case of C139, the FFS location changed from the old one in Magnetite and + Selenite to a new one in Tourmaline. Therefore, old FFS instructions have to + be invalidated. + +The present fc-am-toolkit package provides a new way to flash FC firmware images +and initialize their associated FFS in one go, and this document provides +instructions. + +Step 1: install software on your host machine +============================================= + +The host machine (PC or laptop) which you are going to use to drive the phone +flashing process will need to have the following FreeCalypso software packages +installed on it: + +1) FC host tools base package: + + ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2 + +2) FFS data bundle add-on: + + ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-data-bundle-latest.tar.bz2 + +3) The present fc-am-toolkit package. + +All 3 packages install all of their files under the /opt/freecalypso directory +tree defined by the Mother, and you only need to do this host software +installation once (or when updates come out), irrespective of how many phones +of various kinds you are going to flash or otherwise work with. + +Step 2: read and save your phone's current flash +================================================ + +You will need to create a dedicated project directory for each individual phone +you are going to reflash to FreeCalypso, or on which you may contemplate the +possibility of such reflashing. This per-phone project directory will contain +a record of the phone's IMEI, a dump (backup) of the original flash content, +bits of data extracted from that flash dump with tools in the present package, +generated command scripts for flashing FC firmware and for restoring the +original flash, and some other script-generated files - read the shell script +code if you want to know the full details. + +In previous instructions I advised users to name this per-phone project +directory after the IMEI, i.e., to use the IMEI as the directory name. I no +longer recommend that approach, and it no longer makes sense with the current +fc-am-toolkit design as the IMEI will be stored in a text file inside the +per-phone project directory, rather than in the directory name. So please name +your project directories in whatever way makes sense for your situation. + +Once you have created your per-phone project directory, please cd into it, and +with that directory as current, run fc-loadtool as appropriate for your C1xx +phone model: + +fc-loadtool -h compal /dev/ttyXXX -- for C11x/12x +fc-loadtool -h compal -c 1004 /dev/ttyXXX -- for C139/140 +fc-loadtool -h c155 /dev/ttyXXX -- for C155/156 + +These simple instructions are valid for C1xx phones with unlocked bootloaders. +If your bootloader is locked, you will need to break in with tfc139 instead. +There are other documentation articles in FreeCalypso that describe tfc139 +break-in method. + +These instructions also assume that you already know how to operate fc-loadtool +on a basic level. If not, here is a basic summary: to make an entry with +fc-loadtool, you need to start with the phone turned off - but the battery +needs to be inserted, and preferably have a full charge. You need to run the +fc-loadtool command shown above (change /dev/ttyXXX to the correct serial or +USB-serial device in your setup) with the cable connected between your PC/laptop +and your phone's headset jack _and with the phone turned off_. When you run +fc-loadtool in this state, it will sit there, waiting for PROMPT1 from the +phone's bootloader. Once fc-loadtool is running in that state and the cable is +correctly inserted on the phone end, press the red power button on the phone - +a momentary press is sufficient and recommended. + +Once you have landed at the loadtool> prompt, make a dump of your flash as +follows: + +loadtool> flash dump2bin flashdump.bin + +The dump file needs to be named flashdump.bin - at least in the case of C11x/12x +subfamily, there is one script in the fc-am-toolkit shell script hierarchy that +looks for this original flash image under this specific name. + +Once the flash dump operation finishes, issue this additional command: + +loadtool> flash compal-imei IMEI + +This command tells fc-loadtool to retrieve the phone's factory IMEI from OTP +cells (the flash chip's OTP protection register) and save it into a text file +named "IMEI". The file name is important - scripts that follow will look for +the IMEI in the file with this name. + +IMEI retrieval needs to be done with this extra command because of the location +where this factory datum is stored. On Compal phones the factory IMEI is not +stored anywhere at all in the flash image (in the main byte array held by the +flash memory chip), instead it is stored in an out-of-band location (OTP cells, +meaning physically immutable once written) in the flash chip's protection +register. Therefore, this factory IMEI cannot be extracted from a captured +flash image - instead it needs to be read in a separate explicit step and saved +alongside the flash image. + +Once you have captured both flashdump.bin and IMEI, close your fc-loadtool +session by issuing an "exit" command at the loadtool> prompt. The phone will +return to its powered-off state. + +Step 3: analyze the flash image you just captured +================================================= + +Run this command: + +c1xx-analyze-image flashdump.bin + +This command runs a shell script, which then invokes several different programs +that analyze various aspects of the flash image. Your current directory when +running the above script command needs to be the per-phone project directory, +and the script will create the following items: + +* A subdirectory named rfasc will contain extracted RF calibration values in + FreeCalypso RF table ASCII format, which is both human- and machine-readable. + This directory is not used by any subsequent fc-am-toolkit scripts, but if + you have the mind of an engineer, you may find its content interesting. + +* Another subdirectory named rfbin will contain the same data as rfasc, but in + the firmware's internal binary format. This subdir will be used by subsequent + scripts. + +* A text file named restore-flash will contain a generated command script for + fc-loadtool - executing this script will restore the flash image in + flashdump.bin back into your phone's flash, i.e., restore your phone back to + its original state after playing with FreeCalypso. + +Step 4: prepare FC firmware flashing command script +=================================================== + +This step is the first one where you need the FC firmware image you seek to +flash - previous steps didn't need one. You can flash a firmware image which +you compiled yourself from source, or an official build you downloaded as part +of a tarball release - either way, you need the fwimage.bin file that +corresponds to your hardware model (c11x, c139 or c155) and your desired +functional configuration as in VPM or UI preview firmware. + +VERY IMPORTANT: You need to be very certain of which C1xx subfamily your phone +belongs to; the 3 subfamilies known to us are C11x/12x, C139/140 and C155/156. +Firmware images are NOT interchangeable between these 3 hw subfamilies! C11x +and C139 are distinguished by their LCD type (monochrome on C11x, color on +C139); C155/156 have a distinct visual appearance, but they also have 8 MiB +flash which no other subfamily in this set uses, and our c1xx-analyze-image +script looks at the image size. Verbose notes printed by that script should +agree with your own knowledge of which phone subfamily you are working with - +if there is a discrepancy, STOP RIGHT HERE and ask for expert help. + +Once you have confirmed your phone model/subfamily and selected the firmware +image you are going to flash, execute one of the following shell scripts: + +c11x-gen-fc-script path/to/fwimage.bin +c139-gen-fc-script path/to/fwimage.bin +c155-gen-fc-script path/to/fwimage.bin + +Each script variant works the same way for its respective C1xx subfamily, and +all have the same invokation rules: the current directory needs to be your +per-phone project directory containing flashdump.bin and IMEI files and the +rfbin subdirectory produced in steps 2 and 3, and the script adds to this +project directory. + +The main result of executing the script command above will be a text file named +fc-flash-script; this text file is a command script for fc-loadtool that +reflashes your phone to the FreeCalypso fw image you have selected. The fw +image pathname you gave to {c11x,c139,c155}-gen-fc-script will be contained +inside the generated fc-flash-script - but in addition to referencing that fw +image, the generated loadtool command script also contains instructions for +programming fc-ffs.bin into the phone along with the firmware. This fc-ffs.bin +image is also generated by the shell script you just ran, and it is specific to +your individual phone: your IMEI and extracted RF calibration values go into it. + +Step 5: actually flash your phone +================================= + +This step is the actual surgery - all previous steps merely manipulated data in +files in your project directory on your host machine. To perform the flashing +surgery, do the following: + +* Using the phone's original firmware as the charging agent (the thing you plug + in is not the charger, it is the charging power source; the charger circuit + is inside the phone, and the firmware is the entity that controls the flow of + current from the charging power source into the battery), make sure that your + battery is fully charged. The flashing process does not require a ton of + battery power, but the last thing you want is to have your battery run out + while you are in the middle of the flashing operation. + +* Make entry with fc-loadtool just like you did in step 2, when you made a dump + of the original flash content. + +* Once you are at the loadtool> prompt, issue this command: + + exec fc-flash-script + +In this step you are basically telling fc-loadtool to execute the command script +that was prepared in step 4. This script performs all necessary flash erasure +and programming operations - having a previously prepared script do everything +in one go greatly reduced the chances of leaving your phone in an invalid +partially flashed state due to operator distraction or other human errors. +Once the flashing script finishes executing, exit loadtool and your phone will +power off. Next time this reflashed phone executes hardware switch-on (power +button press or charging power plug-in while off), your firmware will boot! + +Restoring the original firmware and full flash content +====================================================== + +To restore the flash to its original state, do the same procedure as above, but +run 'exec restore-flash' instead of 'exec fc-flash-script' - just execute a +different flashing command script. + +IMPORTANT NOTE: Do NOT attempt to transplant complete flash images (not just +the firmware portion, but the whole thing) from one phone to another! For +maximal restorative power, the loadtool command script generated by +c1xx-analyze-image (named restore-flash) restores the entire flash image, every +bit without exceptions - but this quality also makes the {flashdump.bin + +restore-flash script} package non-transplantable, i.e., it should NOT be +programmed into a different phone. Each individual phone has its own unique RF +calibration values and other factory tunings, stored in small sectors at the end +of the flash (after the firmware), and these bits should never be mindlessly +transplanted from one phone to another. + +The firmware portion (part of the flash up to a certain model-dependent offset) +CAN be transplanted from one phone to another, and such copying of certain +"good" official Motorola fw versions is often quite useful - but such procedures +are a different topic from what the present document is addressing, which is +providing less expert users with a fool-proof way to play with FreeCalypso fw +and then restore their phones to the original state. + +Flash process interruptions and recovery +======================================== + +All C1xx phones are brickable: if you give wrong flash write commands to +fc-loadtool, it is quite easy to brick the phone's boot sector beyond recovery. +As a departure from previous FreeCalypso flashing instructions, in the present +flow you never enter any flash commands manually in loadtool - instead you +execute a loadtool command script that was generated by official shell scripts +in the present package. + +Because the boot sector still needs to be rewritten (the command that does so +is part of the generated fc-flash-script and restore-flash scripts), a very +small bricking vulnerability window still exists - but this window is on the +order of a few tens of milliseconds. Furthermore, in order for the phone to +get bricked, the unfortunate event happening in that short vulnerability window +would have to be someone physically yanking the battery out of the phone at +that exact moment, or the battery running out or falling out, again at that +exact moment in a time window that spans maybe 100 ms at the most. There is +absolutely NO bricking vulnerability window in terms of the serial cable +disconnecting or the host machine crashing - those events can happen at any +moment in time and do NOT create bricking danger. + +However, if the flashing process as a whole (on the order of a few minutes if +you are using "slow" 115200 baud rate) gets interrupted for whatever reason, +you will get a partially flashed phone, which may at first glance appear to be +bricked. But as long as the boot sector is good - and it will be good if you +haven't hit the worst-case scenario as above - you can still recover. To +recover from a flashing process that got interrupted in the middle, follow this +sequence: + +* Return the phone to its powered-off state by removing and reinserting the + battery. Very important: do NOT press the power button or plug in charging + power after reinserting battery until instructed to do so below; if you mess + up, remove the battery again, reinsert it, and be careful this time to NOT + press the power button prematurely. + +* With the phone off and the battery freshly removed and reinserted, connect + the headset jack serial cable and run fc-loadtool with the right arguments. + +* Momentarily press the power button. + +fc-loadtool should now make its entry and land you at the loadtool> prompt. +At this point you re-issue the 'exec fc-flash-script' or 'exec restore-flash' +command as per the direction of desired transition, and hopefully complete this +time. + +Battery charging +================ + +If your phone happens to be in the messed-up state caused by interrupted +flashing, charging will not work in this state: you can only use whatever power +is left in the battery, or swap in another battery, perhaps charged in another +phone. This consideration is the main reason why you should fully charge your +battery before starting a firmware flashing operation. Don't ever plug the +charging power source into a phone with (temporarily) messed-up firmware: it +won't do any actual charging (which requires charging control managed by fw), +but it will mess up your ability to make fc-loadtool entry for recovery. + +One of the benefits of the current flashing procedure, with the firmware and a +fully prepared FFS image flashed in one go, is that once converted to +FreeCalypso, the phone regains its charging ability right away. With previous +instructions that called for flashing just the firmware and then formatting and +initializing FFS with fc-fsio, there was a longer window in which the phone is +not capable of charging its battery. + +When the phone is in flashed FC firmware state, flashed correctly by following +the present instructions, it _is_ capable of charging: simply plug in charging +power, and charging will proceed much like it does in standard phones. This +aspect holds for VPM firmwares too, not just the UI-enabled version - although +the only way to see the progress state of the charging process is by watching +the debug trace output or querying the firmware with AT%CBC (a private AT +command) and knowing how to interpret the cryptic result it returns. + +A warning is needed, however: FC-fw-driven battery charging on C1xx phones is +not carefully tuned, and what our fw aims for as "full charge" may actually be +either an undercharge or an overcharge. Significant overcharge appears to be +unlikely - the available evidence suggests that undercharge is a little more +likely - but the possibility of overcharge (which is very bad for battery +health) cannot be ruled out. You've been warned!