As we understand it, TI's earlier DBB (digital baseband processor) chips prior
to our Calypso did not have an on-chip ARM boot ROM: instead they would execute
code directly out of flash immediately out of reset, like our Calypso does when
its boot ROM is disabled with nIBOOT high.  To get the firmware code into the
flash initially, one had to either use JTAG or populate preprogrammed chips
onto the board, and if you bricked your flash, you were screwed without JTAG.

To assist with loading new firmware images during casual development, TI
incorporated a bootloader stage into their firmware architecture.  This
bootloader stage is placed at the beginning of the flash at the reset vector,
and the rest of the firmware begins at an erase unit boundary.  The bootloader
stage executes first, and before it jumps to the main firmware entry point
(_INT_Initialize) for normal boot, it offers an opportunity for the boot process
to be interrupted and diverted if an external host sends certain magic command
packets into either of the two UARTs during the allotted time window.  If the
external host does interrupt and divert the boot process in this manner, it can
feed a code image to the bootloader to be written somewhere in target RAM, and
then command the bootloader to jump to it.  It is exactly the same functionality
(though with different serial protocol specifics) as implemented in the Calypso
boot ROM.  The ROM version is obviously superior because it is unbrickable, but
the flash-resident, built-with-firmware version is what TI used before they
came up with the idea of the boot ROM for the Calypso.

When the boot-ROM-equipped Calypso came along, TI kept the flash-resident
bootloader in the firmware: it does no harm aside from adding a little bit of
delay to the boot process, it does not conflict with the ROM bootloader as the
two speak different serial protocols and respond to different interrupt-boot
sequences, and it allowed TI to keep the same firmware architecture for
platforms with and without a boot ROM.  (Using flash boot mode 1, TI's firmwares
boot and run exactly the same way whether the Calypso boot ROM is present and
enabled or not.)  However, in our FreeCalypso firmwares starting with Magnetite
we have removed this extra bootloader stage for the following reasons:

* It is not useful to us on any of our hardware targets: on those devices that
  have the Calypso boot ROM enabled, we use that boot ROM and get full
  unbrickability, whereas on Mot C1xx phones we have to work with Mot/Compal's
  own different bootloader and serial protocol at least initially, hence it
  makes the most sense to stick with the same after the conversion to
  FreeCalypso as well.

* As delivered by TI with their full production TCS211 fw releases, their
  firmware-resident bootloader works as intended only on hw platforms with
  13 MHz VCXOs like the original D-Sample (Clara RF), and is broken on platforms
  like Rita RF (the only RF chip for which we have driver code!) with 26 MHz
  VCXOs: there is no conditionally-compiled code anywhere in the bootloader
  code path to set the VCLKOUT_DIV2 bit in the CNTL_CLK register on 26 MHz
  platforms, thus the UARTs are fed with 26 MHz instead of the standard 13 MHz
  clock expected in normal operation, and the intended baud rate of 115200 bps
  turns into 230400.  Because 230400 bps is a baud rate which Calypso UARTs
  *cannot* produce in normal GSM operation (when the peripheral clock network
  runs at the expected 13 MHz), tools that are designed to talk to Calypso GSM
  devices are typically not designed to support this baud rate.  In particular
  for CP2102 USB-serial adapters, the precedent established by the factory
  CP2102 EEPROM programming in the Pirelli DP-L10 phone is that the baud rate
  entry for 230400 bps is replaced with 203125 bps, which is a valid baud rate
  for Calypso UARTs running at 13 MHz.

* We have no source for TI's firmware-resident bootloader, only linkable binary
  objects that came with our world's last surviving copy of TCS211, which are
  incompatible with our goal of blob-free firmware.

Because this extra bootloader stage is ultimately unnecessary in our
environment, the deblobbing goal was easier accomplished by removing it
altogether instead of expending effort on a blob-free replacement.  Because I
wasn't comfortable with modifying TMS470 assembly code and linker script magic,
the removal of the bootloader was accomplished by stubbing out its C body with
an empty function.  A 'build_lib bootloader' instruction in a firmware
configuration recipe causes a dummy do-nothing bootloader to be built from this
stubbed-out source.

We have been removing (stubbing out) the bootloader from our TCS211-based
firmwares since 2015, but in 2018-09 I (Mother Mychaela) finally took the time
to study TI's bootloader code via disassembly and finally figured out what it
does and how it works.  Now that it is no longer an unknown, it may be
interesting to build some fw images with this bootloader blob re-enabled for
experimentation purposes, and a new experimental (not for production!)
l1reconst-bl configuration has been created for this purpose.  The bootloader
blob has also been re-enabled in the classic configuration, whose only purpose
is to serve as a reference point that preserves almost everything from our
TCS211/Leonardo starting point.

Finally, it needs to be noted for the sake of completeness that Compal's
bootloader used on Mot C1xx phones is a modified version based on TI's original
bootloader.  However, this factoid matters only for historians and genealogists;
for all practical purposes it is an unrelated animal, as Mot/Compal's serial
protocol for interrupting and diverting the boot process is their own and bears
no resemblance to TI's version.  And yes, Mot/Compal's version does set the
VCLKOUT_DIV2 bit in the CNTL_CLK register to adjust for the 26 MHz clock input
as its first order of business; it was probably the very first issue they had
to fix.