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. |