The state of blobs vs. blob-free firmware in FreeCalypso
========================================================

As of 2019, we have 3 different firmware versions for Standard Modem
functionality:

* Magnetite hybrid is the current production firmware version.  The only blobs
  are Nucleus, OSL and OSX glue components of GPF, and TI's proprietary TMS470
  compiler.  Everything other than Nucleus and OSL/OSX is compiled from source,
  but the compiler is TI's proprietary TMS470.  The same Magnetite source tree
  also supports other configurations (maintained only for regression testing)
  which have more blobs, as well as handset configurations which are currently
  frozen for lack of suitable development hardware.

* Selenite-470 is FC Selenite built with TI's TMS470 compiler: all code is
  compiled from source, no blobs other than the compiler and its RTS library
  (libc/libgcc equivalent).  The blob version of Nucleus is replaced with a
  different (slightly newer) version in full source form, while the blob
  versions of OSL and OSX glue components have been replaced with reconstructed
  sources, i.e., a reconstruction based on disassembly.  This fw version is
  currently considered experimental, not cleared for production, and the reason
  is OSL/OSX: the reconstruction is of uncertain correctness and known to be
  incomplete.

* Selenite-gcc is FC Selenite built with gcc.  This version has no blobs
  whatsoever (there is no support in the gcc+binutils toolchain for TI's TMS470
  ABI, thus it is physically impossible to include any of TI's COFF blobs in
  the link), and it is built with a FLOSS compiler.  However, it is even more
  experimental and not-for-production than Selenite-470: not only is the OSL/OSX
  issue still there, but there is also widespread breakage from the use of a
  different compiler which was never anticipated by the original developers.
  The old FC Citrine firmware (unmaintained since 2016) also suffers from all
  of the same problems, plus additional ones, and therefore should not be
  considered at all.

When it comes to the firmware, right now those OSL and OSX glue components of
GPF form the biggest bone in our collective throat.  Just 10 C source files are
missing:

os_com.c
os_drv.c
os_evt.c
os_isr.c
os_mem.c
os_mis.c
os_pro.c
os_sem.c
os_tim.c
osx.c

If we can ever find these 10 missing files (does not even need to be exactly
the same version as in TCS211 GPF), then Selenite-470 would immediately become
the new production firmware replacing Magnetite (the Nucleus change isn't the
problem, it's OSL and OSX), and the way would be cleared to begin work on
bringing Selenite-gcc up to par.  But in the absence of these 10 files, the
following two interlocking problems get in the way of FC Selenite:

1) I (Mother Mychaela) am not willing to skip Selenite-470 and jump directly to
   Selenite-gcc, as doing so would violate the fundamental principle of
   incrementality: we need to be making one small change at a time, requiring
   full stability after each incremental change before going to the next.

2) I am not able to produce a reconstructed C source for certain parts of OSL
   which would result in correct object code when compiled with TMS470: the
   issue is potential race conditions in the OSL timer code.  The existing COFF
   object code avoids the race, I can produce C code for compilation with gcc
   which also avoids the race, but I don't know the requisite magic for C code
   to be compiled with TMS470.

At this point you are going to ask - OK, so what do we do if we can't find
those 10 missing files?  The Mother's current plan is as follows: if these 10
files are still missing when we get our handset UI development board built, I
will create a third firmware source tree (not Magnetite, not Selenite, but to
be named after some other mineral) with the following key properties:

* Just like Selenite, it will be hybrid only, no legacy blob-laden
  configurations;

* Both modem and handset configurations will be included;

* The compiler will be TMS470 - sorry, no gcc;

* The version of Nucleus will be the new source-enabled one, same as Selenite;

* I will do some careful surgery on the OSL/OSX blobs to make them work with
  the new version of Nucleus.

The result of these listed key properties is that the new firmware tree will
have blobs for OSL and OSX and will use the TMS470 compiler as required by
these blobs, but absolutely everything else will be source-enabled.  This
situation will then persist until someone can wave a few million dollars in
front of TI to convince their execs to direct their archivists to dig up the 10
missing files, or until the world civilization collapses into a Mad Max world,
allowing us to seize those archives with a Spetsnaz unit without police
interference.

Special modem applications
==========================

The above plan states that the third firmware source tree will be created as
described if the original OSL and OSX source files are still missing when we
get our handset UI development board built.  The reason for this coupling is
that when we get this UIDB built, the floodgates will open for intensive
handset UI development.  The latter work will need to be done without the
clutter of Magnetite, yet Selenite is blocked by the lack of the 10 missing
files - hence the case for the third firmware source tree as described above.

Alternatively, a third fw source tree similar to the one described (but perhaps
without the handset configuration) can be created if someone commissions
significant work on modem firmware, work that is significant enough to call for
a source tree that is as stable as Magnetite, but free of the clutter.

cdginc header files
===================

Another area of deblobbing that hasn't been done yet, but can be done when and
if a serious need arises, is the cdginc header file set.  The cdginc files which
are currently used for our hybrid config aren't blobs in the strict sense: they
are C header files included by the sources being recompiled, but they have been
auto-generated (from true human-editable sources which we do have) by a tool
(ccdgen) which currently exists only as a Windows binary sans source.

If anyone needs to make changes to cdginc, the proper course of action should
be to hire a Windows reverser to reverse ccdgen.exe and to produce a perfect
form, fit and function replacement.