--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Developer-notes	Fri Nov 09 03:04:02 2018 +0000
@@ -0,0 +1,146 @@
+The present article is a Selenite-specific addendum to the TCS211-fw-arch
+document in the freecalypso-docs repository; the latter document needs to be
+read first before this one.  Also because FC Selenite is derived from FC
+Magnetite, you should also read the Developer-notes document in the fc-magnetite
+source repository before the present one.
+
+Source tree layout
+==================
+
+The principal difference between Magnetite and Selenite in terms of the source
+tree layout is that Magnetite supports building two different code base variants
+(either pure TCS211 with G23M PS blobs or our FreeCalypso signature TCS2/TCS3
+hybrid), whereas Selenite only supports the hybrid code base.  Dropping support
+for the non-hybrid version is necessary in order to have a saner code base for
+new forward developments such as the compiler migration to gcc (the objective
+of FC Selenite) or the future planned UI development work which will be done in
+yet another to-be-created source tree after we build the necessary hardware.
+
+The source tree change is the elimination of parallel versions: in Magnetite we
+have to maintain two parallel versions for many firmware components, whereas in
+Selenite there is only one version, the one corresponding to our FreeCalypso
+signature TCS2/TCS3 hybrid explained in the TCS211-fw-arch document.
+
+The directories under src/ are now as follows:
+
+condat
+
+	This subtree is the amalgamation of condat2 and condat3 from Magnetite,
+	hybridized as detailed in the TCS211-fw-arch document.
+
+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.
+
+	This subtree is kept in sync with Magnetite as much as possible; the
+	diffs from Magnetite are to support gcc and the new version of Nucleus.
+
+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.  Just like in Magnetite, our TCS2/TCS3 hybrid uses the
+	TCS2 version of ALR; in Selenite it has been moved to g23m-gsm/alr2.
+
+	These directories are kept in sync with Magnetite as much as possible;
+	the diffs from Magnetite are fixes (band-aids in some cases) to pass
+	compilation with gcc.
+
+gpf
+
+	This subtree is the amalgamation of gpf2 and gpf3 from Magnetite; see
+	TCS211-fw-arch for the explanation of how our version of GPF has been
+	reconstructed from the surviving bits and pieces.  One additional change
+	is that the old Nucleus header files have been moved out of the way so
+	that we always use the new Nucleus headers without ambiguity or
+	conflict.
+
+libsys
+
+	This library is specific to the gcc-built configuration.  We use newlib
+	that is built as part of our gcc toolchain (see Toolchain-setup-gcc) as
+	our libc implementation for the most part, but for a few functions we
+	are not able to use newlib's implementation because it uses malloc or
+	depends on a Unix syscall environment which we don't have; libsys
+	provides our own replacements for these few libc functions.
+
+nucleus
+
+	We use a non-TI-sourced version of Nucleus from Comrade XVilka; because
+	it does not come from any of our TI-sourced components, it gets its own
+	top-level source directory.
+
+Assembly code pieces
+====================
+
+Like any other software that runs on the bare metal as opposed to an application
+under some high-level OS like Linux, our FreeCalypso GSM fw necessarily includes
+some assembly code pieces in addition to the main body of C code.  The
+differences between TI's TMS470 and GNU ARM environments and ABIs are great,
+hence entirely different versions of all assembly code pieces and linker script
+magic are needed between the two.  For the TMS470 compiler environment all
+assembly code pieces and linker scripts are essentially unchanged from TI's
+TCS211, whereas for the gcc version all assembly code is entirely new.  This
+assembly code and other support pieces that are specific to the gcc environment
+(see libsys above) originate from our first attempts at gcc-built GSM fw from
+the 2013-2015 timeframe.
+
+The use of two entirely independent assembly code implementations between the
+two compiler environments gives rise to some minor architectural differences:
+the new gcc version takes the approach of routing interrupts and exceptions
+through the Calypso internal ROM (on all targets in both flashed and RAM-loaded
+builds) and uses flash boot mode 0 instead of flash boot mode 1 on the sensible
+non-Compal targets.  Both of these design decisions require that the Calypso
+chip version be one of the new ones with boot ROM version 0300 (the one with
+all of the earlier bugs fixed); this requirement poses no problem for our own
+FreeCalypso hw and for the use case of running FreeCalypso fw on the historical
+hw from Motorola, Openmoko and Pirelli, but if anyone besides the Mother has an
+ancient D-Sample or Leonardo board with a Calypso C05 chip on it, those boards
+cannot run Selenite-gcc.
+
+Configuration and build system
+==============================
+
+The configuration and build system of FC Selenite is based on that of Magnetite;
+please read the Developer-notes document in the fc-magnetite source repository.
+
+The first difference from Magnetite is that Selenite does not have overall fw
+configuration recipes like Magnetite has in configs/* - instead the recipe for
+the hybrid modem configuration (the only config in the Magnetite sense that is
+supported in Selenite) has been incorporated into the new configure-gcc.sh
+and configure-tms470.sh scripts.  The selection of which components will be
+included or excluded is driven by GPRS, SRVC and FCHG_STATE config variables -
+these config vars exist in Magnetite too, but in Selenite they can be set by
+the user on the configure command line.
+
+The individual component build recipes in components/* are similar between
+Magnetite and Selenite, but the following aspects are different:
+
+* There are no component variants: for each given foo.lib (TMS470) or foo.a
+  (gcc) firmware component, there is only one components/foo recipe.
+
+* Except for a few gcc-specific components and one TMS470-specific component
+  (the empty bootloader stub, see TCS211-fw-arch), every components/foo recipe
+  has to work for both TMS470 and gcc environments.  The CFLAGS Bourne shell
+  variable is for TI's cl470 compiler, CFLAGS_gcc is for gcc, and CPPFLAGS are
+  common for both.
+
+* The shell function call for compiling C source files is c_file, replacing
+  Magnetite's cfile_plain and cfile_str2ind - there is no support for str2ind
+  in Selenite.
+
+Because there is no hybrid vs. classic TCS211 dichotomy in Selenite, there are
+no more header file selection shell variables - see the ex script in
+scripts/convert-from-magnetite.ex for the idea.