FreeCalypso > hg > fc-tourmaline

comparison doc/Compiling @ 50:a62e5bf88434

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
first round of documentation
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 18 Oct 2020 18:08:15 +0000
parents
children
comparison
equal deleted inserted replaced
49:4e178a0e90f6 50:a62e5bf88434
1 Preparing the development and build environment
2 ===============================================
3
4 In order to compile our FreeCalypso Tourmaline firmware, you will need a
5 Unix/Linux system. Even though we are using a compiler which we got in the
6 form of Windows .exe binaries and thus have to use Wine (see below), everything
7 that we have built on top of it is Unix-based. The Mother currently uses
8 Slackware Linux release 14.2 (32-bit) and previously used Slackware 13.37,
9 also 32-bit.
10
11 You will need to install the following 3 pieces of software on whatever
12 machine you will use to run the FC Tourmaline build process:
13
14 1. Wine: self-explanatory. The Mother uses the following Slackware package:
15
16 https://www.freecalypso.org/members/falcon/slackware/wine-1.5.23-i486-1sg.txz
17
18 I originally used it with Slackware 13.37 and I am still able to use it
19 with 14.2 without any issues.
20
21 2. FreeCalypso Wine environment:
22
23 ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/installed-env.tar.xz
24
25 Extract the content of the above tarball into your ~/.wine/drive_c
26 directory - that's all there is to it!
27
28 3. nowhine wrapper around Wine:
29
30 ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/nowhine.c
31
32 The purpose of this wrapper is to suppress the following obnoxious whine
33 which wine emits on my system:
34
35 preloader: Warning: failed to reserve range 00010000-00110000
36
37 Wine will also emits a bunch of other whines if you have to run it
38 in an environment without an X11 display (e.g., on a machine that you
39 ssh into), and our nowhine wrapper suppresses those as well.
40
41 If wine does not emit those preloader whines on your system and you
42 never find yourself in a situation of having to run without an X11
43 display and thus you find our nowhine wrapper to be unnecessary,
44 you can skip the wrapper and create a nowhine symlink pointing directly
45 to wine.
46
47 Compiling the local helper utilities
48 ====================================
49
50 (cd helpers; make)
51
52 Do the above. Most of the build helper scripts used in the FC Tourmaline build
53 system are written in Bourne shell, but a few were easier to implement in C.
54 You need to compile these C helper utilities before you can run an actual FC
55 Tourmaline firmware build, but these utilities are totally ad hoc and specific
56 to the needs of our fw build system, hence they are not meant to be installed
57 globally on your system - instead they stay within the fc-tourmaline tree. You
58 just need to run make in the helpers directory once before any actual firmware
59 builds.
60
61 Actually building the firmware
62 ==============================
63
64 In order to build our FreeCalypso Tourmaline firmware for a particular target
65 in a particular configuration, run a command like this from the top level of
66 the fc-tourmaline tree:
67
68 ./configure.sh luna2 bigcolor-gprs
69
70 The first required argument to the configure.sh script selects the hardware
71 target, the second required argument selects the functional configuration, and
72 any further arguments beyond these two (optional) allow changing various
73 configurable settings that go beyond basic functional selection and aren't
74 strictly fixed by the hardware target.
75
76 As of this writing, the following hardware targets are supported:
77
78 c11x Motorola C11x/12x
79 c139 Motorola C139/140
80 c155 Motorola C155/156
81 fcdev3b FreeCalypso FCDEV3B
82 gtamodem The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones
83 gtm900mgc Huawei GTM900, hardware variant MGC1GSMT or MGC2GSMT
84 j100 Sony Ericsson J100
85 luna1 FreeCalypso Luna, based on iWOW DSK v4.0 or v5.0 motherboard
86 luna2 FreeCalypso Luna, based on FC Caramel2 motherboard
87 pirelli Pirelli DP-L10
88 tangomdm FreeCalypso Tango standard modem config
89
90 The second required argument selects the basic functional configuration; these
91 functional config stanzas appear in the configs directory. The following
92 functional configurations are currently available:
93
94 bigcolor-gprs & bigcolor-vo
95
96 These are UI-enabled configurations with the big (176x220 pixel) color
97 version of the UI. These functional configs can be built only for
98 luna1 and luna2 targets.
99
100 smallbw
101
102 Small B&W UI configuration - 96x64 pixel black&white UI version. This
103 functional config can be built for c139, luna1 and luna2 targets. When
104 running on Luna, the logical 96x64 pixel B&W LCD is centered in the
105 middle of the 176x220 pixel physical LCD, surrounded by a pale magenta
106 border.
107
108 bwtest
109
110 This one is a special intermediate configuration is that the UI layers
111 are built in the smallbw config, but the underlying R2D framebuffer
112 driver is 176x220 pixel B&W, rather than 96x64 pixel B&W. This config
113 can only be built for Luna targets; it originates from TI's own
114 configuration of running their !LSCREEN (smallbw) UI on D-Sample boards
115 with R2D driver in the BW_D_Sample config.
116
117 stdmodem
118
119 Standard modem config, all data services enabled, no UI functionality
120 included. Supported targets are fcdev3b, gtamodem, gtm900mgc and
121 tangomdm.
122
123 vpm
124
125 See the Voice-pseudo-modem article. This functional config is
126 applicable to c11x, c139, c155, j100 and pirelli targets.
127
128 Each configuration is built in its own directory; the name of this build
129 directory takes the form of build-$TARGET-$CONFIG$SUFFIX, i.e., for the example
130 configure.sh line above, the resulting build directory will be named
131 build-luna2-bigcolor-gprs. The $SUFFIX part is empty by default, but can be set
132 on the command line in order to distinguish non-standard builds that had some
133 tunable settings changed to values other than the default. For example, if you
134 are building modem firmware for an FCDEV3B V1 board where you need to disable
135 sleep, you should run the configure script as follows:
136
137 ./configure.sh fcdev3b stdmodem DISABLE_SLEEP=1 SUFFIX=-nosleep
138
139 The build directory would then become build-fcdev3b-stdmodem-nosleep, and the
140 specified suffix will also be included in the firmware version ID string that
141 gets compiled into the image.
142
143 To actually compile the firmware, cd into the created build directory and run
144 make there. Unfortunately the use of TI's proprietary compiler via Wine makes
145 the build quite slow, but there is a trick to speed it up: if you run some
146 other Wine program that stays open and does not exit on its own (e.g., wine cmd)
147 in another window and leave it open while you run your FC Tourmaline fw build,
148 the build will proceed much faster - the presence of another Wine process using
149 the wineserver environment will keep Wine from shutting this environment down
150 and restarting it for every individual cl470 run, i.e., for each individual C
151 source file.
152
153 When the build is done, the flashable firmware image will be in fwimage.bin.
154 This image is to be flashed with fc-loadtool at a target-dependent base address.
155 The build system also produces a short text file named flash-script which is a
156 flashing command script for fc-loadtool that erases the correct range of flash
157 sectors and then programs fwimage.bin at the right address.
158
159 When building firmware for the FCDEV3B or for the Pirelli, one can build either
160 a flashable image or a RAM-loadable one - or both. Because this part of the
161 build system is common with other targets for which only flash images can be
162 produced, the Makefile always builds the flashable image by default -
163 fwimage.bin is always meant for flash and never for RAM. To build a RAM-
164 loadable image when the target allows it, run 'make ram' - the image will be in
165 ramimage.srec, which you can then load and run on the target with FreeCalypso
166 host tool fc-xram.
167
168 Cached libraries
169 ================
170
171 In the build architecture of all TCS211-based firmwares including Tourmaline,
172 each fw component is first compiled into a linkable library (*.lib file with
173 TI's TMS470 toolchain), and then these libraries are linked together into the
174 final code image. Early in FreeCalypso project history many of these component
175 libraries were blobs, meaning that we had to use prebuilt libraries for which
176 we had no corresponding source. Our fw has now been almost fully deblobbed,
177 meaning that we have transitioned from blobs to recompilation from source for
178 almost all of our fw components. But this deblobbing has had an unfortunate
179 downside: because our Wine-based compiler is very slow, every time we deblobbed
180 a component library, build times would get longer and longer.
181
182 FC Tourmaline introduces a partial solution to this problem in the form of
183 cached libs. Some component libraries are completely independent of
184 configuration particulars, i.e., they remain exactly the same no matter which
185 Calypso target you are building firmware for, and are likewise unaffected by
186 our various supported functional configs. Prebuilt versions of these config-
187 independent libs have been checked into the cache directory of our source tree,
188 and Tourmaline fw builds use these cached libs by default. These cached libs
189 are NOT blobs in that we do have the corresponding source for them, and the
190 versions that are checked in have been built by us, not by any evil source-
191 withholding third parties. You can disable the use of cached libs and force
192 full recompilation from source by adding a USE_CACHE=0 argument to your
193 configure.sh line.
194
195 Running on the hardware
196 =======================
197
198 In order to run the firmware you have built on your Calypso phone or modem
199 (flash or run in RAM as appropriate), you will need to use FreeCalypso host
200 tools. The current version at any given moment can be found at this URL:
201
202 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2
203
204 Please see target-specific notes for more details.