# HG changeset patch # User Mychaela Falconia # Date 1457293773 0 # Node ID 0ee75fdf082f94b7695ae958c32c8f825045e583 # Parent 7d3f0910aeb2fb64ec8aaa49f4c173d57a16ec1f doc/FC-on-Compal written diff -r 7d3f0910aeb2 -r 0ee75fdf082f doc/FC-on-Compal --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/FC-on-Compal Sun Mar 06 19:49:33 2016 +0000 @@ -0,0 +1,232 @@ +FreeCalypso GSM firmware on Mot C11x/12x and C139/140 families +============================================================== + +NOTE: this write-up refers specifically to our work-in-progress full-source +gcc-built GSM firmware. The tcs211-c139 hack which we have produced in late +2015 is an entirely different animal. + +Unlike tcs211-c139, our gcc-built gsm-fw can run equally "well" on both our +preferred C139/140 platform and the more primitive C11x/12x, but this gcc-built +GSM fw is currently much more limited: + +* tcs211-c139 includes TI's demo/prototype UI code and an LCD driver that works + with C139/140 LCD hardware; our gcc-built gsm-fw currently has no UI code at + all, expecting control via AT commands via the same serial cable you use for + flashing it. + +* In common with other TCS211-based firmwares, tcs211-c139 has working voice + calls; in our current gcc-built gsm-fw they are broken on all targets - only + SMS works. + +The phones in this family have very little RAM: 256 KiB of Calypso on-chip RAM +(IRAM) on all variants, plus another 256 KiB of board-level RAM (XRAM) on +C11x/12x or 512 KiB of XRAM on C139/140. The tcs211-c139 port uses almost all +available IRAM and XRAM on the C139, hence porting it to C11x with even less RAM +was completely out of the question. Our gcc-built gsm-fw currently has a lot +less functionality integrated, which naturally translates to lower memory +requirements - hence it is possible to build for the C11x. + +Because RAM is so precious on these feeble targets, running our own fw on them +absolutely requires flashing - fc-xram is not an option. Furthermore, we cannot +use an FFS-in-RAM configuration like we do on large-XRAM targets, and Motorola's +original FFS (flash file system) on these phones is not suitable for our needs - +unlike the situation on Openmoko modems. Therefore, we need to create and +maintain our own aftermarket FFS in a region of the device's flash memory which +we arbitrarily choose ourselves. + +If you are going to play with FreeCalypso firmwares on Mot C1xx targets, we +recommend that you devote a phone specifically for FreeCalypso and have another +phone to charge batteries. The process of flashing our firmware and creating +and maintaining the necessary aftermarket FFS on these targets is quite +involved, hence flashing a given phone back and forth between FreeCalypso and +Mot/Compal's official firmwares would be a total pita. However, none of our +firmwares (neither this one nor tcs211-c139) currently has working battery +charging code, hence you will need to use another phone running one of the +official fw versions to charge batteries. + +Compiling +========= + +The starting configuration file for building gsm-fw for targets in this family +is gsm-fw/configs/c139-gsm-flash. If your phone is a C139 or C140, this default +config can be used as-is, although you are always welcome to edit it to taste. +If your phone is C11x or C12x, change the target setting from c139 to c11x. + +The two numbers on the 'feature aftermarket-ffs' line select the region of +flash where our aftermarket FFS will be placed. The default configuration +places our FFS in the region from 0x3C0000 through 0x3EFFFF. This configuration +is recommended because: + +* it does not conflict with the FFS maintained by Mot/Compal's fw (the two + locations are different), eliminating the possibility of one firmware trying + to use the FFS created by the other; + +* it is placed at the very end of the flash (or rather at the end of the main + flash zone with 64 KiB sectors), maximizing the room available for the + firmware code image. + +NOTE 1: our aftermarket FFS code cannot use 8 KiB flash sectors at the chip's +highest addresses. Therefore, the sectors with factory data (which we don't +know how to grok) are safely left untouched by our fw. + +NOTE 2: if your phone is a C11x/12x variant with 2 MiB of flash (some have +2 MiB, others have 4 MiB), directing the firmware to put its FFS at 0x3C0000 +will result in it being at 0x1C0000 in reality - the highest address bit does +nothing when the flash chip only has 2 MiB. + +NOTE 3: if your phone is C139/140, keeping the aftermarket FFS at 0x3C0000 is +doubly recommended as that is the location used by our tcs211-c139 build. + +Flashing +======== + +The flashing procedures can be divided into two parts: the steps which you need +to perform only once when you first convert a given phone from Mot/Compal's fw +to FreeCalypso vs. the steps which you need to perform each time you wish to +flash another image you just compiled. + +If you are starting with a "virgin" phone that never ran FreeCalypso before, +you will need to start by breaking in with fc-loadtool and possibly tfc139 - +see the Compal-unlock article for more details. Once you are in with loadtool +and have made a backup of your original flash content, your first step will be +to reflash sector 0 (the dangerous one) with a version of the bootloader code +that has been patched to transfer control to the main fw image in the way we +need: + +loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin + +The compal-flash-boot-for-fc.bin code image is built in the +compal-flash-boot-for-fc directory of this source tree by starting from one of +Mot/Compal's original versions and applying a binary patch to it. + +This step of replacing the bootloader needs to be done only once - you don't +need to reflash this dangerous sector again when you reflash the main fw image. + +The next step is to flash the main firmware image which you have just compiled: + +loadtool> flash erase 0x10000 0x160000 +loadtool> flash program-bin 0x10000 finlink/flashImage.bin + +Note that the main fw image is flashed at 0x10000 on these targets. It is +flashed at 0 on sane targets with the Calypso boot ROM enabled in the hardware, +but Compal phones have malicious wiring in their PCBs that makes them brickable +and imposes the requirement of having working boot code in sector 0 at all +times, with the main fw image pushed down to 0x10000. + +Finally, you should erase the flash region which you have allocated for the +aftermarket FFS: + +loadtool> flash erase 0x3C0000 0x30000 + +or if your phone only has 2 MiB of flash: + +loadtool> flash erase 0x1C0000 0x30000 + +Now you can close your loadtool session with an exit command, and the phone +will be cleanly powered off. + +The next time you need to reflash another FreeCalypso image, get in with +loadtool like this: + +fc-loadtool -h compal /dev/ttyXXX + +There is no more need for tfc139 or for the inefficient -c 1003 option to +fc-loadtool once you've replaced the bootloader with compal-flash-boot-for-fc. +Once you are in loadtool, just reflash the main fw image, and leave the +bootloader and FFS sectors alone. + +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. 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. When running on Openmoko GTA0x and Pirelli +DP-L10 targets, our fw can use the original factory-programmed IMEISV and RF +calibration values (partial in the case of the Pirelli), but on Mot/Compal +phones these factory data are stored in a format which we haven't been able to +grok, hence we cannot make use of them. Therefore, you will have to set your +own IMEISV manually, and the radio will run uncalibrated. + +Initialize your aftermarket FFS as follows: + +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) + +After you've initialized your FFS as above, you can exit fc-fsio, run fc-shell +and try some AT commands: + +AT%SLEEP=2 -- disable deep sleep (doesn't work yet) +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. The only other way is to yank the battery, and doing the +latter is recommended anyway: when a phone with the present hack-firmware +flashed into it is powered off but still has the battery inserted, even a +momentary accidental press of the power button will cause it to power on and +boot, but there will be absolutely no visual indication, as the LCD stays dark. + +FreeCalypso GSM firmware on Mot C155/156 +======================================== + +One major difference between Mot C155/156 and the other two subfamilies is that +C155 and C156 have 2 MiB of XRAM, which is large enough to allow our small-ish +experimental firmware to run entirely from RAM, without flashing, just like on +the Pirelli DP-L10. + +If you are ready to play with our experimental GSM pseudo-modem fw on your +C155/156, the steps are as follows: + +1. Build the firmware in the c155-gsm-ramonly configuration - see the + Compiling document for more details. + +2. Connect your serial or USB-serial cable as usual; the phone needs to be + powered off at this point. + +3. Run a command like the following: + + fc-xram -h c155 /dev/ttyUSB0 finlink/ramImage.srec rvinterf + + If you are using an official FreeCalypso USB-serial cable from UberWaves, + you can speed up the code download by switching the serial line to 812500 + baud: + + fc-xram -h c155 -B 812500 /dev/ttyUSB0 finlink/ramImage.srec rvinterf + + Adjust the paths to your /dev/ttyUSBx or other serial device and your + ramImage.srec as appropriate, and add rvinterf logging or other options as + desired. Specifying rvinterf on the fc-xram command line directs fc-xram to + exec rvinterf and pass the serial channel to it immediately as soon as the + code image has been loaded into target RAM and jumped to; this direct + passing of the serial channel from fc-xram to rvinterf is appropriate + because the loaded fw will immediately start emitting binary trace packets + in TI's RVTMUX format. + +4. Momentarily press the red power button on the phone. + +Once the phone executes its boot code with fc-xram running, the boot path will +be diverted and our experimental firmware will be loaded into target device RAM +and jumped to. Our fw will now run, and the rvinterf process on the host will +maintain communication with it. + +Just like on the lower Mot/Compal subfamilies, we don't know how to extract the +factory-programmed IMEI and RF calibration data from Mot/Compal's proprietary +flash data structures, therefore, when our RAM-based firmware boots, it has no +IMEI and no RF calibration. Because this RAM-only configuration leaves the +flash completely alone and does not create a non-volatile FFS there, you will +need to set the IMEISV and RFCAP with fc-fsio on each boot. See the fc-fsio +commands given earlier, but skip the format command as the RAM-based FFS is +automatically formatted - but not otherwise initialized - upon firmware boot. diff -r 7d3f0910aeb2 -r 0ee75fdf082f doc/Firmware_Status --- a/doc/Firmware_Status Sat Mar 05 20:50:37 2016 +0000 +++ b/doc/Firmware_Status Sun Mar 06 19:49:33 2016 +0000 @@ -81,3 +81,13 @@ Option 1 involves more prayer than actionable work, while Option 2 is currently being worked on in another subproject of FreeCalypso - see tcs211-l1-reconst. + +Target-specific usage instructions +================================== + +If you would like to play with our work-in-progress firmware and check it out +for yourself, see the following target-specific instructions: + +Mot C1xx (Compal) FC-on-Compal +Openmoko GTA01/02 Freerunner-Howto +Pirelli DP-L10 Pirelli-Howto