# HG changeset patch # User Mychaela Falconia # Date 1539072593 0 # Node ID 343104963a7fa9923e80466cfa46d00fe0a68a94 # Parent fbf0fabc5505f438eabe854b97a63443fb15ff46 doc/Developer-notes written diff -r fbf0fabc5505 -r 343104963a7f doc/Developer-notes --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Developer-notes Tue Oct 09 08:09:53 2018 +0000 @@ -0,0 +1,187 @@ +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.