annotate README @ 556:39a226a06196

documentation update for rebuilding the easy parts of GPF from source
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 19 Nov 2018 02:00:21 +0000
parents f9125919bbe4
children c32c887ced3a
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
556
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
157 Our TCS2/TCS3 hybrid firmware is built almost entirely from source; the only
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
158 components which are linked in the form of prebuilt objects or libraries are
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
159 certain glue components in GPF (specifically OSL and OSX), the Nucleus PLUS RTOS
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
160 and the TMS470 compiler's equivalent of libc/libgcc. In the case of Nucleus we
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
161 have another version of it in full source form, but switching to a different
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
162 version of Nucleus is outside the scope of FC Magnetite - see the next section.
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
163 In the case of OSL and OSX, we have a reconstructed source and one can build a
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
164 Magnetite config (hybrid-osl) that uses these reconstructed versions of OSL and
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
165 OSX instead of the blobs, but we are not 100% confident in the quality of this
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
166 reconstruction, hence this hybrid-osl config is currently considered
39a226a06196 documentation update for rebuilding the easy parts of GPF from source
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
167 experimental, not production.
521
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
168
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
169 Blob-free, gcc-built version
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
170 ============================
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 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
173 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
174 firmware project called FreeCalypso Selenite:
94
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175
521
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
176 https://bitbucket.org/falconian/fc-selenite
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
177
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
178 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
179 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
180 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
181 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
182 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
183 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
184 environments are entirely different in this regard.
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
185
f9125919bbe4 README: update for Selenite
Mychaela Falconia <falcon@freecalypso.org>
parents: 512
diff changeset
186 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
187 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
188 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
189 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
190 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
191 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
192
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 Further reading
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 ===============
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 For various instructions and notes specific to this FreeCalypso Magnetite
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 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
198 FreeCalypso project and our hardware building aspirations, go to our website:
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199
596d86109e44 initial round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 https://www.freecalypso.org/