FreeCalypso > hg > fc-tourmaline
comparison doc/Compiling @ 50:a62e5bf88434
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. |