# HG changeset patch # User Mychaela Falconia # Date 1446406784 0 # Node ID 132b3e230631a72ecbe3b4d8f9ca14f9967f7578 # Parent fcaacf99563626a8b0152e3c230198634033c80d README written for tcs211-c139 diff -r fcaacf995636 -r 132b3e230631 README --- a/README Sun Nov 01 17:25:37 2015 +0000 +++ b/README Sun Nov 01 19:39:44 2015 +0000 @@ -1,20 +1,177 @@ -This is a special debug version of leo2moko intended for use by FreeCalypso -developers only; it does not provide any additional features for Freerunner -users beyond standard leo2moko-r1 aka moko12; non-developer users are advised -to stay with the just-mentioned stable release. +This semi-source tree contains a hacked version of TI's TCS211 firmware that +has been made to run on the Motorola C139. The UI part of TI's reference fw +has not been ported over yet, hence the version presented here currently builds +and works only in the modem-like ACI configuration, i.e., control via AT +commands only. + +TI's original fw was/is designed to make use of two UARTs, one for the classic +AT command interface and the other for their RVTMUX debug/calibration/etc +interface. Unfortunately though, our present target hw has only one UART +practically accessible (Calypso's MODEM UART brought out on the headset jack), +thus the classic AT command interface had to be sacrificed. Instead the AT +command interface (which is currently the only way to control the GSM +functionality in the absence of a UI ported to the present target) needs to be +accessed through the RVTMUX binary packet interface using FreeCalypso host +tools rvinterf and fc-shell. + +The present fw has been built from a semi-src (half source, half binary objects) +TI firmware release which was made for some manufacturer that made GSM/GPRS +modems, rather than voice handsets, hence the present configuration is +unfortunately highly suboptimal for our use case. The entire mass of code +supporting CSD, fax and GPRS data services is included and cannot be removed +because that part of the fw is in binary blobs, but all this code is pure dead +weight in the present configuration: the phone UI layer (when we get around to +porting it) won't make any use of data functionality (nowhere near enough +resources on this hw to implement a WAP browser or MMS), and because we had to +give up the standard AT command channel, the option of having the phone dual- +function as a laptop-tethered modem is not available either. + +Building the present firmware from semi-source requires using a Wine environment +to run TI's proprietary compiler toolchain and other build tools which exist +only as M$ Windows binaries. The necessary environment can be downloaded here: + +ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/ + +You will also need the mokosrec2bin utility, which is needed for one of the +finishing steps in generating an image that can be usefully flashed into a C139: + +ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c -The primary intended use of this debug fw version is to enable FreeCalypso -developers to troubleshoot misbehavior in our current gcc-built fw version -by comparing the operation of the fw against a known working reference; -the debug features added in this version are: +Once you have the necessary build tools installed, you should be able to +compile the present fw by running first winebuild.sh, then copyout.sh in the +g23m subdirectory. Then you can flash this firmware you just built into an +actual C139 phone with FreeCalypso host tool fc-loadtool. Flash sector 0 (the +brickable boot sector) needs to contain our patched bootloader version +compal-flash-boot-for-fc.bin (this brickable sector only needs to be rewritten +once when first installing some FreeCalypso fw on the phone; no need to touch +this dangerous sector on subsequent updates from one FC fw version to another), +and the main fw image needs to be flashed starting at 0x10000. The image to +flash is aci-build.progbin - it has TI's bootloader code stripped off, as we +are using compal-flash-boot-for-fc instead. + +The phones in question have a data structure in flash at 0x3FC000 (in an 8 KiB +short sector) that must contain factory programming, including each phone's +unique IMEI and RF calibration values. However, we don't understand how to +grok this data structure. Therefore, our firmware features the following +points of inconvenience: + +* You have to set your own IMEI. It's entirely up to you whether you set the + same IMEI as the phone had originally or a different one, but our fw has no + way of reading the original from Mot/Compal's factory flash programming. + You probably won't be able to connect to a live commercial GSM network until + you set some IMEISV which the network will accept as valid. + +* Because Mot/Compal stored their RF calibration values in some format + (different from TI's) which we can't grok, a phone running our aftermarket fw + will run UNCALIBRATED. It may have difficulty connecting to networks if it + can't acquire the frequency burst lacking VCXO calibration, and the Tx power + levels are almost certainly wrong (out of spec) - BEWARE! + +* Our fw does not even know whether your C139 is the 900+1800 MHz version or + 850+1900 MHz. You will need to set the correct rfcap configuration at the + same time when you set your IMEISV. + +Flashing and usage instructions +=============================== + +If you are not scared off by all of the above and you still wish to try this +experimental fw on your C139, you can install it as follows: + +1. Connect to the phone with fc-loadtool, preceded by tfc139 if necessary - + see loadtools documentation. + +2. If the C139 in question does not already have some other FreeCalypso fw + version in its flash, replace the bootloader: + +loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin + +3. Flash the main fw image: -* Same AT-over-RVTMUX mechanism as implemented in FreeCalypso mainline; +loadtool> flash erase 10000 220000 +loadtool> flash program-bin 10000 aci-build.progbin + +(If your serial cable setup supports the special GSM high baud rates, + you can speed the process up by issuing a baud 406250 or baud 812500 + command first.) + +4. Erase the sectors where our firmware's non-volatile flash file system + (aftermarket FFS configuration) will reside: + +loadtool> flash erase 3C0000 30000 + +5. Cleanly end your fc-loadtool session, which will power the phone off: + +loadtool> exit + +Now your phone has FreeCalypso firmware in its flash, but it no longer works +as a "normal" phone. Gotchas to be aware of: + +* Mot/Compal's original firmwares (like all other production phone fws) + implement on a guard on the power-on button: you have to hold it down for a + little while to confirm that you really mean to power the phone on; a + momentary press of the power-on button is interpreted as spurious by standard + fws, and they power the phone back off. However, the present hack-fw has no + such guard, hence even a momentary press of the power-on button will launch + the firmware into full boot. + +* Because our present fw has no UI, the LCD will remain dark and the buttons + won't do anything. A momentary press of the power button will turn the phone + on, but you won't know that it's on - it will just silently and invisibly eat + the battery. Furthermore, the only way to power it off (aside from yanking + the battery) is to connect a serial cable and send a poweroff command via + fc-shell - there is no way to command a power-off from the keypad. (Pressing + and holding the power button produces some kind of hang or crash - to be + investigated - instead of a proper power-off.) + +* The present fw includes TI's LCC (low-cost charger) code that came with + TCS211, but it is not clear whether or not this code drives the charging + circuitry correctly for Mot/Compal's hardware. Therefore, plan on having + the phone with FC firmware draining batteries only, and have another phone + running official fw (or a standalone charger) to charge them back up. -* ETM FFS access protocol changed from TMFFS1 (used by some TI Windows tools, - apparently) to TMFFS2 (the version adopted for FreeCalypso) to allow the - flash file system to be manipulated with fc-fsio while this fw is running. +What all of these gotchas practically mean is that the phone with FC fw in it +should not have a battery inserted on a regular basis; instead you should use +it as follows: + +1. Begin each FC hacking session by inserting the SIM you wish to use, then + inserting the battery - but don't touch the power button yet. + +2. Connect the serial cable and run rvinterf on your host. + +3. Press the power button, and see the firmware boot output in the rvinterf + window. + +4. Run fc-shell, fc-fsio, fc-tmsh etc as desired during your hacking session. + +5. End the session by yanking the battery, killing rvinterf and stowing away + your serial cable. + +First session +============= -* The pf_TaskEntry() function in the guts of GPF has been patched to not - disable system traces. Verbose traces from various entities still need - to be enabled explicitly, but the expected responses to sysprim commands - are no longer suppressed. +Remember the notes above regarding this fw not being able to read the factory +IMEI record? That's right, you'll need to set your own IMEISV. Furthermore, +because we are using our own "aftermarket" FFS configuration for non-volatile +data storage (you erased the flash sectors to be used for this FFS when you +flashed the fw with fc-loadtool, or at least you should have), this FFS needs +to be initialized before the fw can function correctly. + +Initialize your FFS as follows: + +1. Connect the serial cable, run rvinterf and boot the fw as above. + +2. Before you try issuing any AT commands via fc-shell, run fc-fsio first. + +3. Initialize the FFS via fc-fsio 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 the above steps, you can exit fc-fsio (or leave it running), run fc-shell +and exercise the GSM MS via AT commands - try connecting to a network! With my +US band C139 (former Tracfone, now a Crackfone) on Operator 310260's network, +both voice calls and SMS work like a charm. YMMV.