# HG changeset patch # User Mychaela Falconia # Date 1515962751 0 # Node ID 43dbedde9d80fd26fa8ae8c35d66c3b3867d5fec # Parent 7bdd370f6f5909c674ac5da92de8dd64092206ec doc/C1xx-Howto written diff -r 7bdd370f6f59 -r 43dbedde9d80 doc/C1xx-Howto --- /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 + +Change 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. diff -r 7bdd370f6f59 -r 43dbedde9d80 doc/Voice-pseudo-modem --- a/doc/Voice-pseudo-modem Sat Jan 13 21:47:32 2018 +0000 +++ b/doc/Voice-pseudo-modem Sun Jan 14 20:45:51 2018 +0000 @@ -67,15 +67,13 @@ (with data services code as non-exercisable dead weight), but the more basic C11x/12x models (the ones with black&white LCDs) have smaller memories, and the only FC Magnetite config that is small enough to fit into their tiny flash and -XRAM capacity is hybrid-vpm. As of this writing there is no official support -for the C11x target yet, but it is currently under investigation, now that we -have a functional firmware config that is small enough to fit. +XRAM capacity is hybrid-vpm. Playing with FreeCalypso VPM on C1xx phones =========================================== If a Mot C1xx phone is flashed with a FreeCalypso firmware image in the VPM -configuration (see C139-Howto for the messy details of how to do it), it will +configuration (see C1xx-Howto for the messy details of how to do it), it will behave as follows: * The LCD will remain dark and the buttons will do nothing no matter what.