FreeCalypso > hg > freecalypso-sw

comparison doc/FC-on-Compal @ 999:0ee75fdf082f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FC-on-Compal written
author Mychaela Falconia <falcon@ivan.Harhan.ORG>
date Sun, 06 Mar 2016 19:49:33 +0000
parents
children 69d6da9ee188
comparison
equal deleted inserted replaced
998:7d3f0910aeb2 999:0ee75fdf082f
1 FreeCalypso GSM firmware on Mot C11x/12x and C139/140 families
2 ==============================================================
3
4 NOTE: this write-up refers specifically to our work-in-progress full-source
5 gcc-built GSM firmware. The tcs211-c139 hack which we have produced in late
6 2015 is an entirely different animal.
7
8 Unlike tcs211-c139, our gcc-built gsm-fw can run equally "well" on both our
9 preferred C139/140 platform and the more primitive C11x/12x, but this gcc-built
10 GSM fw is currently much more limited:
11
12 * tcs211-c139 includes TI's demo/prototype UI code and an LCD driver that works
13 with C139/140 LCD hardware; our gcc-built gsm-fw currently has no UI code at
14 all, expecting control via AT commands via the same serial cable you use for
15 flashing it.
16
17 * In common with other TCS211-based firmwares, tcs211-c139 has working voice
18 calls; in our current gcc-built gsm-fw they are broken on all targets - only
19 SMS works.
20
21 The phones in this family have very little RAM: 256 KiB of Calypso on-chip RAM
22 (IRAM) on all variants, plus another 256 KiB of board-level RAM (XRAM) on
23 C11x/12x or 512 KiB of XRAM on C139/140. The tcs211-c139 port uses almost all
24 available IRAM and XRAM on the C139, hence porting it to C11x with even less RAM
25 was completely out of the question. Our gcc-built gsm-fw currently has a lot
26 less functionality integrated, which naturally translates to lower memory
27 requirements - hence it is possible to build for the C11x.
28
29 Because RAM is so precious on these feeble targets, running our own fw on them
30 absolutely requires flashing - fc-xram is not an option. Furthermore, we cannot
31 use an FFS-in-RAM configuration like we do on large-XRAM targets, and Motorola's
32 original FFS (flash file system) on these phones is not suitable for our needs -
33 unlike the situation on Openmoko modems. Therefore, we need to create and
34 maintain our own aftermarket FFS in a region of the device's flash memory which
35 we arbitrarily choose ourselves.
36
37 If you are going to play with FreeCalypso firmwares on Mot C1xx targets, we
38 recommend that you devote a phone specifically for FreeCalypso and have another
39 phone to charge batteries. The process of flashing our firmware and creating
40 and maintaining the necessary aftermarket FFS on these targets is quite
41 involved, hence flashing a given phone back and forth between FreeCalypso and
42 Mot/Compal's official firmwares would be a total pita. However, none of our
43 firmwares (neither this one nor tcs211-c139) currently has working battery
44 charging code, hence you will need to use another phone running one of the
45 official fw versions to charge batteries.
46
47 Compiling
48 =========
49
50 The starting configuration file for building gsm-fw for targets in this family
51 is gsm-fw/configs/c139-gsm-flash. If your phone is a C139 or C140, this default
52 config can be used as-is, although you are always welcome to edit it to taste.
53 If your phone is C11x or C12x, change the target setting from c139 to c11x.
54
55 The two numbers on the 'feature aftermarket-ffs' line select the region of
56 flash where our aftermarket FFS will be placed. The default configuration
57 places our FFS in the region from 0x3C0000 through 0x3EFFFF. This configuration
58 is recommended because:
59
60 * it does not conflict with the FFS maintained by Mot/Compal's fw (the two
61 locations are different), eliminating the possibility of one firmware trying
62 to use the FFS created by the other;
63
64 * it is placed at the very end of the flash (or rather at the end of the main
65 flash zone with 64 KiB sectors), maximizing the room available for the
66 firmware code image.
67
68 NOTE 1: our aftermarket FFS code cannot use 8 KiB flash sectors at the chip's
69 highest addresses. Therefore, the sectors with factory data (which we don't
70 know how to grok) are safely left untouched by our fw.
71
72 NOTE 2: if your phone is a C11x/12x variant with 2 MiB of flash (some have
73 2 MiB, others have 4 MiB), directing the firmware to put its FFS at 0x3C0000
74 will result in it being at 0x1C0000 in reality - the highest address bit does
75 nothing when the flash chip only has 2 MiB.
76
77 NOTE 3: if your phone is C139/140, keeping the aftermarket FFS at 0x3C0000 is
78 doubly recommended as that is the location used by our tcs211-c139 build.
79
80 Flashing
81 ========
82
83 The flashing procedures can be divided into two parts: the steps which you need
84 to perform only once when you first convert a given phone from Mot/Compal's fw
85 to FreeCalypso vs. the steps which you need to perform each time you wish to
86 flash another image you just compiled.
87
88 If you are starting with a "virgin" phone that never ran FreeCalypso before,
89 you will need to start by breaking in with fc-loadtool and possibly tfc139 -
90 see the Compal-unlock article for more details. Once you are in with loadtool
91 and have made a backup of your original flash content, your first step will be
92 to reflash sector 0 (the dangerous one) with a version of the bootloader code
93 that has been patched to transfer control to the main fw image in the way we
94 need:
95
96 loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
97
98 The compal-flash-boot-for-fc.bin code image is built in the
99 compal-flash-boot-for-fc directory of this source tree by starting from one of
100 Mot/Compal's original versions and applying a binary patch to it.
101
102 This step of replacing the bootloader needs to be done only once - you don't
103 need to reflash this dangerous sector again when you reflash the main fw image.
104
105 The next step is to flash the main firmware image which you have just compiled:
106
107 loadtool> flash erase 0x10000 0x160000
108 loadtool> flash program-bin 0x10000 finlink/flashImage.bin
109
110 Note that the main fw image is flashed at 0x10000 on these targets. It is
111 flashed at 0 on sane targets with the Calypso boot ROM enabled in the hardware,
112 but Compal phones have malicious wiring in their PCBs that makes them brickable
113 and imposes the requirement of having working boot code in sector 0 at all
114 times, with the main fw image pushed down to 0x10000.
115
116 Finally, you should erase the flash region which you have allocated for the
117 aftermarket FFS:
118
119 loadtool> flash erase 0x3C0000 0x30000
120
121 or if your phone only has 2 MiB of flash:
122
123 loadtool> flash erase 0x1C0000 0x30000
124
125 Now you can close your loadtool session with an exit command, and the phone
126 will be cleanly powered off.
127
128 The next time you need to reflash another FreeCalypso image, get in with
129 loadtool like this:
130
131 fc-loadtool -h compal /dev/ttyXXX
132
133 There is no more need for tfc139 or for the inefficient -c 1003 option to
134 fc-loadtool once you've replaced the bootloader with compal-flash-boot-for-fc.
135 Once you are in loadtool, just reflash the main fw image, and leave the
136 bootloader and FFS sectors alone.
137
138 First boot of the firmware
139 ==========================
140
141 Connect the serial cable, but instead of running fc-loadtool, run rvinterf.
142 Press the red power button on the phone briefly just like you would for
143 fc-loadtool entry. Because there is no fc-loadtool running on the host end of
144 the serial cable, the boot path will *not* be diverted in the bootloader, and
145 the main fw image will run - and this time it will be the FreeCalypso firmware
146 you have compiled and flashed. The phone's LCD will remain dark as there is no
147 LCD driver code in this firmware, but you will see trace output in the rvinterf
148 window, telling you that the fw is running.
149
150 Before you do anything else, you will need to run fc-fsio and initialize the
151 aftermarket FFS for our firmware. When running on Openmoko GTA0x and Pirelli
152 DP-L10 targets, our fw can use the original factory-programmed IMEISV and RF
153 calibration values (partial in the case of the Pirelli), but on Mot/Compal
154 phones these factory data are stored in a format which we haven't been able to
155 grok, hence we cannot make use of them. Therefore, you will have to set your
156 own IMEISV manually, and the radio will run uncalibrated.
157
158 Initialize your aftermarket FFS as follows:
159
160 fsio> format /
161 fsio> mk-std-dirs
162 fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
163 fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
164 or
165 fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)
166
167 After you've initialized your FFS as above, you can exit fc-fsio, run fc-shell
168 and try some AT commands:
169
170 AT%SLEEP=2 -- disable deep sleep (doesn't work yet)
171 AT+CMEE=2 -- enable verbose error responses
172 AT+CFUN=1 -- enable radio and SIM interfaces
173 AT+COPS=0 -- register to the default GSM network
174
175 When you are done, you can power the phone off by sending a 'poweroff' command
176 through fc-shell. The only other way is to yank the battery, and doing the
177 latter is recommended anyway: when a phone with the present hack-firmware
178 flashed into it is powered off but still has the battery inserted, even a
179 momentary accidental press of the power button will cause it to power on and
180 boot, but there will be absolutely no visual indication, as the LCD stays dark.
181
182 FreeCalypso GSM firmware on Mot C155/156
183 ========================================
184
185 One major difference between Mot C155/156 and the other two subfamilies is that
186 C155 and C156 have 2 MiB of XRAM, which is large enough to allow our small-ish
187 experimental firmware to run entirely from RAM, without flashing, just like on
188 the Pirelli DP-L10.
189
190 If you are ready to play with our experimental GSM pseudo-modem fw on your
191 C155/156, the steps are as follows:
192
193 1. Build the firmware in the c155-gsm-ramonly configuration - see the
194 Compiling document for more details.
195
196 2. Connect your serial or USB-serial cable as usual; the phone needs to be
197 powered off at this point.
198
199 3. Run a command like the following:
200
201 fc-xram -h c155 /dev/ttyUSB0 finlink/ramImage.srec rvinterf
202
203 If you are using an official FreeCalypso USB-serial cable from UberWaves,
204 you can speed up the code download by switching the serial line to 812500
205 baud:
206
207 fc-xram -h c155 -B 812500 /dev/ttyUSB0 finlink/ramImage.srec rvinterf
208
209 Adjust the paths to your /dev/ttyUSBx or other serial device and your
210 ramImage.srec as appropriate, and add rvinterf logging or other options as
211 desired. Specifying rvinterf on the fc-xram command line directs fc-xram to
212 exec rvinterf and pass the serial channel to it immediately as soon as the
213 code image has been loaded into target RAM and jumped to; this direct
214 passing of the serial channel from fc-xram to rvinterf is appropriate
215 because the loaded fw will immediately start emitting binary trace packets
216 in TI's RVTMUX format.
217
218 4. Momentarily press the red power button on the phone.
219
220 Once the phone executes its boot code with fc-xram running, the boot path will
221 be diverted and our experimental firmware will be loaded into target device RAM
222 and jumped to. Our fw will now run, and the rvinterf process on the host will
223 maintain communication with it.
224
225 Just like on the lower Mot/Compal subfamilies, we don't know how to extract the
226 factory-programmed IMEI and RF calibration data from Mot/Compal's proprietary
227 flash data structures, therefore, when our RAM-based firmware boots, it has no
228 IMEI and no RF calibration. Because this RAM-only configuration leaves the
229 flash completely alone and does not create a non-volatile FFS there, you will
230 need to set the IMEISV and RFCAP with fc-fsio on each boot. See the fc-fsio
231 commands given earlier, but skip the format command as the RAM-based FFS is
232 automatically formatted - but not otherwise initialized - upon firmware boot.