FreeCalypso > hg > fc-magnetite

comparison README @ 373:9399a83cb394

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
first round of documentation updates for 2018
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 11 Jan 2018 22:44:09 +0000
parents cae495752cf7
children 56ac93768594
comparison
equal deleted inserted replaced
372:c389d938a50e 373:9399a83cb394
1 FreeCalypso Magnetite firmware project 1 FreeCalypso Magnetite firmware project
2 ====================================== 2 ======================================
3 3
4 This source tree contains yet another firmware offering created under the 4 As of A.D. 2018, FC Magnetite is the primary official Calypso firmware source
5 FreeCalypso umbrella. The key qualities of this firmware offering are: 5 tree for the FreeCalypso family of projects. This maintained and evolving
6 source can be built in many different configurations for several different
7 hardware targets, and is currently used in the following ways:
6 8
7 Negatives: 9 * The official production firmwares for our fully supported GSM+GPRS modem
10 products (FCDEV3B and the modem part of Openmoko devices) are built from
11 this source tree. See doc/Modem-configs for this mode of usage.
8 12
9 * Builds with TI's proprietary TMS470 compiler and thus requires Wine; 13 * The work in progress toward a future complete FreeCalypso phone handset
10 * Some of the fw components are still in the form of binary blobs - 14 (also known as a Libre Dumbphone) is being done in this source tree.
11 but see below on the deblobbing progress. 15 See doc/Handset-goal for more info about this project direction.
12 16
13 Positives: 17 * One can play with FreeCalypso and get a taste for it using certain hardware
14 18 that used to be readily available and which most people in the phone hacking
15 * Officially supports our own FCDEV3B and Openmoko GTA01/02 modem targets, 19 scene already have: Motorola C139 and Pirelli DP-L10. Firmware images of the
16 as well as "hack-only" support for Motorola C139 and Pirelli DP-L10, 20 "hacking toy" sort can be built for both of these models from the present
17 all from the same source tree; 21 source tree, and one can exercise most of the functions and capabilities of
18 22 FreeCalypso (with the notable exception of CSD and GPRS) on this historical
19 * Works as solidly as the TCS211 "golden" reference from TI, on all of the 23 but available-to-most-people hardware. See doc/C139-Howto, doc/Pirelli-Howto
20 supported targets - deep sleep works (on non-broken hardware), voice calls 24 and doc/Voice-pseudo-modem for more information.
21 work in all codec modes including AMR, the DSP dynamic download mechanism
22 does its magic, the call audio passes reliably in both directions.
23
24 The present FC Magnetite firmware is built on the principle of starting with
25 the known working TCS211 code base, without any major restructuring, and making
26 small incremental evolutionary changes, testing at every step to ensure that
27 nothing breaks. It is the direct opposite of the "rebuild from the ground up"
28 approach taken with our previous Citrine firmware aka "gsm-fw".
29 25
30 Functionality 26 Functionality
31 ============= 27 =============
32 28
33 TI's GSM mobile station firmware architecture supports two ways in which the 29 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 30 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 31 a local UI on devices with LCD & keypad hardware. (I said "and/or" because the
36 two mechanisms can coexist.) The code we got from TI (TCS211) is very solid 32 two mechanisms can coexist.) The code we got from TI (TCS211) is very solid
37 and mature in the modem configuration (control via AT commands only, no UI, no 33 and mature in the modem configuration (control via AT commands only, no UI, no
38 battery management, no traditional handset on/off control), but the additional 34 battery management, no traditional handset on/off control), but the additional
39 code layers that are needed for handset products but not for modems are in a 35 code layers that are needed for handset products but not for modems came in a
40 very rough "proof of concept" condition, nowhere close to a usable product. 36 very rough "proof of concept" condition, nowhere close to a usable product.
41 37
42 The same situation currently exists in FreeCalypso Magnetite. As explained 38 In FC Magnetite we further maintain and support the solid code base we got for
43 below in the Build system section, a key feature of FC Magnetite is that many 39 the modem functionality, and we are also working to improve the support for
44 different firmware configurations can be built from the same source tree. One 40 handset products and bring it into a practically usable state. We have already
45 of the configuration choices is that you can build the fw either with or without 41 implemented an entirely new battery charging and discharge monitoring driver
46 the phone UI layers. The work we have done earlier in the tcs211-c139 side 42 that actually works on our target hw (of the two we got from TI, one was
47 project (late 2015) has been integrated into Magnetite, properly conditionalized 43 bitrotten and the other was designed for charging hardware that is quite
48 so that TI's original configuration is fully preserved when the target != c139. 44 different from what we are working with), and we shall hopefully start working
49 However, if you build the UI-enabled configuration for any target other than 45 on the UI soon - see doc/Handset-goal for more info.
50 Mot C139, it will compile, but it won't do anything useful: it will try to
51 display TI's 176x220 pixel color UI on the D-Sample LCD on Calypso chip select
52 nCS3, but this hardware doesn't exist on any of our supported targets. (The
53 Pirelli in particular has flash on that chip select instead, so it may interfere
54 with FFS operation.)
55 46
56 Further work on the handset firmware configuration (UI, battery management and 47 Both TI's original modem fw (TCS211) and our recreation thereof in this
57 other currently missing functionality required for a usable phone) will have to 48 Magnetite project support not only voice calls and SMS, but also CSD, fax and
58 wait until we build our own Handset Motherboard Prototype (HSMBP) with a 176x220 49 GPRS. This advanced functionality is fully supported on our own GSM MS
59 pixel 16-bit color LCD, replicating TI's D-Sample - I personally am not too 50 development board (FCDEV3B), where both Calypso UARTs are presented directly to
60 interested in doing this handset fw work on the very crippled Mot C139 or on 51 the developer, as well as on the embedded Calypso modem in Openmoko GTA01/02
61 the Pirelli with its own host of issues, although others in the community are 52 smartphones, where the AT command channel with CSD, fax and GPRS capabilities
62 more than welcome to take a shot at it if someone is interested. 53 is connected to the phone's application processor.
63
64 Until then, the primary current focus of the FC Magnetite project is the
65 AT-command-controlled modem configuration. Both TI's original modem fw (TCS211)
66 and our recreation thereof in this Magnetite project support not only voice
67 calls and SMS, but also CSD, fax and GPRS. This advanced functionality is
68 fully supported on our own GSM MS development board (FCDEV3B), where both
69 Calypso UARTs are presented directly to the developer, as well as on the
70 embedded Calypso modem in Openmoko GTA01/02 smartphones, where the AT command
71 channel with CSD, fax and GPRS capabilities is connected to the phone's
72 application processor.
73 54
74 Build system 55 Build system
75 ============ 56 ============
76 57
77 Even though FC Magnetite is essentially unchanged TCS211 code base and builds 58 Even though FC Magnetite is essentially unchanged TCS211 code base and builds
115 Unix tool to all upper levels. 96 Unix tool to all upper levels.
116 97
117 As yet another defenestration measure, all source files are checked into this 98 As yet another defenestration measure, all source files are checked into this
118 tree with Unix line endings. 99 tree with Unix line endings.
119 100
120 Blob status 101 Two versions of the G23M protocol stack
102 =======================================
103
104 A major component of all functional firmware configurations is the mass of code
105 that implements layers 2 and 3 of the GSM+GPRS protocol stack, called G23M. In
106 FC Magnetite we have the option of using one of two different versions of this
107 key firmware component:
108
109 * The original G23M version from Openmoko: this version is believed to be very
110 stable because it has been used (successfully to the best of our knowledge)
111 by Openmoko, and it came from TI's TCS211 program that officially targeted
112 the Calypso chipset - but it exists only as binary object libraries with no
113 corresponding source. The lack of source means no ability to change the
114 feature configuration (what is enabled and what is disabled), very difficult
115 to debug if something does go wrong - all of the usual problems of software
116 without source.
117
118 * A newer version from TI's TCS3/LoCosto program. This version came to us in
119 the form of full C source, and because this fw component is chipset-
120 independent (unlike L1), we have successfully produced a TCS2/TCS3 hybrid in
121 which the new G23M code from TCS3.2 is grafted onto the chipsetsw foundation
122 from TCS211, which we have reconstructed into full C source form as well.
123
124 Each of the two G23M PS versions also has its own version of the Application
125 Control Interface (ACI) layer to go with it, which we call aci2 and aci3 -
126 except that in the case of ACI, we have the full source for both versions.
127
128 The new TCS2/TCS3 hybrid config is the way forward, as our goal is to have no
129 blobs in our firmware - having the full source is a prerequisite for maintaining
130 a software product. FC Magnetite supports building both configurations in order
131 to facilitate the transition, and as of this writing, we still need to add a few
132 bits to the new version of ACI in order to achieve 100% feature parity with
133 Openmoko.
134
135 Other blobs
121 =========== 136 ===========
122 137
123 A long-term FreeCalypso goal is to have our phone/modem firmware rebuild fully 138 The TCS2/TCS3 hybrid firmware is built almost entirely from source; the only
124 from source without any blobs, but this goal has not been achieved yet. While 139 components which are linked in the form of prebuilt libraries are GPF, Nucleus
125 we do have what *seems* to be a suitable replacement source (or feasible ability 140 and the TMS470 compiler's equivalent of libc/libgcc. It needs to be noted that
126 to reconstruct such) for every piece of TCS211 fw that came in binary-only form, 141 these components are so stable and configuration-independent that they were
127 actually making this replacement without breaking functionality is a very 142 used mostly in prebuilt library form even inside TI. In the case of GPF we've
128 non-trivial endeavor. Our previous attempt to rebuild the firmware from the 143 got the corresponding source for most of the modules within those libs; for the
129 ground up, using source pieces lifted from different available leaks and 144 few modules for which the original source has been lost, we've already done a
130 building with gcc so that no TMS470 COFF blobs could be used - see FreeCalypso 145 rough first-draft reconstruction as part of our previous gcc-built GSM fw
131 Citrine - has produced only a very limited subset of the original functionality, 146 efforts, and we only need to polish this reconstruction in order to have
132 and until very recently even the most basic function of voice calls did not work 147 deblobbed GPF in our mainline production fw. In the case of Nucleus we likewise
133 reliably. 148 have another version of it in full source form which has been proven good in
149 other FreeCalypso firmware projects.
134 150
135 Instead the new FreeCalypso firmware approach implemented in FC Magnetite is to 151 The planned successor to FC Magnetite (tentative planned name Selenite) will
136 approach the blob-free goal incrementally. The new Magnetite build system is 152 use the hybrid config for the G23M PS, deblobbed GPF and the source-enabled
137 specifically designed to enable the transition from the use of blobs to 153 version of Nucleus, resulting in blob-free firmware except for the proprietary
138 recompilation from source to be made with very fine granularity, down to the 154 TMS470 compiler and its equivalent of libc/libgcc. Transition to building with
139 level of individual object modules within libs if necessary. We tackle one 155 gcc (like in FreeCalypso Citrine) will follow afterward, completely exiting the
140 binary-only component at a time, either reconstructing the missing source from 156 land of blobs and proprietary build tools.
141 disassembly or adapting the source from a different version as works best in
142 each individual case, and we make a test build of the firmware using the
143 reconstructed or fitted component instead of the original blob. If the firmware
144 still works (doesn't break), we make this deblobbing transition permanent and
145 move on to the next component.
146
147 See doc/Modem-configs for the current status of the deblobbing effort and for
148 the description of the currently available configurations.
149 157
150 Further reading 158 Further reading
151 =============== 159 ===============
152 160
153 For various instructions and notes specific to this FreeCalypso Magnetite 161 For various instructions and notes specific to this FreeCalypso Magnetite