FreeCalypso > hg > fc-selenite

comparison doc/Developer-notes @ 129:3055bcff8050

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 Fri, 09 Nov 2018 03:04:02 +0000
parents
children
comparison
equal deleted inserted replaced
128:24a161f415f5 129:3055bcff8050
1 The present article is a Selenite-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. Also because FC Selenite is derived from FC
4 Magnetite, you should also read the Developer-notes document in the fc-magnetite
5 source repository before the present one.
6
7 Source tree layout
8 ==================
9
10 The principal difference between Magnetite and Selenite in terms of the source
11 tree layout is that Magnetite supports building two different code base variants
12 (either pure TCS211 with G23M PS blobs or our FreeCalypso signature TCS2/TCS3
13 hybrid), whereas Selenite only supports the hybrid code base. Dropping support
14 for the non-hybrid version is necessary in order to have a saner code base for
15 new forward developments such as the compiler migration to gcc (the objective
16 of FC Selenite) or the future planned UI development work which will be done in
17 yet another to-be-created source tree after we build the necessary hardware.
18
19 The source tree change is the elimination of parallel versions: in Magnetite we
20 have to maintain two parallel versions for many firmware components, whereas in
21 Selenite there is only one version, the one corresponding to our FreeCalypso
22 signature TCS2/TCS3 hybrid explained in the TCS211-fw-arch document.
23
24 The directories under src/ are now as follows:
25
26 condat
27
28 This subtree is the amalgamation of condat2 and condat3 from Magnetite,
29 hybridized as detailed in the TCS211-fw-arch document.
30
31 cs
32
33 This subtree is an import of chipsetsw from TCS211, plus our own
34 reconstruction of those parts of TCS211 chipsetsw which were censored
35 out in our starting copy: src/cs/layer1, src/cs/system/main and the
36 src/cs/system/bootloader/src stub.
37
38 This subtree is kept in sync with Magnetite as much as possible; the
39 diffs from Magnetite are to support gcc and the new version of Nucleus.
40
41 g23m-aci
42 g23m-fad
43 g23m-gprs
44 g23m-gsm
45
46 These directories contain the new TCS3 version of the G23M PS+ACI code
47 realm for our blob-free hybrid. The directory layout comes directly
48 from our TCS3.2 source from Peek/FGW: TI previously kept all G23M code
49 under g23m/condat/ms/src, but then they moved to these new g23m-*
50 directories which I (Mother Mychaela) like for their shortness, so we
51 enthusiastically kept the new directory layout. Only two pieces still
52 resided under g23m/condat/ms/src in our TCS3.2 source: ati_ext and upm,
53 which we moved into g23m-aci and g23m-gprs, respectively, where they
54 properly belong. Just like in Magnetite, our TCS2/TCS3 hybrid uses the
55 TCS2 version of ALR; in Selenite it has been moved to g23m-gsm/alr2.
56
57 These directories are kept in sync with Magnetite as much as possible;
58 the diffs from Magnetite are fixes (band-aids in some cases) to pass
59 compilation with gcc.
60
61 gpf
62
63 This subtree is the amalgamation of gpf2 and gpf3 from Magnetite; see
64 TCS211-fw-arch for the explanation of how our version of GPF has been
65 reconstructed from the surviving bits and pieces. One additional change
66 is that the old Nucleus header files have been moved out of the way so
67 that we always use the new Nucleus headers without ambiguity or
68 conflict.
69
70 libsys
71
72 This library is specific to the gcc-built configuration. We use newlib
73 that is built as part of our gcc toolchain (see Toolchain-setup-gcc) as
74 our libc implementation for the most part, but for a few functions we
75 are not able to use newlib's implementation because it uses malloc or
76 depends on a Unix syscall environment which we don't have; libsys
77 provides our own replacements for these few libc functions.
78
79 nucleus
80
81 We use a non-TI-sourced version of Nucleus from Comrade XVilka; because
82 it does not come from any of our TI-sourced components, it gets its own
83 top-level source directory.
84
85 Assembly code pieces
86 ====================
87
88 Like any other software that runs on the bare metal as opposed to an application
89 under some high-level OS like Linux, our FreeCalypso GSM fw necessarily includes
90 some assembly code pieces in addition to the main body of C code. The
91 differences between TI's TMS470 and GNU ARM environments and ABIs are great,
92 hence entirely different versions of all assembly code pieces and linker script
93 magic are needed between the two. For the TMS470 compiler environment all
94 assembly code pieces and linker scripts are essentially unchanged from TI's
95 TCS211, whereas for the gcc version all assembly code is entirely new. This
96 assembly code and other support pieces that are specific to the gcc environment
97 (see libsys above) originate from our first attempts at gcc-built GSM fw from
98 the 2013-2015 timeframe.
99
100 The use of two entirely independent assembly code implementations between the
101 two compiler environments gives rise to some minor architectural differences:
102 the new gcc version takes the approach of routing interrupts and exceptions
103 through the Calypso internal ROM (on all targets in both flashed and RAM-loaded
104 builds) and uses flash boot mode 0 instead of flash boot mode 1 on the sensible
105 non-Compal targets. Both of these design decisions require that the Calypso
106 chip version be one of the new ones with boot ROM version 0300 (the one with
107 all of the earlier bugs fixed); this requirement poses no problem for our own
108 FreeCalypso hw and for the use case of running FreeCalypso fw on the historical
109 hw from Motorola, Openmoko and Pirelli, but if anyone besides the Mother has an
110 ancient D-Sample or Leonardo board with a Calypso C05 chip on it, those boards
111 cannot run Selenite-gcc.
112
113 Configuration and build system
114 ==============================
115
116 The configuration and build system of FC Selenite is based on that of Magnetite;
117 please read the Developer-notes document in the fc-magnetite source repository.
118
119 The first difference from Magnetite is that Selenite does not have overall fw
120 configuration recipes like Magnetite has in configs/* - instead the recipe for
121 the hybrid modem configuration (the only config in the Magnetite sense that is
122 supported in Selenite) has been incorporated into the new configure-gcc.sh
123 and configure-tms470.sh scripts. The selection of which components will be
124 included or excluded is driven by GPRS, SRVC and FCHG_STATE config variables -
125 these config vars exist in Magnetite too, but in Selenite they can be set by
126 the user on the configure command line.
127
128 The individual component build recipes in components/* are similar between
129 Magnetite and Selenite, but the following aspects are different:
130
131 * There are no component variants: for each given foo.lib (TMS470) or foo.a
132 (gcc) firmware component, there is only one components/foo recipe.
133
134 * Except for a few gcc-specific components and one TMS470-specific component
135 (the empty bootloader stub, see TCS211-fw-arch), every components/foo recipe
136 has to work for both TMS470 and gcc environments. The CFLAGS Bourne shell
137 variable is for TI's cl470 compiler, CFLAGS_gcc is for gcc, and CPPFLAGS are
138 common for both.
139
140 * The shell function call for compiling C source files is c_file, replacing
141 Magnetite's cfile_plain and cfile_str2ind - there is no support for str2ind
142 in Selenite.
143
144 Because there is no hybrid vs. classic TCS211 dichotomy in Selenite, there are
145 no more header file selection shell variables - see the ex script in
146 scripts/convert-from-magnetite.ex for the idea.