--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/C1xx-Howto	Sun Jan 14 20:45:51 2018 +0000
@@ -0,0 +1,347 @@
+Running FreeCalypso firmware on Motorola C1xx phones
+====================================================
+
+Before we begin, it needs to be noted that running FreeCalypso fw on a C1xx
+phone is very much akin to xenotransplantation: Mot C1xx hardware is an alien
+to our FreeCalypso family (our native hw targets are those made by TI, Openmoko
+and us, not Motorola or Compal), and our non-Compal-based, non-Mot-based
+FreeCalypso fw is equally alien to the C1xx phones.  The xenotransplantation
+procedure of converting a C1xx phone to FreeCalypso is highly unnatural, and
+involves a large number of cumbersome manual steps - you've been warned.
+
+Preparing the host system
+=========================
+
+Firmware flashing on Mot C1xx phones is accomplished through the headset jack
+via a special cable.  There is no need to disassemble the phone in any way or
+to do any soldering or other hardware surgery, but you will need a host system
+to run the multitude of special software tools that are involved in the
+procedure.  You will need to begin by installing FreeCalypso host tools, and
+the current version of the FC-C1xx xenotransplantation procedure (the additions
+from the previous version are RF calibration data migration and battery
+charging configuration) requires the use of some new features that (as of this
+writing) have not yet made it in a packaged release of FC host tools - hence
+you will need to install and use the current "bleeding edge" development
+version from:
+
+https://bitbucket.org/falconian/freecalypso-tools
+
+You will also need the battery charging configuration files:
+
+https://bitbucket.org/falconian/fc-battery-conf
+
+Run 'make install' in the fc-battery-conf tree to add the battery charging
+configuration files to your FC host tools installation under /opt/freecalypso.
+
+Flash backup and data gathering
+===============================
+
+Before you begin the actual conversion of your C1xx phone to FreeCalypso, you
+will need to gather the following pieces of information:
+
+* The phone's IMEI - we don't know how to extract it out of Mot/Compal's non-TI
+  flash data structures, so you will have to reset it manually after the
+  firmware change.  Of course you can set your "new" FreeCalypso IMEI to
+  whatever you feel like, but if you wish to keep the original factory-assigned
+  one, you will need to note it down manually, either from the sticker inside
+  the battery compartment (*very* hard to read!) or by booting the phone up
+  with its original fw prior to the conversion, entering *#06# and reading it
+  from the display.
+
+* Your specific phone's factory RF calibration values: you will need to make a
+  dump of your phone's flash memory (also serves as a backup, always a good
+  thing to have) with fc-loadtool and extract the numbers of interest with our
+  c1xx-calextr utility, which is part of the new FC host tools.
+
+* You need to know whether your phone has 900+1800 MHz or 850+1900 MHz bands -
+  you will need to communicate this information to the new fw after the
+  conversion.  To the best of our knowledge, all C11x/12x and C140 phones have
+  900+1800 MHz bands, but C139 phones have been made in both versions.  On the
+  phones that have passed through our hands so far, the first two digits of the
+  IMEI have been 35 on 900+1800 MHz phones and 01 on 850+1900 MHz ones.
+
+* You need to know whether your phone has 2 MiB or 4 MiB flash.  To the best of
+  our knowledge, all C139/140 phones have 4 MiB flash, but C11x have been seen
+  with both 2 MiB and 4 MiB flashes.  The flash memory size will be autodetected
+  by fc-loadtool as part of making the flash dump.
+
+The Mother's method for keeping track of these per-phone bits of information is
+to create a separate directory for each phone with the IMEI as the directory
+name; the flash dump and the RF calibration bits extracted from it will then
+reside in that directory, while the IMEI is in the name of the directory itself.
+
+Once you have created your per-phone directory and cd'ed into it, you are ready
+to run fc-loadtool to capture the flash dump.  The phone needs to be off, but
+the battery needs to be present and have some charge in it; with the phone off,
+connect the serial cable between your host computer and the phone's headset
+jack, and run fc-loadtool as follows:
+
+fc-loadtool -h compal -c 1004 /dev/ttyXXX
+
+Change /dev/ttyXXX to the serial or USB-serial device corresponding to your
+serial cable.  The -c 1004 option (adds a little inefficiency which is required
+for C139/140) phones can be omitted if your phone is C11x/12x, but it is also
+harmless to always add it.  With the serial cable connected, the phone in the
+powered-off state and the fc-loadtool process running and waiting for the phone,
+press the red power button on the phone - a momentary press is sufficient and
+recommended.
+
+Once the phone boots the loadagent code fed to it serially by fc-loadtool and
+you land at the loadtool> prompt, issue the following command:
+
+flash dump2bin flashdump.bin
+
+Given this command, fc-loadtool will autodetect whether your phone has 2 MiB or
+4 MiB flash, then make a dump of the complete content of this flash memory and
+save it in a file named flashdump.bin in the current directory.  When this
+operation completes, exit the loadtool session with the exit command - it will
+also cleanly power the phone off.
+
+The next step is to extract the RF calibration values.  Run a command of the
+following form:
+
+c1xx-calextr -b rfbin flashdump.bin <offset>
+
+Change <offset> to 0x1FC000 if your phone has 2 MiB flash (the size of
+flashdump.bin is 2097152 bytes) or 0x3FC000 if it has 4 MiB flash (the size of
+flashdump.bin is 4194304 bytes).  The stdout scribbles from c1xx-calextr will
+indicate which per-band calibration records it finds (from which you can tell
+if the phone has 900+1800 MHz or 850+1900 MHz bands if you didn't have this
+knowledge already), and a directory named rfbin will be created, containing the
+correct subtree of directories and files which will need to be uploaded into
+the new FreeCalypso flash file system (FFS) under /gsm/rf after the firmware
+change.
+
+Selecting and building the desired firmware config
+==================================================
+
+There is only one FC Magnetite firmware configuration for C11x/12x phones, but
+for the better C139/140 phones there are 3 to choose from:
+
+hybrid-vpm	This config is available for both C11x/12x and C139/140
+		subfamilies, although the actual fw images are different
+		between the two.  In this configuration the converted phone
+		acts not as an end user phone, but as a voice pseudo-modem that
+		needs to be controlled by a host computer via a serial cable to
+		do anything interesting.  See the Voice-pseudo-modem article
+		for more information.
+
+l1reconst-chg	This config is available only for the C139/140 subfamily - its
+		XRAM usage won't fit into C11x's 256 KiB even if your phone has
+		4 MiB flash.  This config is also a voice pseudo-modem just like
+		hybrid-vpm, but it uses the older TCS2 version of the G23M PS
+		and ACI firmware components, which may be needed for debugging.
+
+2092		This config is not a voice pseudo-modem, but includes the demo
+		or prototype or proof-of-concept UI code we've got with our
+		version of TI's TCS211 fw.  However, please be warned that this
+		proof-of-concept UI is nowhere close to being practically
+		usable - see the Handset-goal article for more info.  Like
+		l1reconst-chg, this config is only available for the C139/140
+		subfamily, not for C11x/12x: not only does it has the same
+		issue of needing large flash and XRAM, but also we have the LCD
+		driver implemented only for the SPI/MicroWire LCD on the C139,
+		not for the I2C one on C11x.
+
+Thus we have a total of 4 possible build configurations, one for the C11x
+target and 3 for the C139:
+
+./configure.sh c11x hybrid-vpm
+./configure.sh c139 hybrid-vpm
+./configure.sh c139 l1reconst-chg
+./configure.sh c139 2092
+
+See the Compiling article for more information on how to compile your own
+firmware image in one of the above configurations.
+
+If this is your first time converting a given C1xx phone from its original
+firmware to FreeCalypso (as opposed to updating from an earlier FC firmware
+version), you will also need the compal-flash-boot-for-fc.bin bootloader image
+in addition to the main fw image you just built:
+
+ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/compal-flash-boot-for-fc.bin
+
+Mot C1xx phones are brickable - because the Calypso boot ROM is disabled by PCB
+wiring, the ability to reflash a phone with new firmware critically depends on
+there being a particular kind of boot code in flash sector 0 at all times - a
+particular kind of boot code that allows the boot process to be interrupted and
+diverted to external code loaded via the headset jack serial port.
+
+The FreeCalypso family of projects has adopted one specific version of the
+flash sector 0 boot code (produced by applying a binary patch to one of
+Compal/Motorola's original versions) for use with all of our firmwares for
+these phones.  We use the same FC-C1xx bootloader on both C11x/12x and C139/140
+phones: the official bootloader versions are different between the two (and
+moreover, each particular official fw version comes with its own bootloader
+version), but the simpler bootloader version which we took from one particular
+C11x fw version works perfectly well on the C139 as well, hence we've adopted
+it for all combinations.
+
+Once you have our compal-flash-boot-for-fc.bin image flashed in sector 0, you
+can then flash whichever FC firmware image you like at offset 0x10000 without
+having to touch the dangerous boot sector.
+
+Converting the phone to FreeCalypso fw
+======================================
+
+If you are starting with an unhacked C1xx phone running one of the official
+firmware versions, the procedure for flashing and bringing up FreeCalypso for
+the first time is as follows - *after* you have done all of the preparatory
+steps described in the preceding sections:
+
+* Have your phone's battery fully charged - although you will regain the
+  ability to charge it with FreeCalypso fw when the conversion is fully
+  complete (not just the flashing part, but also the subsequent FFS
+  initialization), your phone will not have this charging ability while you are
+  in the middle of the xenotransplantation procedure.
+
+* Get in with fc-loadtool just like you did when you made the dump of your
+  phone's flash memory for backup and RF calibration data extraction.
+
+* Once you are in with fc-loadtool, i.e., at the loadtool> prompt, reflash the
+  boot sector with the FreeCalypso version:
+
+  loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
+
+* To flash whichever FreeCalypso firmware image you would like to play with,
+  execute the flashing script which the fw build system produced along with the
+  actual image:
+
+  loadtool> exec flash-script
+
+* Erase the flash sectors to be used for the FFS (flash file system) by
+  FreeCalypso firmwares; the specific command depends on whether your phone has
+  2 MiB or 4 MiB flash.  On 2 MiB flash phones:
+
+  loadtool> flash erase 0x1C0000 0x30000
+
+  Or on 4 MiB flash phones:
+
+  loadtool> flash erase 0x3C0000 0x30000
+
+* Exiting fc-loadtool cleanly will cause it to power off the phone:
+
+  loadtool> exit
+
+Reflashing between different FreeCalypso firmwares
+==================================================
+
+By the conventions established in the FreeCalypso family of projects, all of
+our firmwares for C11x and C139 targets have the following in common:
+
+* They all stay out of the boot sector and expect to receive control from the
+  boot code in the same manner (boot entry point at 0x10058, exception vectors
+  at 0x10000), thus there is no need to reflash the dangerous boot sector when
+  going from one FC firmware to another.
+
+* They all use the same aftermarket FFS configuration of 3 sectors of 64 KiB
+  each (64x3) at 0x3C0000 on 4 MiB flash phones, or at 0x1C0000 on 2 MiB flash
+  phones.  This FFS location is deliberately different from the one used by
+  Mot/Compal's firmwares, eliminating the possibility of one fw trying to use
+  the FFS created by the other, and by putting our FFS toward the end of the
+  flash we maximize the amount of flash space available for our firmware code
+  images.  But even though we don't share our FFS with Mot/Compal's official
+  firmwares, we do share the same FFS between all of FreeCalypso firmware
+  projects - thus once you have initialized your FFS (see below) with one FC
+  firmware version, it will work with the others as well.
+
+If you need to reflash your C1xx phone from one FC firmware version to another,
+simply get in with fc-loadtool -h compal (no more need for the inefficient
+-c 1003 or -c 1004 options or for tfc139) and reflash just the fw image part:
+
+loadtool> exec flash-script
+
+First boot of the firmware
+==========================
+
+Connect the serial cable, but instead of running fc-loadtool, run rvinterf.
+Press the red power button on the phone briefly just like you would for
+fc-loadtool entry.  Because there is no fc-loadtool running on the host end of
+the serial cable, the boot path will *not* be diverted in the bootloader, and
+the main fw image will run - and this time it will be the FreeCalypso firmware
+you have compiled and flashed.  If the fw you have flashed is the UI demo
+configuration, the phone must have *NO* SIM in it the first time you boot it.
+UI-enabled fw configurations automatically bring up the GSM radio and try to
+connect to the default network on boot if there is a SIM present, and you don't
+want your firmware trying to connect to a real live GSM network when you haven't
+initialized your FFS yet.  If the fw you have flashed is one of the AT-command-
+controlled pseudo-modem configurations, then you don't need to worry if the SIM
+is there or not on your first boot - just don't command it to connect to a
+network until you have initialized the FFS.
+
+If you have flashed a non-UI firmware version, the phone's LCD will remain dark
+as there is no LCD driver code in this firmware, but you will see trace output
+in the rvinterf window, telling you that the fw is running.
+
+Before you do anything else, you will need to run fc-fsio and initialize the
+aftermarket FFS for our firmware:
+
+fsio> format /
+fsio> mk-std-dirs
+fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
+fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
+or
+fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)
+
+then additionally:
+
+fsio> upload-subtree rfbin /gsm/rf
+fsio> write-charging-config /opt/freecalypso/charging/c1xx/standard
+
+The last two commands are new with the 2018-01 revision of the FC-to-C1xx
+xenotransplantation procedure.  The upload-subtree command uploads the RF
+calibration values which you had extracted earlier with c1xx-calextr (the
+instructions assume that you are running from the same directory where the
+rfbin directory subtree had been created earlier), and this step is necessary
+in order for your phone to continue to transmit at the correct power levels
+after the conversion.  The write-charging-config command uploads the
+configuration settings for the FCHG battery charging driver, without which it
+cannot charge the battery; you must have the charging config files from the
+fc-battery-conf tree installed under /opt/freecalypso in order for this command
+to work as given.
+
+It needs to be noted that the battery charging config settings uploaded with
+fc-fsio write-charging-config take effect only on the next boot cycle of the
+firmware, i.e., until the next reboot after the write-charging-config operation,
+the firmware won't charge the battery even if there is a charging power source
+plugged in.
+
+After you've initialized your FFS as above, you should exit fc-fsio, and your
+next steps will depend on which fw configuration you are playing with.  If it's
+the sans-UI pseudo-modem configuration, run fc-shell and try some AT commands:
+
+AT+CMEE=2	-- enable verbose error responses
+AT+CFUN=1	-- enable radio and SIM interfaces
+AT+COPS=0	-- register to the default GSM network
+
+When you are done, you can power the phone off by sending a 'poweroff' command
+through fc-shell, or you can kill rvinterf and wait for the firmware to power
+off by the keepalive timeout after some 60 to 80 s.
+
+If you are playing with the UI demo firmware, after you have initialized your
+FFS, you can power the phone off with the power button, insert a SIM, power it
+back on and play with the primitive UI.
+
+Updating from previous versions
+===============================
+
+If you had previously initialized your aftermarket FFS using an earlier version
+of these instructions, before we added the RF calibration and charging config
+upload steps, you need to add these bits to your FFS.  Update to the latest FC
+host tools, extract the factory RF calibration values from a dump of your
+phone's flash with c1xx-calextr, add the battery charging config files to your
+/opt/freecalypso installation, boot the phone with rvinterf, get in with fc-fsio
+and run the last two upload-subtree and write-charging-config commands as above.
+
+Recalibration
+=============
+
+In the interest of completeness, it needs to be noted that extracting Motorola's
+original factory RF calibration values and reusing them for FreeCalypso is not
+the only way: the other alternative is to perform a fresh calibration using a
+Rohde&Schwarz CMU200 RF test machine and FreeCalypso RF calibration software
+(fc-rfcal-tools).  This approach will yield superior results, but the
+requirement of having a CMU200 instrument which is itself properly calibrated
+and a cabling setup with the right adapters whose insertion loss at particular
+GSM frequencies is precisely known makes this approach feasible only for
+professional FreeCalypso service shops, not for ordinary individual users.