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.