FreeCalypso > hg > fc-selenite

comparison doc/Compiling @ 109:a68c6c7942d7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: basic build documentation written
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 24 Jul 2018 23:55:24 +0000
parents
children 4238e3220682
comparison
equal deleted inserted replaced
108:af6b7fcf7823 109:a68c6c7942d7
1 Selecting and preparing the compiler environment
2 ================================================
3
4 FreeCalypso Selenite firmware can be built with two different compiler
5 toolchains: either with TI's original TMS470 compiler or with gcc. Transition
6 to compiling with gcc is a very bold move with very heavy fallout, and many
7 parts of the fw are still broken or destabilized when built with gcc instead of
8 the original compiler they were developed with, thus for the foreseeable future,
9 anyone who aspires to be a FreeCalypso developer will need to compile our fw in
10 both ways, compare the behaviour of the two versions, and work toward making
11 the gcc-built version perform as well as the TMS470-built one. Thus you need
12 to have both compiler toolchains installed and working - see the
13 Toolchain-setup-470 and Toolchain-setup-gcc articles for the instructions.
14
15 Compiling the local helper utilities
16 ====================================
17
18 (cd helpers; make)
19
20 Do the above. Most of the build helper scripts used in the FC Selenite build
21 system are written in Bourne shell, but a few were easier to implement in C.
22 You need to compile these C helper utilities before you can run an actual FC
23 Selenite firmware build, but these utilities are totally ad hoc and specific
24 to the needs of our fw build system, hence they are not meant to be installed
25 globally on your system - instead they stay within the fc-selenite tree. You
26 just need to run make in the helpers directory once before any actual firmware
27 builds.
28
29 Actually building the firmware
30 ==============================
31
32 To build our FC Selenite firmware for your hw target of interest in the default
33 configuration, run a command like this from the top level of the fc-selenite
34 tree:
35
36 ./configure-gcc.sh fcdev3b
37
38 or
39
40 ./configure-tms470.sh fcdev3b
41
42 As of this writing, the following hardware targets are supported:
43
44 c11x Motorola C11x/12x
45 c139 Motorola C139/140
46 fcdev3b FreeCalypso FCDEV3B
47 gtamodem The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones
48 pirelli Pirelli DP-L10
49
50 Notice the difference from FC Magnetite: there is no "configuration name"
51 argument after the target name. Because FC Selenite does not include any UI
52 code (modem functionality only) and does not offer different versions of
53 various fw components the way Magnetite does, it does not have named
54 configurations in the same sense as Magnetite. Instead any configuration
55 tweaks are done via var=value optional arguments on the configure command line
56 after the required target name argument; the following variables are currently
57 available for tweaking:
58
59 ALLOW_CSIM_GSM
60
61 Per TI's original design, the AT+CSIM command does not allow GSM APDUs
62 of class 0xA0. Openmoko found some need for them, and they patched
63 their modem fw to allow these APDUs with AT+CSIM. With our new hybrid
64 modem fw this policy setting is configurable at build time; the default
65 is ALLOW_CSIM_GSM=1 (GSM APDUs allowed).
66
67 DISABLE_SLEEP
68
69 The general default is DISABLE_SLEEP=0, and the firmware automatically
70 enables all of the chipset's available sleep modes on boot. Setting
71 DISABLE_SLEEP=1 causes all sleep modes to be disabled by default on
72 boot (they can still be enabled with the AT%SLEEP command); this
73 setting is needed for FCDEV3B V1 boards that have a hardware bug that
74 causes breakage when sleep modes are enabled.
75
76 FCHG_STATE
77
78 This setting enables or disables the FCHG battery charging driver. By
79 default it is enabled on targets that have battery charging hardware
80 (c11x, c139, pirelli) and disabled on those that don't have such hw
81 (fcdev3b, gtamodem).
82
83 GPRS
84
85 Self-explanatory: enables or disables GPRS. By default GPRS is enabled
86 on proper modem hw targets (fcdev3b and gtamodem) and disabled on c11x,
87 c139 and pirelli.
88
89 L1_DYN_DSP_DWNLD
90
91 This setting enables TI's dynamic DSP patch download mechanism. When
92 the firmware is built for a Calypso target with DSP ROM version 36 in
93 the silicon (all FreeCalypso-made hw and most of the supported legacy
94 targets), L1_DYN_DSP_DWNLD is enabled by default and needs to be kept
95 enabled for correct operation: the patch code we got from TI for this
96 ROM is the dynamic download version, and the ARM-side L1 code expects
97 all of these patches to be present, both the static part and the
98 dynamic parts. However, one can build our fw with L1_DYN_DSP_DWNLD=0
99 for experimental testing, to see what breaks when the dynamic patches
100 are omitted.
101
102 L1_VOICE_MEMO_AMR
103
104 This setting enables or disables support in L1 and in the RiViera Audio
105 Service for AMR voice memo recording and playback. This code has not
106 been properly studied yet and no test AT commands are provided for it,
107 but it is enabled by default like in TI's original TCS211 fw.
108
109 MELODY_E2
110
111 This setting enables or disables support in L1 and in the RiViera Audio
112 Service for playing E2-format melodies. The default is MELODY_E2=1
113 like in TI's original TCS211 fw. Note that Melody E1 support is always
114 enabled; setting MELODY_E2=0 disables only Melody E2, but not E1.
115
116 MEMSUPER
117
118 This setting enables the memory supervision feature in TI's GPF and in
119 the G23M protocol stack built on top of it. This code has not been
120 properly studied yet; play with it at your own risk.
121
122 SERIAL_DYNAMIC_SWITCH
123
124 TI's TCS211 fw includes a provision (only for Bluetooth-enabled fw in
125 TI's original) to switch one UART between the AT command interface and
126 RVTMUX while the other UART is fixed for Bluetooth. In FreeCalypso we
127 have changed this code to work without Bluetooth, for the purpose of
128 switching the user-facing MODEM UART between AT commands and RVTMUX,
129 but the mechanism does not work properly yet and is disabled by default.
130 Enable it with SERIAL_DYNAMIC_SWITCH=1 if you would like to play with
131 it.
132
133 SPEECH_RECO
134
135 This setting enables or disables support in L1 and in the RiViera Audio
136 Service for TI's speech recognition mechanism. This code and the
137 underlying DSP facility itself have not been properly studied yet and
138 no test AT commands are provided for it, but it is enabled by default
139 like in TI's original TCS211 fw.
140
141 SRVC
142
143 TI's original config variable, selects the presence or absence of data
144 services other than GPRS as follows:
145
146 SRVC=0: voice and SMS only
147 SRVC=1: CSD and fax enabled
148 SRVC=2: CSD enabled, but not fax
149
150 The default is SRVC=1 (fax and data enabled) for proper modem hw targets
151 (fcdev3b and gtamodem) and SRVC=0 (voice and SMS only) on c11x, c139
152 and pirelli.
153
154 SUFFIX
155
156 This setting is solely for configuration management. If you make a
157 build with any of the settings described in this document changed from
158 the default, you should also pass a SUFFIX=-xxx argument so your special
159 build will be appropriately identified in the build directory name and
160 in the firmware version ID string compiled into the image. The naming
161 of suffixes is up to you, but here are some examples:
162
163 L1_DYN_DSP_DWNLD=0 SUFFIX=-nodyn
164 MELODY_E2=0 SUFFIX=-noe2
165 MEMSUPER=2 SUFFIX=-ps
166 SERIAL_DYNAMIC_SWITCH=1 SUFFIX=-sds
167 SPEECH_RECO=0 SUFFIX=-nosr
168 TR_BAUD_CONFIG=TR_BAUD_812500 SUFFIX=-812500
169
170 TR_BAUD_CONFIG
171
172 The value of this symbol is an alphanumeric keyword of the form
173 TR_BAUD_xxxxxx; the default is TR_BAUD_115200. See
174 src/cs/drivers/drv_core/uart/traceswitch.h for the available baud rate
175 choices; the most practical use is setting TR_BAUD_CONFIG=TR_BAUD_812500
176 when you need to run the RVTMUX serial channel at the maximum possible
177 baud rate.
178
179 Each configuration is built in its own directory; the name of this build
180 directory always begins with build- and is constructed to reflect the
181 configuration. The auto-generated build directory name includes the name of
182 the target, the selection of services to be included based on the GPRS, SRVC
183 and FCHG_STATE variables, and a -470 or -gcc suffix indicating the compiler
184 toolchain, but if you manually override any of the other config variables
185 described above, you should also include a SUFFIX=-xxx argument giving an
186 identifying suffix for your own configuration changes.
187
188 To actually compile the firmware, cd into the created build directory and run
189 make there. With gcc the build proceeds very fast because the compiler runs
190 natively, but building with the original TMS470 compiler requires going through
191 Wine, which is much slower. There is, however, a trick to speed up these
192 TMS470 builds: if you run some other Wine program that stays open and does not
193 exit on its own (e.g., wine cmd) in another window and leave it open while you
194 run your Selenite TMS470 build, the build will proceed much faster - the
195 presence of another Wine process using the wineserver environment will keep
196 Wine from shutting this environment down and restarting it for every individual
197 cl470 run, i.e., for each individual C source file.
198
199 When the build is done, the flashable firmware image will be in fwimage.bin.
200 This image is to be flashed with fc-loadtool at address 0x10000 on Mot C11x and
201 C139 targets, and at address 0 on the more sensible targets that have the
202 Calypso boot ROM enabled. The build system also produces a short text file
203 named flash-script which is a flashing command script for fc-loadtool that
204 erases the correct range of flash sectors and then programs fwimage.bin at the
205 right address.
206
207 When building firmware for the FCDEV3B or for the Pirelli, one can build either
208 a flashable image or a RAM-loadable one - or both. Because this part of the
209 build system is common with other targets for which only flash images can be
210 produced, the Makefile always builds the flashable image by default -
211 fwimage.bin is always meant for flash and never for RAM. To build a RAM-
212 loadable image when the target allows it, run 'make ram' - the image will be in
213 ramimage.srec, which you can then load and run on the target with FreeCalypso
214 host tool fc-xram.
215
216 Running on the hardware
217 =======================
218
219 In order to run the firmware you have built on your FCDEV3B or other Calypso
220 device (flash or run in RAM as appropriate), you will need to use FreeCalypso
221 host tools. As of this writing, the latest packaged release is this one:
222
223 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-r8.tar.bz2