FreeCalypso > hg > fc-magnetite

annotate README @ 527:343104963a7f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Developer-notes written
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 09 Oct 2018 08:09:53 +0000
parents f9125919bbe4
children 39a226a06196
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 FreeCalypso Magnetite firmware project
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 ======================================
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
4 As of A.D. 2018, FC Magnetite is the primary official Calypso firmware source
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
5 tree for the FreeCalypso family of projects. This maintained and evolving
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
6 source can be built in many different configurations for several different
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
7 hardware targets, and is currently used in the following ways:
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
9 * The official production firmwares for our fully supported GSM+GPRS modem
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
10 products (FCDEV3B and the modem part of Openmoko devices) are built from
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
11 this source tree. See doc/Modem-configs for this mode of usage.
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
13 * The work in progress toward a future complete FreeCalypso phone handset
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
14 (also known as a Libre Dumbphone) is being done in this source tree.
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
15 See doc/Handset-goal for more info about this project direction.
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
17 * One can play with FreeCalypso and get a taste for it using certain hardware
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
18 that used to be readily available and which most people in the phone hacking
384
56ac93768594 README: update for C11x support
Mychaela Falconia <falcon@freecalypso.org>
parents: 373
diff changeset
19 scene already have: Motorola C1xx and Pirelli DP-L10. Firmware images of the
56ac93768594 README: update for C11x support
Mychaela Falconia <falcon@freecalypso.org>
parents: 373
diff changeset
20 "hacking toy" sort can be built for these devices from the present source
56ac93768594 README: update for C11x support
Mychaela Falconia <falcon@freecalypso.org>
parents: 373
diff changeset
21 tree, and one can exercise most of the functions and capabilities of
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
22 FreeCalypso (with the notable exception of CSD and GPRS) on this historical
384
56ac93768594 README: update for C11x support
Mychaela Falconia <falcon@freecalypso.org>
parents: 373
diff changeset
23 but available-to-most-people hardware. See doc/C1xx-Howto, doc/Pirelli-Howto
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
24 and doc/Voice-pseudo-modem for more information.
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25
462
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
26 * If anyone besides the Mother has an original TI-made D-Sample hardware kit
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
27 for Calypso software development, we are doing the best we can to support
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
28 running our FreeCalypso firmware on this original TI hardware - see
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
29 doc/D-Sample for more information.
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
30
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 Functionality
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 =============
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 TI's GSM mobile station firmware architecture supports two ways in which the
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 GSM device may be controlled: via AT commands from an external host and/or via
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 a local UI on devices with LCD & keypad hardware. (I said "and/or" because the
512
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
37 two mechanisms can coexist.) The code we got from TI (TCS211 and TCS3.2) is
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
38 very solid and mature in the modem configuration (control via AT commands only,
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
39 no UI, no battery management, no traditional handset on/off control), but the
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
40 additional code layers that are needed for handset products but not for modems
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
41 came in a very rough "proof of concept" condition, nowhere close to a usable
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
42 product.
218
75ea63a3fce5 README updated for the current status of the project
Mychaela Falconia <falcon@freecalypso.org>
parents: 96
diff changeset
43
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
44 In FC Magnetite we further maintain and support the solid code base we got for
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
45 the modem functionality, and we are also working to improve the support for
512
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
46 handset products and bring it into a practically usable state. At the present
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
47 time the handset firmware work is on hold, paused until we design and build the
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
48 first prototype version of our own FreeCalypso handset hardware. The reason
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
49 for this hold is that we are not able to use TI's original development board
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
50 (see doc/D-Sample for the issues), hence we need to build our own hardware that
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
51 will serve in its place. Until then we focus on maintaining and supporting the
1edb0615c439 README: state more clearly that the handset fw work is paused
Mychaela Falconia <falcon@freecalypso.org>
parents: 484
diff changeset
52 good working modem functionality.
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
54 Both TI's original modem fw (TCS211) and our recreation thereof in this
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
55 Magnetite project support not only voice calls and SMS, but also CSD, fax and
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
56 GPRS. This advanced functionality is fully supported on our own GSM MS
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
57 development board (FCDEV3B), where both Calypso UARTs are presented directly to
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
58 the developer, as well as on the embedded Calypso modem in Openmoko GTA01/02
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
59 smartphones, where the AT command channel with CSD, fax and GPRS capabilities
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
60 is connected to the phone's application processor.
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 Build system
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 ============
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 Even though FC Magnetite is essentially unchanged TCS211 code base and builds
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 using TI's proprietary TMS470 compiler under Wine, the build system is entirely
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 new. TI's TCS211 build system, called BuSyB, works by way of a Java tool
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 generating a customized makefile for each desired build configuration, based on
96
9fb9f896bd77 README: grammar fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
69 lots of magic contained in a big repository of XML files. There are a bunch of
9fb9f896bd77 README: grammar fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
70 Perl scripts involved as well. The Java tool that does the heavy lifting exists
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 only as compiled Java bytecode sans source, and the surrounding Perl scripts
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 aren't very understandable either. And the whole thing thoroughly assumes a
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 Windows environment (drive letters, backslashes, case-insensitive file system)
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 throughout. As a result, when working with TCS211 fw with its original build
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 system, we had to treat these BuSyB-generated makefiles almost as being blobs in
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 themselves: regenerating a makefile from XML magic required major effort, there
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 were some bugs in the makefile generation which we couldn't fix and thus we had
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 to edit the makefiles manually after each regeneration - it was an utter mess,
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 and absolutely not an acceptable way to build a forward-looking, community-
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 serving project.
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 In FC Magnetite I have recreated the relevant parts of the TCS211 build system,
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 using Bourne shell magic instead of Java and XML. Just like TI's BuSyB, ours
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 is a makefile generation system: in order to compile the firmware in a
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 particular desired configuration, you run a shell script to select the config
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 you would like. This shell script will create a dedicated build directory tree
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 to fully contain this build, and populate it with generated Makefiles and some
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 other bits - then you go into the just-created build directory and run make
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 there. The source and build trees are thus cleanly separated. See
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 doc/Compiling for detailed instructions.
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 Another key difference from our previous TCS211-based firmware offerings is that
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 even though we still have to run TI's compiler binaries under Wine, the Wine
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 invokation has been moved from the top (root) of the build process to the
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 bottom leaves. With our previous TCS211-based works you would run Wine at the
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 top, and then the entire build process would proceed in the Windows environment,
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 using Windows versions of make and other nonsense. Not so in FC Magnetite:
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 in this firmware project all shell scripts, Makefiles, Perl scripts and other
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 build system accessories run at the native Unix level, and Wine is only invoked
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 at the lowest level by individual tool wrappers: for example, TI's compiler
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 binary cl470.exe is encapsulated in a Unix shell script called cl470 that
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 invokes Wine to run the Windows binary, presenting the illusion of a native
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 Unix tool to all upper levels.
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 As yet another defenestration measure, all source files are checked into this
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 tree with Unix line endings.
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
108 Two versions of the G23M protocol stack
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
109 =======================================
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
110
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
111 A major component of all functional firmware configurations is the mass of code
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
112 that implements layers 2 and 3 of the GSM+GPRS protocol stack, called G23M. In
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
113 FC Magnetite we have the option of using one of two different versions of this
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
114 key firmware component:
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
115
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
116 * The original G23M version from Openmoko: this version is believed to be very
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
117 stable because it has been used (successfully to the best of our knowledge)
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
118 by Openmoko, and it came from TI's TCS211 program that officially targeted
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
119 the Calypso chipset - but it exists only as binary object libraries with no
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
120 corresponding source. The lack of source means no ability to change the
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
121 feature configuration (what is enabled and what is disabled), very difficult
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
122 to debug if something does go wrong - all of the usual problems of software
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
123 without source.
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
124
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
125 * A newer version from TI's TCS3/LoCosto program. This version came to us in
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
126 the form of full C source, and because this fw component is chipset-
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
127 independent (unlike L1), we have successfully produced a TCS2/TCS3 hybrid in
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
128 which the new G23M code from TCS3.2 is grafted onto the chipsetsw foundation
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
129 from TCS211, which we have reconstructed into full C source form as well.
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
130
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
131 Each of the two G23M PS versions also has its own version of the Application
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
132 Control Interface (ACI) layer to go with it, which we call aci2 and aci3 -
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
133 except that in the case of ACI, we have the full source for both versions.
462
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
134 Furthermore, in the case of firmware builds that have the phone UI layers
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
135 enabled (BMI and MFW, sitting on top of ACI), we likewise have different TCS2
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
136 and TCS3 versions of these BMI and MFW layers, also with full source for both
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
137 versions. Thus the chipsetsw foundation is always the same TCS211, but then we
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
138 bifurcate: we can build either a pure TCS211 config using TCS211 versions of
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
139 G23M PS (blobs), ACI (source) and MFW+BMI (source), or a TCS2/TCS3 hybrid config
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
140 using the new TCS3 versions of G23M PS, ACI and MFW+BMI, all in full C source
78e19122fa2b README: update for D-Sample target support and hybrid UI
Mychaela Falconia <falcon@freecalypso.org>
parents: 384
diff changeset
141 form.
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
142
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
143 The new TCS2/TCS3 hybrid config is the way forward, as our goal is to have no
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
144 blobs in our firmware - having the full source is a prerequisite for maintaining
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
145 a software product. FC Magnetite supports building both configurations in order
484
a1946652f71c top README: update for the status of hybrid firmware
Mychaela Falconia <falcon@freecalypso.org>
parents: 462
diff changeset
146 to facilitate the transition. As of this writing, the hybrid config is believed
a1946652f71c top README: update for the status of hybrid firmware
Mychaela Falconia <falcon@freecalypso.org>
parents: 462
diff changeset
147 to have reached feature parity with Openmoko-mimicking classic and l1reconst
a1946652f71c top README: update for the status of hybrid firmware
Mychaela Falconia <falcon@freecalypso.org>
parents: 462
diff changeset
148 configs, i.e., unless we missed or broke something, every feature that worked
a1946652f71c top README: update for the status of hybrid firmware
Mychaela Falconia <falcon@freecalypso.org>
parents: 462
diff changeset
149 correctly on Openmoko's original modem should work just as well with our hybrid
a1946652f71c top README: update for the status of hybrid firmware
Mychaela Falconia <falcon@freecalypso.org>
parents: 462
diff changeset
150 firmware. All functionality (both standard and OM-custom) that can be tested
a1946652f71c top README: update for the status of hybrid firmware
Mychaela Falconia <falcon@freecalypso.org>
parents: 462
diff changeset
151 in our lab appears to work flawlessly; the new hybrid modem fw now needs to be
a1946652f71c top README: update for the status of hybrid firmware
Mychaela Falconia <falcon@freecalypso.org>
parents: 462
diff changeset
152 tested by a larger number of users in real-life usage.
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
153
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
154 Other blobs
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 ===========
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156
373
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
157 The TCS2/TCS3 hybrid firmware is built almost entirely from source; the only
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
158 components which are linked in the form of prebuilt libraries are GPF, Nucleus
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
159 and the TMS470 compiler's equivalent of libc/libgcc. It needs to be noted that
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
160 these components are so stable and configuration-independent that they were
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
161 used mostly in prebuilt library form even inside TI. In the case of GPF we've
9399a83cb394 first round of documentation updates for 2018
Mychaela Falconia <falcon@freecalypso.org>
parents: 254
diff changeset
162 got the corresponding source for most of the modules within those libs; for the
521
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
163 few modules for which the original source has been lost (OSL and OSX), we have
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
164 a reconstructed source and one can build a Magnetite config (hybrid-gpf) that
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
165 uses these reconstructed versions of OSL and OSX instead of the blobs, but we
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
166 are not 100% confident in the quality of this reconstruction, hence this
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
167 hybrid-gpf config is currently considered experimental, not production. In the
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
168 case of Nucleus we likewise have another version of it in full source form
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
169 which has been proven good in other FreeCalypso firmware projects, but it is
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
170 not used in Magnetite.
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
171
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
172 Blob-free, gcc-built version
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
173 ============================
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
174
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
175 For those who require or desire a firmware version that is completely free of
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
176 any blobs and builds with a FLOSS compiler, we now have a new experimental
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
177 firmware project called FreeCalypso Selenite:
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178
521
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
179 https://bitbucket.org/falconian/fc-selenite
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
180
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
181 FC Selenite is based on FC Magnetite (just the modem functionality, no work-in-
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
182 progress phone UI, and only the hybrid code version), but it uses the new
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
183 full-source version of Nucleus and our reconstructed versions of OSL and OSX,
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
184 and it offers the option of building either with the original TMS470 compiler
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
185 or with gcc. The gcc-built version also uses entirely new implementations of
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
186 all assembly components and linker script magic, as the two toolchain
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
187 environments are entirely different in this regard.
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
188
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
189 This new Selenite firmware is expected to fully supplant our earlier and now
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
190 completely unmaintained Citrine fw (our first attempt at gcc-built fw), but it
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
191 is still highly experimental: as of this writing, GPRS does not work at all in
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
192 Selenite-gcc (Citrine does not have any GPRS support either), and even the
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
193 GSM-only config with GPRS disabled exhibits some intermittent glitches. Thus
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
194 the stable production fw is still TMS470-built FC Magnetite for the time being.
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196 Further reading
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 ===============
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199 For various instructions and notes specific to this FreeCalypso Magnetite
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 firmware, look in the doc directory. For more information about the overall
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201 FreeCalypso project and our hardware building aspirations, go to our website:
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203 https://www.freecalypso.org/