--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Bootloader	Sat Sep 22 05:59:38 2018 +0000
@@ -0,0 +1,90 @@
+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.