--- /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!