FreeCalypso > hg > fc-magnetite
view doc/C1xx-Howto @ 405:909fe8b92b26
components/tpudrv: support RF 10 or 12
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Thu, 18 Jan 2018 02:53:31 +0000 |
parents | 43dbedde9d80 |
children | 6530fc550836 |
line wrap: on
line source
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.