--- /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.