Modem configurations
====================

If you would like to build our Magnetite firmware for the Standard Modem
functionality (voice, SMS, CSD, fax and GPRS services enabled, control via AT
commands, no UI, two UARTs are expected to be available for the AT command
interface and for the RVTMUX binary packet interface), you have 4 specific
configurations to choose from, differing in the level of deblobbing:

classic		This configuration replicates classic TCS211, just like
		leo2moko from 2013.  Almost all of the original binary blob
		libraries are used; the only components that are recompiled
		from source are those which we got in source form with our copy
		of TCS211 from Sotovik.  This config can only be built for the
		fcdev3b and gtamodem targets, not any others.

l1reconst	In this configuration the Layer1 component of the firmware
		(which came as a blob in our copy of TCS211) is recompiled from
		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 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
		binary blobs, this config uses the G23M PS version from the
		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, 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-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
Calypso UARTs are brought out, with the MODEM UART presenting a standard ASCII
AT command interface including data functions, while the IrDA UART carries the
RVTMUX interface for debug trace and other development functions.  If you are
interacting with your Calypso target modem or pseudo-modem solely through
RVTMUX, without access to the ASCII AT command interface on the dedicated MODEM
UART, then the data functions of the firmware are inaccessible and act as dead
weight.

Having fully deblobbed all of L1, we now have the ability to build our hybrid
firmware not only for the Standard Modem functionality with all data services
enabled as above, but also in a stripped-down "voice pseudo-modem"
configuration - see the Voice-pseudo-modem article.

The deblobbing of L1 has been done in a very meticulous manner, ensuring that
each individual reconstructed C module compiles into a strict functional
equivalent of the original binary blob, sometimes even matching bit for bit -
thus no regressions are expected with the classic->l1reconst transition, and no
extensive testing is deemed necessary beyond the basic tests that have already
been done.  However, the transition from l1reconst to hybrid involves wholesale
replacement of two major firmware components (G23M PS and ACI) and some
important associated support pieces with entirely different versions from a
different TI program, hence it can certainly benefit from more thorough testing.

So far the most-deblobbed hybrid config looks very promising: voice, SMS and
GPRS work perfectly in my (Mother Mychaela's) lab environment, and even CSD has
finally been proven to work as well on 2018-06-21.  CSD functionality has been
extremely difficult to test because it has been very unreliable lately on the
network side in my geographical location (T-Mobile USA), with CSD calls failing
something like 99.9% of the time with a NO CARRIER response to the ATD command,
using exactly the same modem hardware and firmware that worked flawlessly for
CSD several years earlier, which makes it extremely difficult to test CSD calls
with new firmware - but I finally succeeded in making a CSD call from an FCDEV3B
running FC Magnetite hybrid on 2018-06-21, proving that the new hybrid fw is
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-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-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
  new C code was written with gcc in mind.  Recompilation of this code with
  TI's proprietary TMS470 compiler may not be fully trustworthy.

* An error handling function called os_SystemError() is currently stubbed out:
  reconstructing its original logic from disassembly is quite difficult, so it
  is deferred for now.

* Given the complexity, some of the logic may have been reconstructed
  incorrectly, thus extensive testing will be needed.