FreeCalypso > hg > fc-magnetite
view doc/Developer-notes @ 644:9bc993985bdc
doc/Compiling: update for gtm900mgc target
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sat, 15 Feb 2020 17:58:50 +0000 |
parents | 343104963a7f |
children |
line wrap: on
line source
The present article is a Magnetite-specific addendum to the TCS211-fw-arch document in the freecalypso-docs repository; the latter document needs to be read first before this one. Source tree layout ================== The arrangement of source components under src/ in FC Magnetite is somewhat peculiar because it is designed to support building two different code base variants: either pure TCS211 without any code from TCS3/LoCosto (which requires using a binary-only version of the G23M PS component) or our FreeCalypso signature TCS2/TCS3 hybrid which is blob-free in this regard. The directories under src/ are as follows: aci2 This subtree is an import of g23m/condat/ms/src from TCS211; it is named aci2 because it primarily contains the TCS2 version of ACI and the UI layers (BMI+MFW) that go with it, but it also contains the source for ALR from TCS211 which is used in our TCS2/TCS3 hybrid. condat2 This subtree is an import of g23m/condat from TCS211, pruned to just com and frame subtrees, with int and ms subtrees omitted. The header files found in this subtree are used only in the pure TCS211 configs, but most of the source modules in this same subtree are used in both pure TCS211 and hybrid configs. condat3 This subtree is an import of g23m/condat from TCS3.2, similarly pruned to just com and frame subtrees. This subtree is used only for hybrid configs, and mostly for the header files under condat3/com/inc and condat3/com/include; the only C module taken from condat3 is cl_rlcmac.c in comlib. Two header files under condat3/com/include (pwr.h and rtc.h) have been replaced with TCS211 versions as part of the hybridization. cs This subtree is an import of chipsetsw from TCS211, plus our own reconstruction of those parts of TCS211 chipsetsw which were censored out in our starting copy: src/cs/layer1, src/cs/system/main and the src/cs/system/bootloader/src stub. Because our reconstruction of these pieces meticulously replicates the original blobs, it still counts as pure TCS211 and is not a hybrid. This chipsetsw division is invariant among all of our configs, both pure TCS211 and TCS2/TCS3 hybrid. g23m-aci g23m-fad g23m-gprs g23m-gsm These directories contain the new TCS3 version of the G23M PS+ACI code realm for our blob-free hybrid. The directory layout comes directly from our TCS3.2 source from Peek/FGW: TI previously kept all G23M code under g23m/condat/ms/src, but then they moved to these new g23m-* directories which I (Mother Mychaela) like for their shortness, so we enthusiastically kept the new directory layout. Only two pieces still resided under g23m/condat/ms/src in our TCS3.2 source: ati_ext and upm, which we moved into g23m-aci and g23m-gprs, respectively, where they properly belong. gpf2 gpf3 gpf2 is an import of the gpf tree from TCS211; gpf3 is an import of the gpf tree from TCS3.2/LoCosto. Both imports have been pruned to just the sources and headers present in each respective version, without binary libs, Windows tools and other junk. Our own reconstruction of OSL and OSX components has been added under gpf2. ui3 This subtree contains the new TCS3 version of phone UI (BMI+MFW) components, used in our UI-enabled hybrid configs instead of the old TCS2 version under aci2. Two versions of ACI =================== ACI is a firmware component that receives a lot of development activity as we add new AT commands and other new-to-FreeCalypso functionality, and for as long as we support both pure TCS211 and TCS2/TCS3 hybrid configurations, we have to maintain two different versions of ACI in parallel. The version under src/aci2/aci is used in pure TCS211 configs and works only with the all-blobs version of G23M PS, whereas the other version under src/g23m-aci/aci is used in hybrid configs going forward. We strive to keep them in sync, but the hybrid version is the forward-looking one - those who seek to understand our firmware starting from a blank slate should focus on the new TCS3 version under g23m-aci. Two versions of ALR =================== Our TCS2/TCS3 hybrid involves grafting the new TCS3 version of G23M PS onto the old TCS211 L1, and there naturally has to be a splice point somewhere. ALR is the component of the G23M PS whose job is to interface to L1, and we have the source for both TCS2 and TCS3 versions of ALR. Support for Calypso L1 in the new version of ALR is badly bitrotten, thus we took the approach of keeping the L1-matching TCS211 version of ALR and putting the splice point just above it. The L1-matching TCS211 version of ALR we are using resides in src/aci2/alr; the other version in src/g23m-gsm/alr fails to compile in the Calypso configuration. Header file selection ===================== A critical distinction between pure TCS211 vs hybrid configs is the choice of header files. Our pure TCS211 configs include the following stanza: CONDAT=condat2 GPF=gpf2 CDGINC=cdg211/cdginc CDGPRIM=cdg211/prim ACI=aci2 whereas our hybrid configs include this other stanza: CONDAT=condat3 GPF=gpf3 CDGINC=cdg-hybrid/cdginc CDGPRIM=cdg-hybrid/sap-inline ACI=g23m-aci The following header files are hereby switched: * Condat headers which would have been under condat/com/inc and condat/com/include if we didn't have our condat2 vs. condat3 dichotomy; * cdginc generated header files - see TCS211-fw-arch document for the explanation; * ACI headers. The gpf2 vs. gpf3 include switch can be considered superfluous, as there are no substantive differences between the two versions - do a diff -ur src/gpf[23] to see for yourself. Configuration and build system ============================== Our firmware configuration and build system is implemented in Bourne shell with a few C helpers. This build system is driven by two kinds of recipes: firmware configuration recipes (configs/*) and individual component build recipes (components/*). The overall fw configuration recipe sets up some Bourne shell variables which apply to the entire fw build configuration (which include the header file selection variables described above), invokes the script that generates the same config header files which were generated by TI's original TCS211 build system, and then lists all components which are to be included in the given fw build configuration. For each component to be included, the configuration recipe specifies whether it is to be built from source or included as a blob library; for each component to be built from source the corresponding component build recipe comes into play. Each component has a name that equals the name of the *.lib linkable library into which it will be compiled, and some components come in multiple variants in relation to deblobbing or hybridization. If a given component is available in multiple variants, then each variant will have its own component build recipe, and the build_lib line in the overall fw configuration recipe specifies the variant to be used. The individual component build recipes under components/* specify which actual C source files are to be compiled and with what options. The CFLAGS variable within these component build recipes sets cl470 compiler options that are treated as "voodoo", whereas the CPPFLAGS variable accumulates long lists of -D definitions and -I include paths, all of which have been taken from the BuSyB- generated makefiles of TCS211. Once CFLAGS and CPPFLAGS have been set, the actual C files are added to the build with cfile_plain and cfile_str2ind shell function calls; the difference between these two is that cfile_str2ind allows the possibility of preprocessing with str2ind whereas cfile_plain does not; the choice of which is used when has been taken from TCS211. Note that the use of str2ind is globally disabled by default and needs to be enabled with USE_STR2IND=1 if it is desired. It also needs to be noted that the sources we got from TI include some C files and sometimes entire components that aren't used in our TCS211-mimicking FreeCalypso fw, and they can be quite confusing when one doesn't realize that they are defunct. There are also many components which are included in some configurations but not in others. To tell whether a given piece of C code is actually used in our firmware or not, you need to first study the overall fw configuration recipe for the config you are working with, and then study the individual component build recipes it invokes to see what actual C files are being compiled.