FreeCalypso > hg > fc-magnetite

annotate doc/Developer-notes @ 695:530f71d65c20

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