# HG changeset patch # User Mychaela Falconia # Date 1446710994 0 # Node ID 52325cb524a8418739999ced56dfdc0e15480257 # Parent fa6b0576202dd5474493311ce84939bc41611f04 new README written for the UI-enabled configuration diff -r fa6b0576202d -r 52325cb524a8 README --- a/README Thu Nov 05 01:50:11 2015 +0000 +++ b/README Thu Nov 05 08:09:54 2015 +0000 @@ -1,30 +1,13 @@ 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. +has been made to run on the Motorola C139. Once the remaining bugs get shaken +out (there are still some crippling ones, so don't break out the champagne yet), +one will be able to replace Motorola's firmware in flash with this one and +*still be able to use the phone as an end user* - but now running firmware that +we build from source ourselves, one whose internals we know and understand and +which we can use a baseline for further functional improvements. -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. +Compiling +========= 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 @@ -38,41 +21,94 @@ ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c 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. +compile the present fw as follows: + +cd g23m +./winebuild.sh +./copyout.sh + +The build products will be in the g23m/mfw-build directory. mfw-build.progbin +is the flashable image, and the other files should be saved as documentation: +you should retain the COFF, map and str2ind.tab files that correspond exactly +to what you have flashed, so you can debug it later. + +Flashing: what goes where +========================= + +WARNING: C139 phones are brickable! If you type the wrong command in +fc-loadtool, you can brick your phone *unrecoverably*! Flash sector 0 MUST at +all times contain working boot code that can successfully perform the following +functions: -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: +1. Check the headset jack UART for a possible serial download - if an external + host is requesting a serial code download, accept the serially loaded code + and jump to it. + +2. If no serial download is taking place, jump to the main fw image in the rest + of the flash for normal boot. + +Function (2) may differ depending on what main fw is to be used, but function +(1) is absolutely essential: if flash sector 0 is erased and not immediately +reprogrammed with working boot code, or if it gets programmed with some code +version that does not perform function (1), then all ability to take control of +the phone will be lost, and it will be forever stuck in one of two states: + +(a) If the boot code still performs function (2) and there happens to be a + working main fw image in the flash, the phone will be stuck with that fw + version forever, with no ability to reflash it or to load and execute any + code in RAM. + +(b) If the conditions of (a) above aren't met, the phone will be reduced to a + paperweight. There is no JTAG access on these phones, and the flash chip + is not only a micro-BGA, but also combined with SRAM in the same package. + Desoldering the flash+SRAM chip and replacing it with an externally + programmed one is not likely to be feasible, hence bricked really means + bricked. You've been warned! -* 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. +For FreeCalypso we've adopted our own version of the bootloader that performs +function (1) exactly like Mot/Compal's original (actually slightly better, as +we've removed the "1003" check, thus the inefficient -c 1003 fc-loadtool option +becomes unnecessary), but we've modified function (2): in Compal's original +design the main fw image starts at 0x2000 with the entry point at 0x20F8, +whereas in our arrangement the main fw image starts at 0x10000 with the entry +point at 0x10058. + +We've changed the starting address for the main fw image to coincide with the +physical flash erase block boundary and thereby reduce the bricking risk. If +we put our main fw image starting at 0x2000 like Mot/Compal did, we would have +to erase and reprogram flash sector 0 every time we would like to change the +main fw, incurring the risk of bricking the phone. But with our modified boot +code we only have to do it once, when a given phone is first transitioned from +Mot/Compal's original fw to one of ours. With subsequent reflashings from one +FreeCalypso fw version to another, we only need to reflash the main fw starting +at 0x10000, and leave flash sector 0 alone. + +Besides the main fw and the critical boot code, the flash houses two more +entities: the factory data block and the flash file system (FFS). -* 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! +Factory data block +================== + +The 8 KiB flash sector at 0x3FC000 contains per-unit factory programming from +Motorola/Compal: RF calibration values, the unit's official IMEI and Cthulhu +knows what else. Unfortunately we haven't been able to parse this info beyond +a superficial level, hence we have no way to make use of any of this data. +But of course we should not erase or overwrite it, so we just leave this flash +sector alone. -* 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. +Flash file system +================= -Flashing and usage instructions -=============================== +Because Mot/Compal had moved their IMEI and RF calibration values into their +own proprietary format, these juicy items are NOT found in the FFS maintained +by the original firmware. Instead the original fw's FFS contains only dynamic +state and user data, hence it is of no use to us. We have adopted a different +flash location for our FFS from that used by Mot/Compal's fw in order to prevent +any possible cross-contamination, and you will need to manually initialize this +aftermarket FFS the first time you install FreeCalypso firmware on your C139. + +Flashing procedure +================== 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: @@ -85,14 +121,24 @@ loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin +(compal-flash-boot-for-fc.bin is our modified bootloader version, and it is + built from one of Compal's versions via binary patching in the freecalypso-sw + source tree.) + +Optional step: 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 at this point. + 3. Flash the main fw image: -loadtool> flash erase 10000 220000 -loadtool> flash program-bin 10000 aci-build.progbin +loadtool> flash erase 10000 290000 +loadtool> flash program-bin 10000 mfw-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.) +Or you can use the supplied nifty loadtool command script: + +loadtool> exec ./flash-mfw + +The current directory must be g23m for the script method to work. 4. Erase the sectors where our firmware's non-volatile flash file system (aftermarket FFS configuration) will reside: @@ -103,66 +149,32 @@ 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. - -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: +FFS initialization +================== -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. +The first time you boot your C139 after the above flashing procedure, the phone +should have no SIM in it. Firmwares built with UI enabled (like the present) +automatically fire up GSM functionality and try to connect to a network +immediately upon boot if a SIM is present, and you don't want to do that on +your first boot: at this point your phone has *no* IMEI and no working FFS at +all. When the fw boots up without a SIM, it still enables the part of the GSM +radio protocol stack that looks for usable cells, in anticipation of the +possibility that the user may need to make an emergency call, but it never +transmits anything in this state (Tx fully off) unless you do dial that +emergency call. -First session -============= +So take the SIM out before you start the reflashing procedure, and then boot +the SIM-less phone afterward. You should see a message on the LCD that reads +"Insert SIM". But instead of inserting a SIM, you should run the fc-fsio +utility from FreeCalypso host tools at this point. Plug the serial cable back +in if you unplugged it, and run fc-fsio: -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. +fc-fsio -p /dev/ttyXXX -Initialize your FFS as follows: - -1. Connect the serial cable, run rvinterf and boot the fw as above. +(Omit the -p argument if you already have rvinterf running for fc-fsio to + connect to.) -2. Before you try issuing any AT commands via fc-shell, run fc-fsio first. - -3. Initialize the FFS via fc-fsio as follows: +Then issue the following commands: fsio> format / fsio> mk-std-dirs @@ -171,7 +183,82 @@ 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. +Yes, you need to set your own IMEISV. The official one is stored in the factory +data block, but we don't know how to parse it, so it effectively does not exist +for us. It is entirely up to you whether you set the same IMEI as the official +one or a different one: our fw has no psychic powers to compare. Unless you +have reason to do otherwise though, the default should be to keep the original +IMEI. It is not clear what Mot/Compal's fw puts in the SV digits, so just put +00 in there if you don't feel like inventing version numbers. + +The set-rfcap command is necessary because our fw does not know otherwise +whether your C139 is the 900+1800 MHz version or 1900+850 MHz. If you don't +write a /gsm/com/rfcap file with this command, the fw defaults to quadband +(the part of the fw where this default is effected is a binary blob in the +present version) and will waste time scanning frequencies which it can't +receive because the corresponding RF transceiver input is unconnected +(unsupported high band) or because they are blocked by a SAW filter +(unsupported low band). + +After you have initialized your new aftermarket FFS with fc-fsio per the above, +exit fc-fsio and power your phone off: hold the power button down until a TI +logo appears on the LCD, then release the button; the phone will power off +shortly, and you'll know it's off when the LCD turns off. Now you can insert +a SIM and boot again - this time the phone should be live! + +Limitations +=========== + +* 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 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 (see next point), the option of having the phone dual-function as a + laptop-tethered modem is not available either. + +* TI's full-featured phone firmwares allow the phone to dual-function as a + modem, so one could connect the phone to a laptop and make a CSD call or use + GPRS. But they were 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), + and we absolutely need the debug interface, thus the classic AT command + interface had to be sacrificed. One can still issue AT commands over RVTMUX + with FreeCalypso host utility fc-shell, but this mechanism works only for + voice and SMS commands, not CSD or GPRS. Hence the data functions of the fw + remain unusable dead weight. :( + +* The headset functionality of the headset jack is also unavailable: because we + need to be able to use the debug interface at all times, we always keep the + electrically-controlled switch in the state that connects the headset jack to + the UART (presenting RVTMUX) instead of the audio circuits. + +* Because we don't know how to grok Mot/Compal's factory data block, our fw + currently runs 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! + +* The only 3 display configurations for which TI produced demo/prototype UI in + their chipset reference firmware are 84x48 pix monochrome, 176x220 pix + monochrome and 176x220 pix full color. We have a 96x64 pix LCD on the C139, + hence we are using TI's 84x48 UI design until we can create one that makes + use of the slightly larger 96x64 screen. However, TI had that 84x48 LCD on + their C-Sample and earlier platforms (*very* old), and as we discovered + empirically, the support for this 84x48 display config is already bitrotten + in the source tree we got, which officially targets TI's D-Sample and Leonardo + boards. + + At first the C-Sample UI configuration did not even compile. We got it to + compile by fixing it in a way that *seemed* right, but when we run this + resurrected C-Sample UI on our C139 hardware, one can plainly see that the UI + is still defective, as the expected output on the LCD is mixed with garbage. + We will need to delve into the UI code in more depth in order to really fix it + to where the display will be readable without garbage. + +* Battery charging has not been tried yet. It most likely won't work without + additional fixes. diff -r fa6b0576202d -r 52325cb524a8 README.aci --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.aci Thu Nov 05 08:09:54 2015 +0000 @@ -0,0 +1,177 @@ +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 + +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: + +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. + +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 +============= + +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.