FreeCalypso > hg > tcs211-c139

comparison README @ 43:52325cb524a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
new README written for the UI-enabled configuration
author Mychaela Falconia <falcon@ivan.Harhan.ORG>
date Thu, 05 Nov 2015 08:09:54 +0000
parents 132b3e230631
children
comparison
equal deleted inserted replaced
42:fa6b0576202d 43:52325cb524a8
1 This semi-source tree contains a hacked version of TI's TCS211 firmware that 1 This semi-source tree contains a hacked version of TI's TCS211 firmware that
2 has been made to run on the Motorola C139. The UI part of TI's reference fw 2 has been made to run on the Motorola C139. Once the remaining bugs get shaken
3 has not been ported over yet, hence the version presented here currently builds 3 out (there are still some crippling ones, so don't break out the champagne yet),
4 and works only in the modem-like ACI configuration, i.e., control via AT 4 one will be able to replace Motorola's firmware in flash with this one and
5 commands only. 5 *still be able to use the phone as an end user* - but now running firmware that
6 6 we build from source ourselves, one whose internals we know and understand and
7 TI's original fw was/is designed to make use of two UARTs, one for the classic 7 which we can use a baseline for further functional improvements.
8 AT command interface and the other for their RVTMUX debug/calibration/etc 8
9 interface. Unfortunately though, our present target hw has only one UART 9 Compiling
10 practically accessible (Calypso's MODEM UART brought out on the headset jack), 10 =========
11 thus the classic AT command interface had to be sacrificed. Instead the AT
12 command interface (which is currently the only way to control the GSM
13 functionality in the absence of a UI ported to the present target) needs to be
14 accessed through the RVTMUX binary packet interface using FreeCalypso host
15 tools rvinterf and fc-shell.
16
17 The present fw has been built from a semi-src (half source, half binary objects)
18 TI firmware release which was made for some manufacturer that made GSM/GPRS
19 modems, rather than voice handsets, hence the present configuration is
20 unfortunately highly suboptimal for our use case. The entire mass of code
21 supporting CSD, fax and GPRS data services is included and cannot be removed
22 because that part of the fw is in binary blobs, but all this code is pure dead
23 weight in the present configuration: the phone UI layer (when we get around to
24 porting it) won't make any use of data functionality (nowhere near enough
25 resources on this hw to implement a WAP browser or MMS), and because we had to
26 give up the standard AT command channel, the option of having the phone dual-
27 function as a laptop-tethered modem is not available either.
28 11
29 Building the present firmware from semi-source requires using a Wine environment 12 Building the present firmware from semi-source requires using a Wine environment
30 to run TI's proprietary compiler toolchain and other build tools which exist 13 to run TI's proprietary compiler toolchain and other build tools which exist
31 only as M$ Windows binaries. The necessary environment can be downloaded here: 14 only as M$ Windows binaries. The necessary environment can be downloaded here:
32 15
36 finishing steps in generating an image that can be usefully flashed into a C139: 19 finishing steps in generating an image that can be usefully flashed into a C139:
37 20
38 ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c 21 ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c
39 22
40 Once you have the necessary build tools installed, you should be able to 23 Once you have the necessary build tools installed, you should be able to
41 compile the present fw by running first winebuild.sh, then copyout.sh in the 24 compile the present fw as follows:
42 g23m subdirectory. Then you can flash this firmware you just built into an 25
43 actual C139 phone with FreeCalypso host tool fc-loadtool. Flash sector 0 (the 26 cd g23m
44 brickable boot sector) needs to contain our patched bootloader version 27 ./winebuild.sh
45 compal-flash-boot-for-fc.bin (this brickable sector only needs to be rewritten 28 ./copyout.sh
46 once when first installing some FreeCalypso fw on the phone; no need to touch 29
47 this dangerous sector on subsequent updates from one FC fw version to another), 30 The build products will be in the g23m/mfw-build directory. mfw-build.progbin
48 and the main fw image needs to be flashed starting at 0x10000. The image to 31 is the flashable image, and the other files should be saved as documentation:
49 flash is aci-build.progbin - it has TI's bootloader code stripped off, as we 32 you should retain the COFF, map and str2ind.tab files that correspond exactly
50 are using compal-flash-boot-for-fc instead. 33 to what you have flashed, so you can debug it later.
51 34
52 The phones in question have a data structure in flash at 0x3FC000 (in an 8 KiB 35 Flashing: what goes where
53 short sector) that must contain factory programming, including each phone's 36 =========================
54 unique IMEI and RF calibration values. However, we don't understand how to 37
55 grok this data structure. Therefore, our firmware features the following 38 WARNING: C139 phones are brickable! If you type the wrong command in
56 points of inconvenience: 39 fc-loadtool, you can brick your phone *unrecoverably*! Flash sector 0 MUST at
57 40 all times contain working boot code that can successfully perform the following
58 * You have to set your own IMEI. It's entirely up to you whether you set the 41 functions:
59 same IMEI as the phone had originally or a different one, but our fw has no 42
60 way of reading the original from Mot/Compal's factory flash programming. 43 1. Check the headset jack UART for a possible serial download - if an external
61 You probably won't be able to connect to a live commercial GSM network until 44 host is requesting a serial code download, accept the serially loaded code
62 you set some IMEISV which the network will accept as valid. 45 and jump to it.
63 46
64 * Because Mot/Compal stored their RF calibration values in some format 47 2. If no serial download is taking place, jump to the main fw image in the rest
65 (different from TI's) which we can't grok, a phone running our aftermarket fw 48 of the flash for normal boot.
66 will run UNCALIBRATED. It may have difficulty connecting to networks if it 49
67 can't acquire the frequency burst lacking VCXO calibration, and the Tx power 50 Function (2) may differ depending on what main fw is to be used, but function
68 levels are almost certainly wrong (out of spec) - BEWARE! 51 (1) is absolutely essential: if flash sector 0 is erased and not immediately
69 52 reprogrammed with working boot code, or if it gets programmed with some code
70 * Our fw does not even know whether your C139 is the 900+1800 MHz version or 53 version that does not perform function (1), then all ability to take control of
71 850+1900 MHz. You will need to set the correct rfcap configuration at the 54 the phone will be lost, and it will be forever stuck in one of two states:
72 same time when you set your IMEISV. 55
73 56 (a) If the boot code still performs function (2) and there happens to be a
74 Flashing and usage instructions 57 working main fw image in the flash, the phone will be stuck with that fw
75 =============================== 58 version forever, with no ability to reflash it or to load and execute any
59 code in RAM.
60
61 (b) If the conditions of (a) above aren't met, the phone will be reduced to a
62 paperweight. There is no JTAG access on these phones, and the flash chip
63 is not only a micro-BGA, but also combined with SRAM in the same package.
64 Desoldering the flash+SRAM chip and replacing it with an externally
65 programmed one is not likely to be feasible, hence bricked really means
66 bricked. You've been warned!
67
68 For FreeCalypso we've adopted our own version of the bootloader that performs
69 function (1) exactly like Mot/Compal's original (actually slightly better, as
70 we've removed the "1003" check, thus the inefficient -c 1003 fc-loadtool option
71 becomes unnecessary), but we've modified function (2): in Compal's original
72 design the main fw image starts at 0x2000 with the entry point at 0x20F8,
73 whereas in our arrangement the main fw image starts at 0x10000 with the entry
74 point at 0x10058.
75
76 We've changed the starting address for the main fw image to coincide with the
77 physical flash erase block boundary and thereby reduce the bricking risk. If
78 we put our main fw image starting at 0x2000 like Mot/Compal did, we would have
79 to erase and reprogram flash sector 0 every time we would like to change the
80 main fw, incurring the risk of bricking the phone. But with our modified boot
81 code we only have to do it once, when a given phone is first transitioned from
82 Mot/Compal's original fw to one of ours. With subsequent reflashings from one
83 FreeCalypso fw version to another, we only need to reflash the main fw starting
84 at 0x10000, and leave flash sector 0 alone.
85
86 Besides the main fw and the critical boot code, the flash houses two more
87 entities: the factory data block and the flash file system (FFS).
88
89 Factory data block
90 ==================
91
92 The 8 KiB flash sector at 0x3FC000 contains per-unit factory programming from
93 Motorola/Compal: RF calibration values, the unit's official IMEI and Cthulhu
94 knows what else. Unfortunately we haven't been able to parse this info beyond
95 a superficial level, hence we have no way to make use of any of this data.
96 But of course we should not erase or overwrite it, so we just leave this flash
97 sector alone.
98
99 Flash file system
100 =================
101
102 Because Mot/Compal had moved their IMEI and RF calibration values into their
103 own proprietary format, these juicy items are NOT found in the FFS maintained
104 by the original firmware. Instead the original fw's FFS contains only dynamic
105 state and user data, hence it is of no use to us. We have adopted a different
106 flash location for our FFS from that used by Mot/Compal's fw in order to prevent
107 any possible cross-contamination, and you will need to manually initialize this
108 aftermarket FFS the first time you install FreeCalypso firmware on your C139.
109
110 Flashing procedure
111 ==================
76 112
77 If you are not scared off by all of the above and you still wish to try this 113 If you are not scared off by all of the above and you still wish to try this
78 experimental fw on your C139, you can install it as follows: 114 experimental fw on your C139, you can install it as follows:
79 115
80 1. Connect to the phone with fc-loadtool, preceded by tfc139 if necessary - 116 1. Connect to the phone with fc-loadtool, preceded by tfc139 if necessary -
83 2. If the C139 in question does not already have some other FreeCalypso fw 119 2. If the C139 in question does not already have some other FreeCalypso fw
84 version in its flash, replace the bootloader: 120 version in its flash, replace the bootloader:
85 121
86 loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin 122 loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
87 123
124 (compal-flash-boot-for-fc.bin is our modified bootloader version, and it is
125 built from one of Compal's versions via binary patching in the freecalypso-sw
126 source tree.)
127
128 Optional step: If your serial cable setup supports the special GSM high baud
129 rates, you can speed the process up by issuing a baud 406250 or baud 812500
130 command at this point.
131
88 3. Flash the main fw image: 132 3. Flash the main fw image:
89 133
90 loadtool> flash erase 10000 220000 134 loadtool> flash erase 10000 290000
91 loadtool> flash program-bin 10000 aci-build.progbin 135 loadtool> flash program-bin 10000 mfw-build.progbin
92 136
93 (If your serial cable setup supports the special GSM high baud rates, 137 Or you can use the supplied nifty loadtool command script:
94 you can speed the process up by issuing a baud 406250 or baud 812500 138
95 command first.) 139 loadtool> exec ./flash-mfw
140
141 The current directory must be g23m for the script method to work.
96 142
97 4. Erase the sectors where our firmware's non-volatile flash file system 143 4. Erase the sectors where our firmware's non-volatile flash file system
98 (aftermarket FFS configuration) will reside: 144 (aftermarket FFS configuration) will reside:
99 145
100 loadtool> flash erase 3C0000 30000 146 loadtool> flash erase 3C0000 30000
101 147
102 5. Cleanly end your fc-loadtool session, which will power the phone off: 148 5. Cleanly end your fc-loadtool session, which will power the phone off:
103 149
104 loadtool> exit 150 loadtool> exit
105 151
106 Now your phone has FreeCalypso firmware in its flash, but it no longer works 152 FFS initialization
107 as a "normal" phone. Gotchas to be aware of: 153 ==================
108 154
109 * Mot/Compal's original firmwares (like all other production phone fws) 155 The first time you boot your C139 after the above flashing procedure, the phone
110 implement on a guard on the power-on button: you have to hold it down for a 156 should have no SIM in it. Firmwares built with UI enabled (like the present)
111 little while to confirm that you really mean to power the phone on; a 157 automatically fire up GSM functionality and try to connect to a network
112 momentary press of the power-on button is interpreted as spurious by standard 158 immediately upon boot if a SIM is present, and you don't want to do that on
113 fws, and they power the phone back off. However, the present hack-fw has no 159 your first boot: at this point your phone has *no* IMEI and no working FFS at
114 such guard, hence even a momentary press of the power-on button will launch 160 all. When the fw boots up without a SIM, it still enables the part of the GSM
115 the firmware into full boot. 161 radio protocol stack that looks for usable cells, in anticipation of the
116 162 possibility that the user may need to make an emergency call, but it never
117 * Because our present fw has no UI, the LCD will remain dark and the buttons 163 transmits anything in this state (Tx fully off) unless you do dial that
118 won't do anything. A momentary press of the power button will turn the phone 164 emergency call.
119 on, but you won't know that it's on - it will just silently and invisibly eat 165
120 the battery. Furthermore, the only way to power it off (aside from yanking 166 So take the SIM out before you start the reflashing procedure, and then boot
121 the battery) is to connect a serial cable and send a poweroff command via 167 the SIM-less phone afterward. You should see a message on the LCD that reads
122 fc-shell - there is no way to command a power-off from the keypad. (Pressing 168 "Insert SIM". But instead of inserting a SIM, you should run the fc-fsio
123 and holding the power button produces some kind of hang or crash - to be 169 utility from FreeCalypso host tools at this point. Plug the serial cable back
124 investigated - instead of a proper power-off.) 170 in if you unplugged it, and run fc-fsio:
125 171
126 * The present fw includes TI's LCC (low-cost charger) code that came with 172 fc-fsio -p /dev/ttyXXX
127 TCS211, but it is not clear whether or not this code drives the charging 173
128 circuitry correctly for Mot/Compal's hardware. Therefore, plan on having 174 (Omit the -p argument if you already have rvinterf running for fc-fsio to
129 the phone with FC firmware draining batteries only, and have another phone 175 connect to.)
130 running official fw (or a standalone charger) to charge them back up. 176
131 177 Then issue the following commands:
132 What all of these gotchas practically mean is that the phone with FC fw in it
133 should not have a battery inserted on a regular basis; instead you should use
134 it as follows:
135
136 1. Begin each FC hacking session by inserting the SIM you wish to use, then
137 inserting the battery - but don't touch the power button yet.
138
139 2. Connect the serial cable and run rvinterf on your host.
140
141 3. Press the power button, and see the firmware boot output in the rvinterf
142 window.
143
144 4. Run fc-shell, fc-fsio, fc-tmsh etc as desired during your hacking session.
145
146 5. End the session by yanking the battery, killing rvinterf and stowing away
147 your serial cable.
148
149 First session
150 =============
151
152 Remember the notes above regarding this fw not being able to read the factory
153 IMEI record? That's right, you'll need to set your own IMEISV. Furthermore,
154 because we are using our own "aftermarket" FFS configuration for non-volatile
155 data storage (you erased the flash sectors to be used for this FFS when you
156 flashed the fw with fc-loadtool, or at least you should have), this FFS needs
157 to be initialized before the fw can function correctly.
158
159 Initialize your FFS as follows:
160
161 1. Connect the serial cable, run rvinterf and boot the fw as above.
162
163 2. Before you try issuing any AT commands via fc-shell, run fc-fsio first.
164
165 3. Initialize the FFS via fc-fsio as follows:
166 178
167 fsio> format / 179 fsio> format /
168 fsio> mk-std-dirs 180 fsio> mk-std-dirs
169 fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere) 181 fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
170 fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware) 182 fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
171 or 183 or
172 fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware) 184 fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)
173 185
174 After the above steps, you can exit fc-fsio (or leave it running), run fc-shell 186 Yes, you need to set your own IMEISV. The official one is stored in the factory
175 and exercise the GSM MS via AT commands - try connecting to a network! With my 187 data block, but we don't know how to parse it, so it effectively does not exist
176 US band C139 (former Tracfone, now a Crackfone) on Operator 310260's network, 188 for us. It is entirely up to you whether you set the same IMEI as the official
177 both voice calls and SMS work like a charm. YMMV. 189 one or a different one: our fw has no psychic powers to compare. Unless you
190 have reason to do otherwise though, the default should be to keep the original
191 IMEI. It is not clear what Mot/Compal's fw puts in the SV digits, so just put
192 00 in there if you don't feel like inventing version numbers.
193
194 The set-rfcap command is necessary because our fw does not know otherwise
195 whether your C139 is the 900+1800 MHz version or 1900+850 MHz. If you don't
196 write a /gsm/com/rfcap file with this command, the fw defaults to quadband
197 (the part of the fw where this default is effected is a binary blob in the
198 present version) and will waste time scanning frequencies which it can't
199 receive because the corresponding RF transceiver input is unconnected
200 (unsupported high band) or because they are blocked by a SAW filter
201 (unsupported low band).
202
203 After you have initialized your new aftermarket FFS with fc-fsio per the above,
204 exit fc-fsio and power your phone off: hold the power button down until a TI
205 logo appears on the LCD, then release the button; the phone will power off
206 shortly, and you'll know it's off when the LCD turns off. Now you can insert
207 a SIM and boot again - this time the phone should be live!
208
209 Limitations
210 ===========
211
212 * The present fw has been built from a semi-src (half source, half binary
213 objects) TI firmware release which was made for some manufacturer that made
214 GSM/GPRS modems, rather than voice handsets, hence the present configuration
215 is unfortunately highly suboptimal for our use case. The entire mass of code
216 supporting CSD, fax and GPRS data services is included and cannot be removed
217 because that part of the fw is in binary blobs, but all this code is pure dead
218 weight in the present configuration: the phone UI layer won't make any use of
219 data functionality (nowhere near enough resources on this hw to implement a
220 WAP browser or MMS), and because we had to give up the standard AT command
221 channel (see next point), the option of having the phone dual-function as a
222 laptop-tethered modem is not available either.
223
224 * TI's full-featured phone firmwares allow the phone to dual-function as a
225 modem, so one could connect the phone to a laptop and make a CSD call or use
226 GPRS. But they were designed to make use of two UARTs, one for the classic
227 AT command interface and the other for their RVTMUX debug/calibration/etc
228 interface. Unfortunately though, our present target hw has only one UART
229 practically accessible (Calypso's MODEM UART brought out on the headset jack),
230 and we absolutely need the debug interface, thus the classic AT command
231 interface had to be sacrificed. One can still issue AT commands over RVTMUX
232 with FreeCalypso host utility fc-shell, but this mechanism works only for
233 voice and SMS commands, not CSD or GPRS. Hence the data functions of the fw
234 remain unusable dead weight. :(
235
236 * The headset functionality of the headset jack is also unavailable: because we
237 need to be able to use the debug interface at all times, we always keep the
238 electrically-controlled switch in the state that connects the headset jack to
239 the UART (presenting RVTMUX) instead of the audio circuits.
240
241 * Because we don't know how to grok Mot/Compal's factory data block, our fw
242 currently runs UNCALIBRATED. It may have difficulty connecting to networks
243 if it can't acquire the frequency burst lacking VCXO calibration, and the Tx
244 power levels are almost certainly wrong (out of spec) - BEWARE!
245
246 * The only 3 display configurations for which TI produced demo/prototype UI in
247 their chipset reference firmware are 84x48 pix monochrome, 176x220 pix
248 monochrome and 176x220 pix full color. We have a 96x64 pix LCD on the C139,
249 hence we are using TI's 84x48 UI design until we can create one that makes
250 use of the slightly larger 96x64 screen. However, TI had that 84x48 LCD on
251 their C-Sample and earlier platforms (*very* old), and as we discovered
252 empirically, the support for this 84x48 display config is already bitrotten
253 in the source tree we got, which officially targets TI's D-Sample and Leonardo
254 boards.
255
256 At first the C-Sample UI configuration did not even compile. We got it to
257 compile by fixing it in a way that *seemed* right, but when we run this
258 resurrected C-Sample UI on our C139 hardware, one can plainly see that the UI
259 is still defective, as the expected output on the LCD is mixed with garbage.
260 We will need to delve into the UI code in more depth in order to really fix it
261 to where the display will be readable without garbage.
262
263 * Battery charging has not been tried yet. It most likely won't work without
264 additional fixes.