--- a/README	Sun Mar 19 23:41:49 2017 +0000
+++ b/README	Mon Mar 20 00:37:25 2017 +0000
@@ -1,61 +1,48 @@
-The purpose of this Hg tree (derived from leo2moko-debug) is to facilitate an
-attempt at reconstructing an L1 source that would match the binary object
-version we got with our TCS211 semi-src delivery from Sotovik.
-
-The idea is to deblob TCS211 L1 one module or small group of modules at a time.
-Take individual C modules from the LoCosto L1 source and get them to compile
-in the TCS211 environment with TCS211 versions of all include files, producing
-new from-source objects that would serve as candidate replacements for the ones
-we got as blobs.  An absolutely essential aspect of this approach is
-incrementality: we should be able to deblob just a few L1 objects (replace them
-with build-from-source versions) while keeping the original blobs for all other
-parts of L1 we haven't reached yet, and regression-test at each step to ensure
-that the firmware still works.
+This Hg repository contains a version of TI's TCS211 firmware based on our sole
+available TCS211 semi-src with the L1 component almost fully deblobbed.
+Specifically, we have deblobbed all of L1 with the exception of GPRS-specific
+l1p_*, macs and p_tpudr12 modules - all other L1 modules are recompiled from
+reconstructed C sources, producing objects that work in the place of the
+original blobs - sometimes matching bit for bit, in other cases differing in
+the bits, but matching in logic.  See STATUS for a detailed analysis of the
+reconstruction matches and differences.
 
-TI's build system for this fw does not provide very fine granularity as far as
-compiling each individual module from source or taking it as a delivered blob.
-Instead it operates on the granularity of libs, or sometimes (as in the case of
-L1) groups of libs.  In the case of L1, this tree has the build system set up
-to rebuild l1_ext.lib and l1_int.lib from source, which necessarily includes
-_everything_ that goes into these libs.  We are nowhere close to having a
-working reconstructed source for every module in these two libs, thus we have
-dummies in the place of most of them to appease BuSyB.  Therefore, if you
-simply run ./winebuild.sh to build this fw version, the link step will fail.
+Building the firmware in this tree requires a trick because of the not-yet-
+deblobbed L1_GPRS modules - see README.old for the details.  This tree only
+supports the original gtamodem target; see FreeCalypso Magnetite for other
+target support.
 
-Instead this fw has to be built in a somewhat convoluted way:
-
-1. Run ./winebuild.sh initially to compile everything leading up to the link
-   step, and let it fail.
+Choice of version for reconstruction
+====================================
 
-2. Go into g23m/__out__/gsm*/obj/l1_ext, and copy in original blob objects for
-   all those modules which have not been source-reconstructed yet.  Do likewise
-   for l1_int.
-
-   [Update: the copyblobs.sh script does this job now.]
+For some of the L1 objects (those packaged in l1_ext.lib and l1_int.lib) we
+have two versions: the original from 20070608 (the same date as the rest of our
+TCS211 semi-src) and an updated version of the l1_{ext,int}.lib set from
+20080421.  To the best of our knowledge, this 20080421 update was provided by
+TI-Taiwan while engaged in a wild goose chase after the infamous bug #1024,
+which later turned out to be a pure hardware problem, not involving the firmware
+at all.
 
-3. Run ./winebuild.sh again.  As long as the dummy C files have not been
-   touched and the copied-in objects have newer timestamps, the dummies won't
-   be recompiled and the copied-in objects won't get blown away.  TI's make
-   will rerun the ar packaging step to produce l1_ext.lib and l1_int.lib from
-   the mix of objects (some compiled from source, others copied-in blobs) in
-   the obj directories, and then the final link should succeed.
-
-The development process is as follows:
+The differences between the two versions are limited to just 3 objects:
+l1_cmplx.obj and l1p_cmpl.obj in l1_ext.lib, and l1_ctl.obj in l1_int.lib.
 
-1. Choose an individual L1 C module to work on.
-
-2. Copy the source for the chosen module from the LoCosto source in the place
-   of the dummy in this tree.
-
-3. Run ./winebuild.sh in the g23m directory and examine the output in
-   report.txt.  If the imported C module fails to compile, massage it until it
-   passes compilation.
+When we were reconstructing l1_cmplx.c and l1_ctl.c from the available LoCosto
+source, the reconstruction of the original 20070608 version came more easily
+than the 20080421 update, and our reconstruction of these two modules matches
+the 20070608 objects bit for bit.  It thus appears that whatever changes TI's
+customer support group made in that 20080421 version were not on TI's internal
+mainline.
 
-4. Once compilation passes, look at the generated COFF object in
-   g23m/__out__/gsm*/obj/l1_{ext,int}.  Disassemble it with the tiobjd tool
-   from freecalypso-reveng, and compare against the disassembly of the
-   original ("official") binary blob version we got.  Massage the reconstructed
-   source until it compiles into object code that matches the original.
+Because the 20080421 L1 libs update was made for no other purpose except an
+attempt to debug or fix what was erroneously believed to be a firmware problem
+but turned out to be hw instead, we have every reason to believe that it does
+not improve anything and is ultimately unnecessary.  And because the original
+20070608 version was easier to source-reconstruct than the other, we are
+adopting the original 20070608 version and our reconstruction of its C source
+form as the canonical version of TCS211 L1 for FreeCalypso.
 
-   [Update: use the scripts under g23m/objdiff to facilitate the disassembly
-    and diffing.]
+Note that because we have not source-reconstructed the GPRS-specific l1p_*
+modules yet, we haven't looked at the l1p_cmpl.obj differences yet.  However,
+when building a complete fw image with GPRS included using our partially
+reconstructed L1, one should use the 20070608 version of the l1p_cmpl.obj blob
+for consistency, like we do in FreeCalypso Magnetite.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.old	Mon Mar 20 00:37:25 2017 +0000
@@ -0,0 +1,61 @@
+The purpose of this Hg tree (derived from leo2moko-debug) is to facilitate an
+attempt at reconstructing an L1 source that would match the binary object
+version we got with our TCS211 semi-src delivery from Sotovik.
+
+The idea is to deblob TCS211 L1 one module or small group of modules at a time.
+Take individual C modules from the LoCosto L1 source and get them to compile
+in the TCS211 environment with TCS211 versions of all include files, producing
+new from-source objects that would serve as candidate replacements for the ones
+we got as blobs.  An absolutely essential aspect of this approach is
+incrementality: we should be able to deblob just a few L1 objects (replace them
+with build-from-source versions) while keeping the original blobs for all other
+parts of L1 we haven't reached yet, and regression-test at each step to ensure
+that the firmware still works.
+
+TI's build system for this fw does not provide very fine granularity as far as
+compiling each individual module from source or taking it as a delivered blob.
+Instead it operates on the granularity of libs, or sometimes (as in the case of
+L1) groups of libs.  In the case of L1, this tree has the build system set up
+to rebuild l1_ext.lib and l1_int.lib from source, which necessarily includes
+_everything_ that goes into these libs.  We are nowhere close to having a
+working reconstructed source for every module in these two libs, thus we have
+dummies in the place of most of them to appease BuSyB.  Therefore, if you
+simply run ./winebuild.sh to build this fw version, the link step will fail.
+
+Instead this fw has to be built in a somewhat convoluted way:
+
+1. Run ./winebuild.sh initially to compile everything leading up to the link
+   step, and let it fail.
+
+2. Go into g23m/__out__/gsm*/obj/l1_ext, and copy in original blob objects for
+   all those modules which have not been source-reconstructed yet.  Do likewise
+   for l1_int.
+
+   [Update: the copyblobs.sh script does this job now.]
+
+3. Run ./winebuild.sh again.  As long as the dummy C files have not been
+   touched and the copied-in objects have newer timestamps, the dummies won't
+   be recompiled and the copied-in objects won't get blown away.  TI's make
+   will rerun the ar packaging step to produce l1_ext.lib and l1_int.lib from
+   the mix of objects (some compiled from source, others copied-in blobs) in
+   the obj directories, and then the final link should succeed.
+
+The development process is as follows:
+
+1. Choose an individual L1 C module to work on.
+
+2. Copy the source for the chosen module from the LoCosto source in the place
+   of the dummy in this tree.
+
+3. Run ./winebuild.sh in the g23m directory and examine the output in
+   report.txt.  If the imported C module fails to compile, massage it until it
+   passes compilation.
+
+4. Once compilation passes, look at the generated COFF object in
+   g23m/__out__/gsm*/obj/l1_{ext,int}.  Disassemble it with the tiobjd tool
+   from freecalypso-reveng, and compare against the disassembly of the
+   original ("official") binary blob version we got.  Massage the reconstructed
+   source until it compiles into object code that matches the original.
+
+   [Update: use the scripts under g23m/objdiff to facilitate the disassembly
+    and diffing.]