changeset 556:39a226a06196

documentation update for rebuilding the easy parts of GPF from source
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 19 Nov 2018 02:00:21 +0000
parents 6690ae453594
children 7aad22344e77
files README doc/Modem-configs doc/Pirelli-Howto
diffstat 3 files changed, 34 insertions(+), 33 deletions(-) [+]
line wrap: on
line diff
--- a/README	Mon Nov 19 00:16:07 2018 +0000
+++ b/README	Mon Nov 19 02:00:21 2018 +0000
@@ -154,20 +154,17 @@
 Other blobs
 ===========
 
-The TCS2/TCS3 hybrid firmware is built almost entirely from source; the only
-components which are linked in the form of prebuilt libraries are GPF, Nucleus
-and the TMS470 compiler's equivalent of libc/libgcc.  It needs to be noted that
-these components are so stable and configuration-independent that they were
-used mostly in prebuilt library form even inside TI.  In the case of GPF we've
-got the corresponding source for most of the modules within those libs; for the
-few modules for which the original source has been lost (OSL and OSX), we have
-a reconstructed source and one can build a Magnetite config (hybrid-gpf) that
-uses these reconstructed versions of OSL and OSX instead of the blobs, but we
-are not 100% confident in the quality of this reconstruction, hence this
-hybrid-gpf config is currently considered experimental, not production.  In the
-case of Nucleus we likewise have another version of it in full source form
-which has been proven good in other FreeCalypso firmware projects, but it is
-not used in Magnetite.
+Our TCS2/TCS3 hybrid firmware is built almost entirely from source; the only
+components which are linked in the form of prebuilt objects or libraries are
+certain glue components in GPF (specifically OSL and OSX), the Nucleus PLUS RTOS
+and the TMS470 compiler's equivalent of libc/libgcc.  In the case of Nucleus we
+have another version of it in full source form, but switching to a different
+version of Nucleus is outside the scope of FC Magnetite - see the next section.
+In the case of OSL and OSX, we have a reconstructed source and one can build a
+Magnetite config (hybrid-osl) that uses these reconstructed versions of OSL and
+OSX instead of the blobs, but we are not 100% confident in the quality of this
+reconstruction, hence this hybrid-osl config is currently considered
+experimental, not production.
 
 Blob-free, gcc-built version
 ============================
--- a/doc/Modem-configs	Mon Nov 19 00:16:07 2018 +0000
+++ b/doc/Modem-configs	Mon Nov 19 02:00:21 2018 +0000
@@ -19,9 +19,12 @@
 		reconstructed source, and the same is done for the system
 		initialization code in main.lib.  The entire chipsetsw division
 		of the firmware (now in src/cs) is thus recompiled from source,
-		either original or reconstructed, and the only components that
-		are used as blobs are the G23M PS, GPF and Nucleus.  This
-		config can be built for all targets except c11x.
+		either original or reconstructed, and those parts of GPF for
+		which we have found matching sources are recompiled from those
+		sources as well.  The only components that are used as blobs
+		are the G23M PS, CCD and ccddata, OSL and OSX (glue parts of
+		GPF) and Nucleus.  This config can be built for all targets
+		except c11x.
 
 hybrid		This configuration is a TCS2/TCS3 hybrid.  Instead of using the
 		TCS211 version of the G23M protocol stack which we got only as
@@ -29,15 +32,16 @@
 		TCS3.2/LoCosto source, backported to work with L1 and the fw
 		foundation layers from TCS211.  ACI also had to be replaced with
 		the TCS3 version, and a special hybrid version of the cdginc
-		headers had to be constructed.  L1 and the init code are also
-		deblobbed as in l1reconst.  Like l1reconst, this config can be
-		built for all targets except c11x.
+		headers had to be constructed, giving us blob-free CCD and
+		ccddata.  L1, the init code and the easy parts of GPF are also
+		deblobbed as in l1reconst.  Only Nucleus, OSL and OSX remain as
+		blobs.  Like l1reconst, this config can be built for all targets
+		except c11x.
 
-hybrid-gpf	This configuration is just like the regular hybrid config, but
-		GPF libraries are recompiled from source along with the rest of
-		the fw.  For some parts of GPF (OSL and OSX components) no
-		original source could be found, thus the source we are using
-		has been reconstructed from disassembly.
+hybrid-osl	This configuration is just like the regular hybrid config, but
+		all of GPF is recompiled from source, including OSL and OSX glue
+		layers.  The source for these components has been reconstructed
+		from disassembly - see below for the issues.
 
 All 4 of the above configurations have CSD, fax and GPRS enabled; this
 functionality can only be exercised on those hardware targets on which both
@@ -77,14 +81,14 @@
 good for CSD functionality in addition to the better-tested voice, SMS and GPRS.
 
 When exercising our hybrid firmware in a production or semi-production setting,
-you should use the regular hybrid config for now, not hybrid-gpf.  GPF contains
+you should use the regular hybrid config for now, not hybrid-osl.  GPF contains
 a sublayer called OSL (OS Adaptation Layer), a glue layer between GPF and
 Nucleus, and we got absolutely no source for it, only binary objects.  The new
-hybrid-gpf config uses a reconstructed source for OSL (reconstructed from
-disassembly), same as our earlier Citrine firmware, and it is intended to serve
-as the basis for the planned new FreeCalypso Selenite fw project.  There is a
-lot of code in OSL, the reconstruction from disassembly has been a significant
-work, and there are a few issues with the reconstructed source:
+hybrid-osl config uses a reconstructed source for OSL (reconstructed from
+disassembly), same as our earlier Citrine firmware, and it was introduced into
+Magnetite to serve as a stepping stone toward FC Selenite.  There is a lot of
+code in OSL, the reconstruction from disassembly has been a significant work,
+and there are a few issues with the reconstructed source:
 
 * The reconstruction was really a process of writing new C code that matches
   the logic found in the disassembly of the original, and in some places this
@@ -93,7 +97,7 @@
 
 * An error handling function called os_SystemError() is currently stubbed out:
   reconstructing its original logic from disassembly is quite difficult, so it
-  being deferred for now.
+  is deferred for now.
 
 * Given the complexity, some of the logic may have been reconstructed
   incorrectly, thus extensive testing will be needed.
--- a/doc/Pirelli-Howto	Mon Nov 19 00:16:07 2018 +0000
+++ b/doc/Pirelli-Howto	Mon Nov 19 02:00:21 2018 +0000
@@ -49,7 +49,7 @@
 configurations (in the ./configure.sh sense) for VPM targets are hybrid-vpm and
 l1reconst-chg.  Because of the huge RAM, you can also compile and run our more
 traditional configurations intended for proper modems like FCDEV3B (l1reconst,
-hybrid or hybrid-gpf), but all data services functionality of those fw configs
+hybrid or hybrid-osl), but all data services functionality of those fw configs
 (CSD and GPRS) will remain inaccessible (dead weight) when running on the
 Pirelli.  Furthermore, our FreeCalypso battery charging code is only included
 in the special hybrid-vpm and l1reconst-chg configs, not in the traditional