FreeCalypso > hg > fc-magnetite

comparison README @ 94:596d86109e44

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial round of documentation
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 03 Oct 2016 04:26:16 +0000
parents
children 9fb9f896bd77
comparison
equal deleted inserted replaced
93:6475bde1b170 94:596d86109e44
1 FreeCalypso Magnetite firmware project
2 ======================================
3
4 This source tree contains yet another firmware offering created under the
5 FreeCalypso umbrella. The key qualities of this firmware offering are:
6
7 Negatives:
8
9 * Builds with TI's proprietary TMS470 compiler and thus requires Wine;
10 * Some of the fw components are still in the form of binary blobs -
11 but see below on the deblobbing progress.
12
13 Positives:
14
15 * Can be built to run on Motorola C139, Openmoko GTA02 and Pirelli DP-L10
16 targets, as well as the to-be-built FCDEV3B, all from the same source tree;
17
18 * Works as solidly as the TCS211 "golden" reference from TI, on all of the
19 supported targets - deep sleep works, voice calls work in all codec modes
20 including AMR, the DSP dynamic download mechanism does its magic, the call
21 audio passes reliably in both directions.
22
23 The present FC Magnetite firmware is built on the principle of starting with
24 the known working TCS211 code base, without any major restructuring, and making
25 small incremental evolutionary changes, testing at every step to ensure that
26 nothing breaks. It is the direct opposite of the "rebuild from the ground up"
27 approach taken with our previous Citrine firmware (aka "gsm-fw"), the approach
28 that produced very disappointing results.
29
30 Functionality
31 =============
32
33 TI's GSM mobile station firmware architecture supports two ways in which the
34 GSM device may be controlled: via AT commands from an external host and/or via
35 a local UI on devices with LCD & keypad hardware. (I said "and/or" because the
36 two mechanisms can coexist.) At the present time, however, only the AT command
37 mode of operation is supported in FreeCalypso Magnetite. The effect of this
38 limitation is that if you run this fw on a Motorola C139 or a Pirelli DP-L10,
39 the phone's LCD will stay dark, the buttons won't do anything, and the
40 phone-turned-modem can only be operated via AT commands sent via FreeCalypso
41 host utility fc-shell.
42
43 The demo/prototype phone UI code in TI's reference fw delivery is written for
44 a 176x220 pixel 16-bit color LCD (such an LCD was used on TI's official
45 development platform called D-Sample), whereas our available Mot C139 and
46 Pirelli targets have significantly smaller LCDs: 96x64 and 128x128 pixels,
47 respectively. Prior to the D-Sample, TI had used 84x48 pixel black&white
48 (1 bit per pixel) LCDs, and this old C-Sample LCD code is still there, albeit
49 bitrotten. In late 2015 this author made a very dirty hack to resurrect TI's
50 old C-Sample UI code and get it to display on the C139 phone LCD (84x48 is a
51 proper subset of 96x64) - you can find this hack in the tcs211-c139 Hg tree.
52
53 The upshot of this LCD situation is that porting TI's phone UI code to run on
54 Mot C139 or Pirelli DP-L10 will require major rework of the affected parts of
55 the firmware. While I would like to do it eventually, I am not willing to do
56 it right now - I would like to get this code running in its pristine state on
57 its native 176x220 pix LCD *before* I hack the holy **** out of it for the
58 C139/Pirelli port. I do have a real TI-made D-Sample kit with the right LCD,
59 but unfortunately the main board has an older version of the core chipset for
60 which we lack the necessary fw support, hence it doesn't help. Therefore, we
61 will need to build our own Calypso board with a 176x220 pix 16-bit color LCD,
62 get the UI-enabled GSM firmware running on that board, and only then proceed
63 with C139 and/or Pirelli ports if such are still desired.
64
65 For now, modem or pseudo-modem operation with control via AT commands is all
66 we have.
67
68 Build system
69 ============
70
71 Even though FC Magnetite is essentially unchanged TCS211 code base and builds
72 using TI's proprietary TMS470 compiler under Wine, the build system is entirely
73 new. TI's TCS211 build system, called BuSyB, works by way of a Java tool
74 generating a customized makefile for each desired build configuration, based on
75 lots of magic contained in a big repository of XML files. There also a bunch
76 of Perl scripts involved. The Java tool that does the heavy lifting exists
77 only as compiled Java bytecode sans source, and the surrounding Perl scripts
78 aren't very understandable either. And the whole thing thoroughly assumes a
79 Windows environment (drive letters, backslashes, case-insensitive file system)
80 throughout. As a result, when working with TCS211 fw with its original build
81 system, we had to treat these BuSyB-generated makefiles almost as being blobs in
82 themselves: regenerating a makefile from XML magic required major effort, there
83 were some bugs in the makefile generation which we couldn't fix and thus we had
84 to edit the makefiles manually after each regeneration - it was an utter mess,
85 and absolutely not an acceptable way to build a forward-looking, community-
86 serving project.
87
88 In FC Magnetite I have recreated the relevant parts of the TCS211 build system,
89 using Bourne shell magic instead of Java and XML. Just like TI's BuSyB, ours
90 is a makefile generation system: in order to compile the firmware in a
91 particular desired configuration, you run a shell script to select the config
92 you would like. This shell script will create a dedicated build directory tree
93 to fully contain this build, and populate it with generated Makefiles and some
94 other bits - then you go into the just-created build directory and run make
95 there. The source and build trees are thus cleanly separated. See
96 doc/Compiling for detailed instructions.
97
98 Another key difference from our previous TCS211-based firmware offerings is that
99 even though we still have to run TI's compiler binaries under Wine, the Wine
100 invokation has been moved from the top (root) of the build process to the
101 bottom leaves. With our previous TCS211-based works you would run Wine at the
102 top, and then the entire build process would proceed in the Windows environment,
103 using Windows versions of make and other nonsense. Not so in FC Magnetite:
104 in this firmware project all shell scripts, Makefiles, Perl scripts and other
105 build system accessories run at the native Unix level, and Wine is only invoked
106 at the lowest level by individual tool wrappers: for example, TI's compiler
107 binary cl470.exe is encapsulated in a Unix shell script called cl470 that
108 invokes Wine to run the Windows binary, presenting the illusion of a native
109 Unix tool to all upper levels.
110
111 As yet another defenestration measure, all source files are checked into this
112 tree with Unix line endings.
113
114 Blob status
115 ===========
116
117 A long-term FreeCalypso goal is to have our phone/modem firmware rebuild fully
118 from source without any blobs, but this goal has not been achieved yet. While
119 we do have what *seems* to be a suitable replacement source (or feasible ability
120 to reconstruct such) for every piece of TCS211 fw that came in binary-only form,
121 actually making this replacement without breaking functionality is a very
122 non-trivial endeavor. Our previous attempt to rebuild the firmware from the
123 ground up, using source pieces lifted from different available leaks and
124 building with gcc so that no TMS470 COFF blobs could be used, produced very
125 disappointing results.
126
127 Instead the new FreeCalypso firmware approach implemented in FC Magnetite is to
128 approach the blob-free goal incrementally. The new Magnetite build system is
129 specifically designed to enable the transition from the use of blobs to
130 recompilation from source to be made with very fine granularity, down to the
131 level of individual object modules within libs if necessary. We tackle one
132 binary-only component at a time, either reconstructing the missing source from
133 disassembly or adapting the source from a different version as works best in
134 each individual case, and we make a test build of the firmware using the
135 reconstructed or fitted component instead of the original blob. If the firmware
136 still works (doesn't break), we make this deblobbing transition permanent and
137 move on to the next component.
138
139 As of this writing, most of Layer 1 and a few housekeeping parts of the fw have
140 already been deblobbed, i.e., are now recompiled from source. The G23M protocol
141 stack is our next deblobbing target - we have a newer version of it in full
142 source form, and we are hoping to be able to retrofit this newer G23M version
143 into the TCS211 environment in order to replace the binary blob version we are
144 using currently.
145
146 Further reading
147 ===============
148
149 For various instructions and notes specific to this FreeCalypso Magnetite
150 firmware, look in the doc directory. For more information about the overall
151 FreeCalypso project and our hardware building aspirations, go to our website:
152
153 https://www.freecalypso.org/