FreeCalypso > hg > freecalypso-docs

comparison Handset-UI-fw @ 0:fcd1cf531017

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
TCS211-fw-arch masterpiece written
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 08 Oct 2018 19:52:50 +0000
parents
children 2e9719074e79
comparison
equal deleted inserted replaced
-1:000000000000 0:fcd1cf531017
1 The present article is a companion to the TCS211 firmware architecture document
2 (TCS211-fw-arch). Those who are interested in the FreeCalypso phone handset
3 goal (which is currently a very distant goal) should read the TCS211-fw-arch
4 document first and then this article, whereas those who are more interested in
5 the rock solid FreeCalypso modem (as opposed to handset) solution which is
6 already available today and would like to understand our modem fw better only
7 need to read the TCS211-fw-arch document and can safely skip this handset UI
8 addendum.
9
10 TI's offerings for handset UI
11 =============================
12
13 Unlike their rock solid, full commercial product offering for AT-command-
14 controlled modems, TI never produced a reference phone handset firmware
15 implementation that could be used as-is with minimal or no changes: instead
16 they provided a very rough proof-of-concept implementation which is nowhere
17 close to usable, and left it up to their customers (handset manufacturers) to
18 whip it into even a minimally decent shape. Furthermore, they had several
19 different approaches over the years to what the GSM industry calls by the
20 sexist term "MMI":
21
22 * They once had something called SMI, for "simple MMI" or "slim MMI". We have
23 what appears to be the complete source for this SMI component as part of the
24 MV100-0.1.rar and 94140216gsm.rar finds, but both of those finds are just
25 broken fragments, not a complete firmware for any target. It might be
26 possible to integrate this unknown-origin SMI source into Magnetite and get
27 it to work with the TCS2 version of ACI, but no such feat has been attempted
28 yet - it would be a mere curiosity, not something for practical use.
29
30 * SMI later gave way to a successor called BMI for "basic MMI", which is much
31 bigger in terms of code size and complexity and consists of two layers: there
32 is a layer called MFW (mobile framework) that sits on top of ACI, and then
33 BMI proper sits on top of MFW. This incarnation of TI's demo/prototype phone
34 UI is the one which they officially supported in the TCS211 program, and our
35 copy of TCS211 from OM miraculously has these BMI+MFW sources included, even
36 though OM obviously didn't use this code and could not even compile it without
37 doing some surgery on the build system. Our other TCS3.2/LoCosto source also
38 has BMI and MFW matching that newer version of G23M ACI and PS components,
39 and we use this new TCS3 version of BMI+MFW in our TCS2/TCS3 hybrid config.
40
41 * It appears that TI once had or were trying to develop some kind of Riviera-
42 based "MMI" code as an alternative to the Condat-based SMI and BMI. SMI and
43 BMI+MFW execute in the same "MMI" GPF task as ACI and communicate with it
44 through direct function calls; in contrast, the alternative Riviera MMI would
45 run somewhere in Riviera land and communicate with ACI through ATP and some
46 kind of ACI adapter. We never got any of this code, and it is not clear if
47 it was ever a reality beyond just the idea.
48
49 In any case, it is clear from the code that TI's SSA group in France who
50 developed the drivers for various Calypso chipset peripherals including LCDs,
51 keypads and ringing buzzers on their development boards and the Condat UK group
52 who did SMI and BMI had very different visions and ideas. Some examples:
53
54 * The Calypso DSP has a built-in mechanism for playing quite pleasant-sounding
55 ringtone melodies through a loudspeaker driven by the chipset's ABB, and the
56 SSA group developed their RiViera Audio Service front-end to these L1+DSP
57 audio services, but Condat's code makes absolutely minimal use of this RV
58 Audio Service, just enough to be compatible with it, and does not use any of
59 the melody functions, neither E1 nor E2.
60
61 * In the original TCS211 architecture before LoCosto changes, the driver for
62 the physical LCD was/is R2D in the Riviera/SSA land. R2D provides a very rich
63 set of text and graphics drawing primitives, but Condat's display layer does
64 not use any of them: instead they obtain the raw framebuffer address from R2D
65 and do all drawing operations themselves.
66
67 * The TCS211 code we got had a jaw-dropping bug in the code path for ringing
68 the piezoelectric buzzer: due to a miscommunication between the French folks
69 in charge of the actual buzzer driver in chipsetsw and the German or UK folks
70 in charge of Condat's audio layer, the buzzer always rang at some 99 Hz (its
71 lowest possible frequency, horrible on ears) no matter what tone frequency
72 was intended. Given that our copy of TCS211 dates from 2007 and considering
73 how old the buzzer function must be, it hurts to think for how many years
74 that bug sat there without anyone wondering why ringing sounds so horrible.
75
76 In terms of the code architecture, none of Condat's UI code ever calls any of
77 the actual drivers in the SSA realm directly: instead everything goes through
78 the Condat drivers layer in condat/com/src/driver, and that layer provides a
79 very poor adaptation as highlighted above.
80
81 LCD support
82 ===========
83
84 TI's demo/prototype UI code never supported a wide variety of different display
85 sizes or keypad layouts - instead they only supported whatever existed on their
86 in-house development boards at each given point in their history. TI's C-Sample
87 and earlier development boards had 84x48 pixel B&W displays, whereas from
88 D-Sample onward they made the big jump to a 176x220 pixel color LCD. Both
89 versions of the UI we got (TCS211 targeting D-Sample and TCS3.2 targeting
90 I-Sample, TI's LoCosto board) were developed on 176x220 pixel color LCD
91 platforms, and that is the only display size which they intended to support.
92 There also exists a remnant of support for their earlier 84x48 pixel C-Sample
93 LCD, which we resurrected in FreeCalypso to see it run on Mot C139 hardware,
94 but that support was broken: it would not even compile without our fixes. In
95 our current FC Magnetite firmware we can build this C-Sample UI version for the
96 C139 target and it works in the demo / proof-of-concept sense, but it is likely
97 to be even more broken than the official 176x220 pixel version.
98
99 Anyone interested in adding support for a different LCD will need to start with
100 the R2D driver under src/cs/drivers/drv_app/r2d. The principal LCD type
101 selection is done in r2d_config.h (C-Sample and D-Sample are the only options
102 supported by the version we got with TCS211), and this selection affects all of
103 R2D and all of its clients. Our change to this r2d_config.h LCD type selection
104 logic consists of selecting C-Sample instead of D-Sample when the build target
105 is C139. A secondary selection is made in r2d_inits.c and r2d_refresh.c where
106 the code snippets for the actual hardware initialization and output are
107 included: the way we currently support the C139 hw target is a very thorough
108 emulation of the C-Sample including its vertical B&W framebuffer format, all of
109 the code in R2D and in Condat's display driver sees a real C-Sample LCD, and
110 only the hardware-poking code is substituted.
111
112 The direct implication of our C-Sample emulation approach for the C139 LCD is
113 that the full 96x64 pixel size of Motorola's LCD becomes completely
114 inaccessible, and all software sees a 84x48 pixel subset. The same happens
115 with color: because TI's C-Sample LCD was B&W, the color capabilities of the
116 real C139 LCD become inaccessible. Anyone who wishes to fix this shortcoming
117 would need to implement a new bona fide LCD type in R2D, and then adapt
118 Condat's display driver accordingly.
119
120 Condat's display driver (condat/com/src/driver/display.c) is very messy and
121 very difficult to understand. The only change we have made to it in FreeCalypso
122 was fixing the support for the C-Sample LCD which was bitrotten: the bitrot and
123 our fix for it is not specific to the C139, it would affect a real C-Sample
124 board just as well. Understanding this code well enough to extend it to other
125 LCD geometries and framebuffer formats would be a much greater challenge.
126
127 Above Condat's display driver lies the actual UI implementation in BMI and MFW.
128 This UI code supports only 3 possible configurations:
129
130 * Both COLOURDISPLAY and LSCREEN defined: the display is 176x220 color;
131
132 * LSCREEN is defined but not COLOURDISPLAY: the display is 176x220 B&W - TI
133 used this config when building "GSM Lite" fw for the D-Sample;
134
135 * Neither LSCREEN nor COLOURDISPLAY defined: the old 84x48 pixel B&W UI from
136 the days of C-Sample and earlier.
137
138 Note the lack of support for small color displays like the one on the C139.
139
140 Text fonts
141 ----------
142
143 The SSA group's R2D driver provides text display functions and contains its own
144 fonts, but Condat's stuff does not use those display functions or fonts -
145 instead BMI and MFW (and presumably SMI too) use a different font/text
146 implementation contained in the Condat drivers layer.
147
148 Keypad support
149 ==============
150
151 The hardware keypad driver is KPD in Riviera/SSA land, residing in
152 chipsetsw/drivers/drv_app/kpd in TCS211 or in src/cs/drivers/drv_app/kpd in
153 Magnetite and Selenite. Unlike the display driver R2D, KPD is always included
154 even in modem firmware builds - but if there is no keypad connected to the
155 Calypso, it does nothing. TI's firmware architecture and UI code support only
156 traditional numeric keypads - there is no provision for supporting a full QWERTY
157 keyboard. However, if the keypad layout on a given phone handset is close
158 enough to what TI had on their development boards, modifying KPD for the
159 specific wiring is very easy: we have already added proper support for Mot C1xx
160 and Pirelli DP-L10 keypads.
161
162 Battery monitoring and charging
163 ===============================
164
165 TI had two incarnations of their battery charging and monitoring driver: first
166 PWR, then LCC. Both were implemented in Riviera/SSA land. LCC was not a good
167 fit for our targets of interest (Mot C1xx, Pirelli DP-L10 and our desired
168 FreeCalypso Libre Dumbphone hardware) while PWR had other problems, so we
169 retired both of them and wrote our own replacement called FCHG.
170
171 There is a quirk, however: there is no connection in the TCS211 code as
172 delivered by TI between their demo/prototype UI (or rather between Condat's
173 power driver stub) and either of their battery driver implementations. At the
174 time of TCS211-2007 the original PWR driver had already been retired and only
175 LCC was supported, but even that LCC driver had no connection to the UI: one
176 could remove it from the fw build configuration and the UI code would still
177 compile and link just fine, which would not be possible if there were any calls
178 to LCC's API functions. The practical effect of this quirk is that there is no
179 need to resurrect PWR or LCC in order to run TI's UI code in its pristine
180 original form - using our own FCHG or no battery management driver at all is
181 just as fine.
182
183 The proper way to get proper support for Mot C139
184 =================================================
185
186 I (Mother Mychaela) feel very strongly that the best way to produce practically
187 usable end user FreeCalypso firmware for the C139 target would be to do it
188 together with our own FreeCalypso Libre Dumbphone development, as opposed to
189 trying to support the C139 to the exclusion of our own FreeCalypso hardware.
190 Specifically, I propose the following order of steps:
191
192 1) First build our own FreeCalypso UI development board, a derivative of the
193 FCDEV3B adding a 176x220 pixel color LCD and other miscellany to serve as a
194 replacement for TI's D-Sample.
195
196 2) Retire the C-Sample UI configuration and our currently implemented C-Sample
197 emulation hack on the C139, and start running TI's UI code the way TI's own
198 developers ran it on the D-Sample.
199
200 3) Change the "small screen" UI layout from 84x48 to 96x64 pixels (from 6 rows
201 of 14 characters to 8 rows of 16 characters with TI's existing font), and
202 fix the bugs related to displaying this "small screen" (!LSCREEN) UI on a
203 physically larger LCD - we would like to display it on our 176x220 pixel UI
204 development board.
205
206 4) Extend the UI code to allow the possibility of COLOURDISPLAY && !LSCREEN,
207 i.e., a small (96x64 pixels) color display like on the C139. Have this
208 96x64 pixel color UI displayed on our 176x220 pixel UI development board.
209
210 5) Work on getting the actual UI into shape, keeping the two configurations of
211 176x220 pixel color (future FreeCalypso Libre Dumbphone) and 96x64 pixel
212 color (Mot C139) as actively supported ones. Do all development on our
213 176x220 pixel UI development board.
214
215 6) Once the UI-enabled firmware works decently on our development board in both
216 176x220 and 96x64 configurations, add native C139 LCD support (not C-Sample
217 emulation) to R2D, adapt Condat's display driver as necessary if we are still
218 using it (if we don't find a way to get rid of it by this point), and run
219 our 96x64 pixel color UI config on real C139 hardware. At this point we
220 should have practically usable end user FreeCalypso fw on the C139.
221
222 7) While the less demanding and more casual phone users will be happy with the
223 feeble C139 if it runs our FreeCalypso fw, those of us who desire the
224 Ultimate Awesome Libre Dumbphone will be able to take our 176x220 pixel UI
225 development board and start turning it into an actual FreeCalypso Libre
226 Dumbphone handset. This will be the point when we can move the ringtone
227 output from the piezo buzzer to the loudspeaker (Melody E1) and start making
228 other changes for better-than-C139 hardware.
229
230 Of course the biggest difficulty with the above plan is that it requires
231 designing and building a new piece of hardware as its very first critical step.
232 My personal plan is to kill two birds with one stone: design the board in such
233 a way that it can be used both as a development board for the above plan and as
234 a close-to-final prototype for my desired FC Libre Dumbphone handset - although
235 not completely final, as this board would absolutely need to be usable in its
236 bare form on a lab bench without plastics, which calls for a somewhat different
237 design than a final handset product.
238
239 Anyone who disagrees with my approach, anyone who is against designing and
240 building new custom hardware at high cost and who is instead interested first
241 and foremost in pre-existing hardware targets like Mot C139 is more than welcome
242 to delve into the code themselves and try their own hand at fixing the code to
243 make it practically usable on the C139. However, I have to warn you: if you
244 spend a significant amount of time working with TI's code and develop an
245 affection for it, it is quite possible that you will start to feel the way I do
246 in terms of desiring a D-Sample-like platform for development.
247
248 Why Mot C139?
249 =============
250
251 Out of the known repertoire of pre-existing Calypso-based phones whose existence
252 has been discovered by OsmocomBB and for which we already have some foundations
253 of support in FreeCalypso, Mot C139 is the most suitable one for the purpose of
254 turning it into a Libre Dumbphone by way of aftermarket firmware. Here are the
255 problems with the other ones:
256
257 * Pirelli DP-L10 is my absolute favourite with an end user hat on, but the
258 unwanted extra chips for the unwanted-for-us WLAN and camera functionality
259 are a killer. There are no schematics for the phone and no documentation for
260 any of these chips, and we don't know how to power them down. In a fully
261 quiescent state with all Calypso sleep modes enabled and with both LCD and
262 keypad backlights off, the board still draws about 87 mA from the battery,
263 which will kill a fully charged battery in about 10 hours of complete idle.
264 Furthermore, it is not possible to turn on the loudspeaker without going
265 through the W56940 ringtone chip, and the reset line for this chip comes from
266 a GPIO on the completely undocumented camera chip - thus without a way to
267 control this reset line we may not be able to program the W56940, and without
268 that programming we may not be able to turn on the loudspeaker, ruining all
269 usefulness of this phone.
270
271 * Mot C11x/12x family is good in terms of not having any undocumented hardware,
272 but the tiny RAM capacity is a bummer. These lowest-end phones have only
273 256 KiB of IRAM (Calypso internal RAM) and 256 KiB of XRAM (board-level RAM),
274 whereas the next-step-up C139/140 has 512 KiB of XRAM. It is a significant
275 difference for us: while we fit into C139's 512 KiB with no sweat, it would
276 require some very unpleasant and unrewarding work to trim the fat and
277 reshuffle our memory usage to fit into the 256+256 arrangement on C11x.
278 Furthermore, most C11x/12x phones have only 2 MiB of flash, which would again
279 require major contortions to fit into, whereas all C139/140 phones have 4 MiB.
280
281 * Mot C155/156 seem nice, but there is a problem: these phones ring with a
282 loudspeaker driven by a ringtone generator chip instead of a piezo buzzer
283 driven by the Calypso, and their ringtone generator chip is Sunplus SPMA100B.
284 No documentation could be found for that chip, and if we can't program it, we
285 won't be able to make the phone ring or operate its loudspeaker in any other
286 way. Furthermore, the LCD controller in these phones is much less obvious
287 than the one in the C139/140.