+
−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; the
+
−current version at any given moment can be found at this URL:
+
−
+
−ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2
+
−
+
−You will also need our battery charging configuration files:
+
−
+
−https://www.freecalypso.org/hg/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.
+
−
+
−* For the lower C1xx subfamilies only: 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.  C155 and C156 phones have 8 MiB flash.
+
−
+
−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:
+
−
+
−C11x/12x: fc-loadtool -h compal /dev/ttyXXX
+
−C139/140: fc-loadtool -h compal -c 1004 /dev/ttyXXX
+
−C155/156: fc-loadtool -h c155 /dev/ttyXXX
+
−
+
−Change /dev/ttyXXX to the serial or USB-serial device corresponding to your
+
−serial cable.  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 (for the lower C1xx subfamilies), 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>
+
−
+
−For the lower C1xx subfamilies, 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).  For C155/156 the
+
−correct offset is 0x7E0000.  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 (or for C155/156) there are several to choose
+
−from.  The following two configs are the currently recommended ones:
+
−
+
−hybrid-vpm	This config is available for all 3 C1xx subfamilies, although
+
−		the actual fw images are different for each.  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.
+
−
+
−hybrid-ui-vo	This config is available only for the C139/140 target, not for
+
−		the other two.  This configuration includes the UI layers, thus
+
−		when a C139/140 phone runs this firmware, it is able to function
+
−		as an untethered phone without a host computer connection.
+
−		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.
+
−
+
−Both of the above are hybrid configurations in that they use the new TCS3
+
−versions of the G23M protocol stack and ACI (Application Control Interface)
+
−firmware components grafted on top of the TCS211 chipsetsw foundation, resulting
+
−in a fully built-from-source configuration without major blob components.  The
+
−UI layers BMI and MFW in the UI-enabled hybrid-ui-vo config also come from the
+
−new TCS3 source, not the old version of unknown origin.  They are "voice only"
+
−configs in that CSD, fax and GPRS functions are disabled - these functions
+
−cannot be made use of on Mot C1xx phones, and disabling them significantly
+
−reduces the weight of the firmware.
+
−
+
−For the C139 and C155 targets (but not for C11x/12x), it is also possible to
+
−build some of the older configs that use the old binary blob version of the
+
−G23M PS component and the corresponding old versions of ACI, MFW and BMI on top
+
−of it - however, those configuration are now officially deprecated except for
+
−only two remaining use cases which do not apply to Mot C1xx targets, hence they
+
−are no longer supported officially.
+
−
+
−Thus we have a total of 4 possible build configurations, one for the C11x/12x
+
−target, 2 for C139/140 and 1 for C155/156:
+
−
+
−./configure.sh c11x hybrid-vpm
+
−./configure.sh c139 hybrid-vpm
+
−./configure.sh c139 hybrid-ui-vo
+
−./configure.sh c155 hybrid-vpm
+
−
+
−See the Compiling article for more information on how to compile your own
+
−firmware image in one of the above configurations.
+
−
+
−Bootloader change on the lower C1xx subfamilies
+
−===============================================
+
−
+
−This section applies ONLY to C11x/12x and C139/140 subfamilies; it does NOT
+
−apply to the C155/156 subfamily.
+
−
+
−If this is your first time converting a given lower-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
+
−
+
−(If you are working with a binary release package that has prebuilt firmware
+
− images, the compal-flash-boot-for-fc.bin image is also included in the
+
− package.)
+
−
+
−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.
+
−
+
−On C155/156 phones the situation is a little different: they are also brickable
+
−with the Calypso boot ROM disabled, but Motorola's original bootloader on these
+
−phones is significantly different from the one on the lower C1xx subfamilies,
+
−and they use a different flash layout: the bootloader in the first 8 KiB sector,
+
−unused flash space between 0x2000 and 0x20000, and the main fw image starting
+
−at 0x20000.  Our FC firmwares for the C155/156 target are built to be flashed
+
−at 0x20000 just like Mot's official ones, and they are designed to receive
+
−control from Mot's original bootloader on this target.
+
−
+
−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.
+
−
+
−* If you are operating on a C11x/12x or C139/140 phone, reflash the boot sector
+
−  with our FreeCalypso version:
+
−
+
−  loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
+
−
+
−  DO NOT flash compal-flash-boot-for-fc.bin into C155/156 phones, it is ONLY
+
−  for the lower C1xx subfamilies!
+
−
+
−* 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, 4 MiB or 8 MiB flash.  On 2 MiB flash phones:
+
−
+
−  loadtool> flash erase 0x1C0000 0x30000
+
−
+
−  Or on 4 MiB flash phones:
+
−
+
−  loadtool> flash erase 0x3C0000 0x30000
+
−
+
−  Or on 8 MiB flash C155/156 phones:
+
−
+
−  loadtool> flash erase 0x700000 0xD0000
+
−
+
−* 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 (run it without the
+
−-p option to have it connect to your already-running rvinterf process) and
+
−initialize the aftermarket FFS for our firmware:
+
−
+
−fsio> format /
+
−fsio> mk-std-dirs
+
−fsio> set-imeisv fc XXXXXXXX-YYYYYY-SV (see following section for the details)
+
−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.
+
−
+
−Note regarding the IMEISV
+
−=========================
+
−
+
−The argument to the set-imeisv command in fc-fsio is a 16-digit IMEISV, not a
+
−15-digit IMEI.  The IMEI part of IMEISV (the first 14 digits) identifies the
+
−physical hardware and is supposed to be immutable, whereas the two SV digits
+
−are supposed to identify the software version, i.e., they are supposed to change
+
−when the software version changes in a significant way.  Motorola and Compal
+
−did in fact use the SV digits as called for by the specs: their official
+
−firmwares take the IMEI part of IMEISV from the factory-written per-unit vital
+
−data records, and each fw version appends its own SV digits, different from one
+
−version to the next.
+
−
+
−When a Mot C1xx phone runs FreeCalypso as opposed to one of Motorola's official
+
−fw versions, we need our own SV to identify our firmware as being distinct from
+
−any of Motorola's original versions.  The convention established by the Mother
+
−of FreeCalypso is that the SV for FreeCalypso on Mot C1xx should be set to 98.
+
−
+
−To transform the 15-digit IMEI of your Mot C1xx phone into the 16-digit IMEISV
+
−to be entered in fc-fsio set-imeisv, perform the following two steps:
+
−
+
−1) Drop the Luhn check digit - it is not included in the IMEISV form;
+
−2) Add -98 to the remaining 14 content digits of the IMEI from the previous
+
−   step.
+
−
+
−Exercising GSM functionality
+
−============================
+
−
+
−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
+
−
+
−Once you are connected to a network, you can dial and answer voice calls with
+
−ATD and ATA commands, and you can use GSM 07.05 AT commands to send and receive
+
−SMS.  You can also use the quite capable SMS tools included in the FC host tools
+
−package.
+
−
+
−When you are done, you can power the phone off by sending a 'poweroff' command
+
−through fc-shell, or you can kill rvinterf or unplug the serial cable and wait
+
−for the firmware to power off by the keepalive timeout after some 15 to 20 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.
+
−
+
−Restoring Motorola's original firmware
+
−======================================
+
−
+
−If you have many phones of the same type, it is best to dedicate a particular
+
−phone to FreeCalypso, as reflashing a phone back and forth is a royal pita.
+
−However, if you have only one phone, then you don't have much choice except to
+
−reflash it back and forth between Motorola's official fw and FreeCalypso, thus
+
−instructions need to be provided.
+
−
+
−Restoring original fw on the lower C1xx subfamilies
+
−---------------------------------------------------
+
−
+
−Whether you are restoring the original fw version your phone came with or
+
−flashing a different official fw version, you need to ensure that whichever fw
+
−version you are flashing does not have its bootloader locked out.  Examine your
+
−fw image with a hex dump tool and look at the 4 bytes at location 0x2060.  If
+
−these 4 bytes are all FF, then you have an older fw version with no bootloader
+
−locking capability - good.  If these 4 bytes are 'DD DD DD DD' (0xDDDDDDDD
+
−32=bit word), then your fw version does have bootloader locking capability, but
+
−the lock is not activated.  In this case you can still flash it, but you must
+
−make sure that this 32-bit word at 0x2060 always remains equal to 0xDDDDDDDD,
+
−otherwise your phone will be bricked.  And finally if the 4 bytes at 0x2060 are
+
−all zeros, then the bootloader lock is activated - DO NOT flash an image in
+
−this state (you will brick your phone if you do), instead you need to patch
+
−these 4 bytes to 0xDDDDDDDD with a hex editor and then flash the resulting
+
−unlocked version.
+
−
+
−Once you have verified that your to-be-flashed fw image is safe, you can flash
+
−it as follows:
+
−
+
−1) Get in with fc-loadtool:
+
−
+
−fc-loadtool -h compal -c 1004 /dev/ttyXXX
+
−
+
−The -c 1004 option is generally unnecessary if your phone runs FreeCalypso fw,
+
−but it doesn't hurt to always include it - it only makes the fc-loadtool entry
+
−process slower by about a second.
+
−
+
−2) Once you are at the loadtool> prompt, issue the following commands:
+
−
+
−if your phone is C139/140 or C11x/12x with 4 MiB flash:
+
−
+
−loadtool> flash erase-program-boot mot-fw-image.bin 0x10000
+
−loadtool> flash erase 0x10000 0x360000
+
−loadtool> flash program-bin 0x10000 mot-fw-image.bin 0x10000 0x360000
+
−
+
−or if your phone is C11x/12x with 2 MiB flash:
+
−
+
−loadtool> flash erase-program-boot mot-fw-image.bin 0x10000
+
−loadtool> flash erase 0x10000 0x1E0000
+
−loadtool> flash program-bin 0x10000 mot-fw-image.bin 0x10000 0x1E0000
+
−
+
−Restoring original fw on Mot C155/156
+
−-------------------------------------
+
−
+
−On these phones the bootloader is separate from the main body of the firmware,
+
−thus there is no need to reflash the dangerous boot sector (erase-program-boot)
+
−when changing firmwares, whether changing between Motorola's official fw and
+
−FreeCalypso or between different Mot fw versions.  Simply get in with
+
−fc-loadtool like this:
+
−
+
−fc-loadtool -h c155 /dev/ttyXXX
+
−
+
−and reflash the firmware like this:
+
−
+
−loadtool> flash erase 0x20000 0x7C0000
+
−loadtool> flash program-bin 0x20000 flash-backup.bin 0x20000 0x7C0000