FreeCalypso > hg > fc-magnetite

comparison doc/Developer-notes @ 527:343104963a7f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Developer-notes written
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 09 Oct 2018 08:09:53 +0000
parents
children
comparison
equal deleted inserted replaced
526:fbf0fabc5505 527:343104963a7f
1 The present article is a Magnetite-specific addendum to the TCS211-fw-arch
2 document in the freecalypso-docs repository; the latter document needs to be
3 read first before this one.
4
5 Source tree layout
6 ==================
7
8 The arrangement of source components under src/ in FC Magnetite is somewhat
9 peculiar because it is designed to support building two different code base
10 variants: either pure TCS211 without any code from TCS3/LoCosto (which requires
11 using a binary-only version of the G23M PS component) or our FreeCalypso
12 signature TCS2/TCS3 hybrid which is blob-free in this regard. The directories
13 under src/ are as follows:
14
15 aci2
16
17 This subtree is an import of g23m/condat/ms/src from TCS211; it is
18 named aci2 because it primarily contains the TCS2 version of ACI and
19 the UI layers (BMI+MFW) that go with it, but it also contains the
20 source for ALR from TCS211 which is used in our TCS2/TCS3 hybrid.
21
22 condat2
23
24 This subtree is an import of g23m/condat from TCS211, pruned to just
25 com and frame subtrees, with int and ms subtrees omitted. The header
26 files found in this subtree are used only in the pure TCS211 configs,
27 but most of the source modules in this same subtree are used in both
28 pure TCS211 and hybrid configs.
29
30 condat3
31
32 This subtree is an import of g23m/condat from TCS3.2, similarly pruned
33 to just com and frame subtrees. This subtree is used only for hybrid
34 configs, and mostly for the header files under condat3/com/inc and
35 condat3/com/include; the only C module taken from condat3 is cl_rlcmac.c
36 in comlib.
37
38 Two header files under condat3/com/include (pwr.h and rtc.h) have been
39 replaced with TCS211 versions as part of the hybridization.
40
41 cs
42
43 This subtree is an import of chipsetsw from TCS211, plus our own
44 reconstruction of those parts of TCS211 chipsetsw which were censored
45 out in our starting copy: src/cs/layer1, src/cs/system/main and the
46 src/cs/system/bootloader/src stub. Because our reconstruction of these
47 pieces meticulously replicates the original blobs, it still counts as
48 pure TCS211 and is not a hybrid. This chipsetsw division is invariant
49 among all of our configs, both pure TCS211 and TCS2/TCS3 hybrid.
50
51 g23m-aci
52 g23m-fad
53 g23m-gprs
54 g23m-gsm
55
56 These directories contain the new TCS3 version of the G23M PS+ACI code
57 realm for our blob-free hybrid. The directory layout comes directly
58 from our TCS3.2 source from Peek/FGW: TI previously kept all G23M code
59 under g23m/condat/ms/src, but then they moved to these new g23m-*
60 directories which I (Mother Mychaela) like for their shortness, so we
61 enthusiastically kept the new directory layout. Only two pieces still
62 resided under g23m/condat/ms/src in our TCS3.2 source: ati_ext and upm,
63 which we moved into g23m-aci and g23m-gprs, respectively, where they
64 properly belong.
65
66 gpf2
67 gpf3
68
69 gpf2 is an import of the gpf tree from TCS211; gpf3 is an import of the
70 gpf tree from TCS3.2/LoCosto. Both imports have been pruned to just
71 the sources and headers present in each respective version, without
72 binary libs, Windows tools and other junk.
73
74 Our own reconstruction of OSL and OSX components has been added under
75 gpf2.
76
77 ui3
78
79 This subtree contains the new TCS3 version of phone UI (BMI+MFW)
80 components, used in our UI-enabled hybrid configs instead of the old
81 TCS2 version under aci2.
82
83 Two versions of ACI
84 ===================
85
86 ACI is a firmware component that receives a lot of development activity as we
87 add new AT commands and other new-to-FreeCalypso functionality, and for as long
88 as we support both pure TCS211 and TCS2/TCS3 hybrid configurations, we have to
89 maintain two different versions of ACI in parallel. The version under
90 src/aci2/aci is used in pure TCS211 configs and works only with the all-blobs
91 version of G23M PS, whereas the other version under src/g23m-aci/aci is used in
92 hybrid configs going forward. We strive to keep them in sync, but the hybrid
93 version is the forward-looking one - those who seek to understand our firmware
94 starting from a blank slate should focus on the new TCS3 version under g23m-aci.
95
96 Two versions of ALR
97 ===================
98
99 Our TCS2/TCS3 hybrid involves grafting the new TCS3 version of G23M PS onto the
100 old TCS211 L1, and there naturally has to be a splice point somewhere. ALR is
101 the component of the G23M PS whose job is to interface to L1, and we have the
102 source for both TCS2 and TCS3 versions of ALR. Support for Calypso L1 in the
103 new version of ALR is badly bitrotten, thus we took the approach of keeping the
104 L1-matching TCS211 version of ALR and putting the splice point just above it.
105
106 The L1-matching TCS211 version of ALR we are using resides in src/aci2/alr; the
107 other version in src/g23m-gsm/alr fails to compile in the Calypso configuration.
108
109 Header file selection
110 =====================
111
112 A critical distinction between pure TCS211 vs hybrid configs is the choice of
113 header files. Our pure TCS211 configs include the following stanza:
114
115 CONDAT=condat2
116 GPF=gpf2
117 CDGINC=cdg211/cdginc
118 CDGPRIM=cdg211/prim
119 ACI=aci2
120
121 whereas our hybrid configs include this other stanza:
122
123 CONDAT=condat3
124 GPF=gpf3
125 CDGINC=cdg-hybrid/cdginc
126 CDGPRIM=cdg-hybrid/sap-inline
127 ACI=g23m-aci
128
129 The following header files are hereby switched:
130
131 * Condat headers which would have been under condat/com/inc and
132 condat/com/include if we didn't have our condat2 vs. condat3 dichotomy;
133
134 * cdginc generated header files - see TCS211-fw-arch document for the
135 explanation;
136
137 * ACI headers.
138
139 The gpf2 vs. gpf3 include switch can be considered superfluous, as there are no
140 substantive differences between the two versions - do a diff -ur src/gpf[23]
141 to see for yourself.
142
143 Configuration and build system
144 ==============================
145
146 Our firmware configuration and build system is implemented in Bourne shell with
147 a few C helpers. This build system is driven by two kinds of recipes: firmware
148 configuration recipes (configs/*) and individual component build recipes
149 (components/*). The overall fw configuration recipe sets up some Bourne shell
150 variables which apply to the entire fw build configuration (which include the
151 header file selection variables described above), invokes the script that
152 generates the same config header files which were generated by TI's original
153 TCS211 build system, and then lists all components which are to be included in
154 the given fw build configuration. For each component to be included, the
155 configuration recipe specifies whether it is to be built from source or included
156 as a blob library; for each component to be built from source the corresponding
157 component build recipe comes into play.
158
159 Each component has a name that equals the name of the *.lib linkable library
160 into which it will be compiled, and some components come in multiple variants
161 in relation to deblobbing or hybridization. If a given component is available
162 in multiple variants, then each variant will have its own component build
163 recipe, and the build_lib line in the overall fw configuration recipe specifies
164 the variant to be used.
165
166 The individual component build recipes under components/* specify which actual
167 C source files are to be compiled and with what options. The CFLAGS variable
168 within these component build recipes sets cl470 compiler options that are
169 treated as "voodoo", whereas the CPPFLAGS variable accumulates long lists of -D
170 definitions and -I include paths, all of which have been taken from the BuSyB-
171 generated makefiles of TCS211. Once CFLAGS and CPPFLAGS have been set, the
172 actual C files are added to the build with cfile_plain and cfile_str2ind shell
173 function calls; the difference between these two is that cfile_str2ind allows
174 the possibility of preprocessing with str2ind whereas cfile_plain does not; the
175 choice of which is used when has been taken from TCS211. Note that the use of
176 str2ind is globally disabled by default and needs to be enabled with
177 USE_STR2IND=1 if it is desired.
178
179 It also needs to be noted that the sources we got from TI include some C files
180 and sometimes entire components that aren't used in our TCS211-mimicking
181 FreeCalypso fw, and they can be quite confusing when one doesn't realize that
182 they are defunct. There are also many components which are included in some
183 configurations but not in others. To tell whether a given piece of C code is
184 actually used in our firmware or not, you need to first study the overall fw
185 configuration recipe for the config you are working with, and then study the
186 individual component build recipes it invokes to see what actual C files are
187 being compiled.