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.