FreeCalypso > hg > freecalypso-citrine

comparison doc/Compal-Howto @ 28:cb00b90edaff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation write-ups imported from freecalypso-sw and updated for Citrine
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 12 Jun 2016 18:28:35 +0000
parents
children
comparison
equal deleted inserted replaced
27:3ecd6054a7f7 28:cb00b90edaff
1 FreeCalypso Citrine firmware on Mot C11x/12x and C139/140 families
2 ==================================================================
3
4 NOTE: this write-up refers specifically to our work-in-progress Citrine fw.
5 The tcs211-c139 hack which we have produced in late 2015 is an entirely
6 different animal.
7
8 Unlike tcs211-c139, Citrine can run equally "well" on both our preferred
9 C139/140 platform and the more primitive C11x/12x, but this fw is currently
10 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; Citrine currently has no UI code at all,
14 expecting control via AT commands via the same serial cable you use for
15 flashing it.
16
17 * TCS211 is TI's official production-quality firmware for the Calypso, whereas
18 our Citrine fw is only beginning to catch up to it - see the Current_Status
19 article for more information.
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
25 RAM was completely out of the question. Citrine currently has a lot less
26 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 Citrine for targets in this family
51 is 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 in the FreeCalypso host tools package for more
91 details. Once you are in with loadtool and have made a backup of your original
92 flash content, your first step will be to reflash sector 0 (the dangerous one)
93 with a version of the bootloader code that has been patched to transfer control
94 to the main fw image in the way we 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 can be downloaded here:
99
100 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/compal-flash-boot-for-fc.bin
101
102 It was made from one of Mot/Compal's original versions by applying a binary
103 patch to it; the source for this patch can be found in the retired
104 freecalypso-sw source repository on Bitbucket.
105
106 This step of replacing the bootloader needs to be done only once - you don't
107 need to reflash this dangerous sector again when you reflash the main fw image.
108 The patched FreeCalypso bootloader is also the same for both the present Citrine
109 fw and tcs211-c139.
110
111 The next step is to flash the main firmware image which you have just compiled:
112
113 loadtool> flash erase 0x10000 0x160000
114 loadtool> flash program-bin 0x10000 finlink/flashImage.bin
115
116 Note that the main fw image is flashed at 0x10000 on these targets. It is
117 flashed at 0 on sane targets with the Calypso boot ROM enabled in the hardware,
118 but Compal phones have malicious wiring in their PCBs that makes them brickable
119 and imposes the requirement of having working boot code in sector 0 at all
120 times, with the main fw image pushed down to 0x10000.
121
122 Finally, you should erase the flash region which you have allocated for the
123 aftermarket FFS:
124
125 loadtool> flash erase 0x3C0000 0x30000
126
127 or if your phone only has 2 MiB of flash:
128
129 loadtool> flash erase 0x1C0000 0x30000
130
131 Now you can close your loadtool session with an exit command, and the phone
132 will be cleanly powered off.
133
134 The next time you need to reflash another FreeCalypso image, get in with
135 loadtool like this:
136
137 fc-loadtool -h compal /dev/ttyXXX
138
139 There is no more need for tfc139 or for the inefficient -c 1003 option to
140 fc-loadtool once you've replaced the bootloader with compal-flash-boot-for-fc.
141 Once you are in loadtool, just reflash the main fw image, and leave the
142 bootloader and FFS sectors alone.
143
144 First boot of the firmware
145 ==========================
146
147 Connect the serial cable, but instead of running fc-loadtool, run rvinterf.
148 Press the red power button on the phone briefly just like you would for
149 fc-loadtool entry. Because there is no fc-loadtool running on the host end of
150 the serial cable, the boot path will *not* be diverted in the bootloader, and
151 the main fw image will run - and this time it will be the FreeCalypso firmware
152 you have compiled and flashed. The phone's LCD will remain dark as there is no
153 LCD driver code in this firmware, but you will see trace output in the rvinterf
154 window, telling you that the fw is running.
155
156 Before you do anything else, you will need to run fc-fsio and initialize the
157 aftermarket FFS for our firmware. When running on Openmoko GTA0x and Pirelli
158 DP-L10 targets, our fw can use the original factory-programmed IMEISV and RF
159 calibration values (partial in the case of the Pirelli), but on Mot/Compal
160 phones these factory data are stored in a format which we haven't been able to
161 grok, hence we cannot make use of them. Therefore, you will have to set your
162 own IMEISV manually, and the radio will run uncalibrated.
163
164 Initialize your aftermarket FFS as follows:
165
166 fsio> format /
167 fsio> mk-std-dirs
168 fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
169 fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
170 or
171 fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)
172
173 After you've initialized your FFS as above, you can exit fc-fsio, run fc-shell
174 and try some AT commands:
175
176 AT+CMEE=2 -- enable verbose error responses
177 AT+CFUN=1 -- enable radio and SIM interfaces
178 AT+COPS=0 -- register to the default GSM network
179
180 When you are done, you can power the phone off by sending a 'poweroff' command
181 through fc-shell. The only other way is to yank the battery, and doing the
182 latter is recommended anyway: when a phone with the present hack-firmware
183 flashed into it is powered off but still has the battery inserted, even a
184 momentary accidental press of the power button will cause it to power on and
185 boot, but there will be absolutely no visual indication, as the LCD stays dark.
186
187 FreeCalypso GSM firmware on Mot C155/156
188 ========================================
189
190 One major difference between Mot C155/156 and the other two subfamilies is that
191 C155 and C156 have 2 MiB of XRAM, which is large enough to allow our small-ish
192 experimental firmware to run entirely from RAM, without flashing, just like on
193 the Pirelli DP-L10.
194
195 If you are ready to play with our experimental GSM pseudo-modem fw on your
196 C155/156, the steps are as follows:
197
198 1. Build the firmware in the c155-gsm-ramonly configuration - see the
199 Compiling document for more details.
200
201 2. Connect your serial or USB-serial cable as usual; the phone needs to be
202 powered off at this point.
203
204 3. Run a command like the following:
205
206 fc-xram -h c155 /dev/ttyUSB0 finlink/ramImage.srec rvinterf
207
208 If you are using an official FreeCalypso USB-serial cable from UberWaves,
209 you can speed up the code download by switching the serial line to 812500
210 baud:
211
212 fc-xram -h c155 -B 812500 /dev/ttyUSB0 finlink/ramImage.srec rvinterf
213
214 Adjust the paths to your /dev/ttyUSBx or other serial device and your
215 ramImage.srec as appropriate, and add rvinterf logging or other options as
216 desired. Specifying rvinterf on the fc-xram command line directs fc-xram to
217 exec rvinterf and pass the serial channel to it immediately as soon as the
218 code image has been loaded into target RAM and jumped to; this direct
219 passing of the serial channel from fc-xram to rvinterf is appropriate
220 because the loaded fw will immediately start emitting binary trace packets
221 in TI's RVTMUX format.
222
223 4. Momentarily press the red power button on the phone.
224
225 Once the phone executes its boot code with fc-xram running, the boot path will
226 be diverted and our experimental firmware will be loaded into target device RAM
227 and jumped to. Our fw will now run, and the rvinterf process on the host will
228 maintain communication with it.
229
230 Just like on the lower Mot/Compal subfamilies, we don't know how to extract the
231 factory-programmed IMEI and RF calibration data from Mot/Compal's proprietary
232 flash data structures, therefore, when our RAM-based firmware boots, it has no
233 IMEI and no RF calibration. Because this RAM-only configuration leaves the
234 flash completely alone and does not create a non-volatile FFS there, you will
235 need to set the IMEISV and RFCAP with fc-fsio on each boot. See the fc-fsio
236 commands given earlier, but skip the format command as the RAM-based FFS is
237 automatically formatted - but not otherwise initialized - upon firmware boot.