--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/frbl/README	Sat Mar 07 06:54:17 2020 +0000
@@ -0,0 +1,43 @@
+TI's TCS211 firmware and its predecessors contain a flash-resident bootloader
+stage which we call FRBL.  This FRBL implements not one but two different
+protocols for interrupting the normal fw boot process, downloading a code image
+into RAM and jumping to it; we call these two protocols FRBL1 and FRBL2.  The
+reasons for this oddity are historical: the original FRBL (TI GSM bootloader or
+TI GSM monitor or whatever it was called officially) consisted of cmdboot.c,
+command.c, convert.c, optboot.c, serial.c and start.c source modules and
+implemented the protocol we call FRBL1, then came MMJ and other TIDK people
+with their new FLUID idea, they decided on a different protocol which we call
+FRBL2, and they jerry-rigged their new FLUID bootloader into the firmware's
+FRBL code.
+
+The original source for FRBL1 C modules appears to have been lost (it is not
+present in what we presume to be the world's last surviving copy of TCS211 from
+OM), all we have are COFF objects from TI-OM's 20070608 build.  The reconst
+subdirectory contains our reconstruction attempt; this reconstruction is of
+poor quality because these particular COFF objects have only minimal symbolic
+information required for linking, as opposed to the much richer -g kind we got
+for L1 and GPF.
+
+The test subdirectory is intended to contain our frbl1test and frbl2test
+programs; only frbl2test has been written so far.
+
+Aside from implementing two different serial protocols, TI's FRBL as featured
+in their Calypso firmwares has one other major quirk: both FRBL1 and FRBL2 were
+implemented on 13 MHz platforms (the original purpose was to facilitate fw
+loading on TI's earlier DBB chips before Calypso that didn't have the boot ROM
+which we are so used to), on TI's D-Sample board (Calypso chip, 13 MHz CLKTCXO
+input) both the old way (fluid -oO via FRBL or via JTAG) and the new way
+(fluid -oo via the boot ROM) work well, but FRBL was never updated for 26 MHz
+platforms, thus on all practical Calypso platforms (Leonardo derivatives) one
+must use the boot ROM, not FRBL.
+
+TI's TCS211 builds for Leonardo and all vendor firmwares (Openmoko etc) derived
+from this reference do include FRBL which was never updated for 26 MHz CLKTCXO
+input on these platforms.  The result is that FRBL will only work if you talk
+to it at 230400 baud instead of TI's intended 115200 baud.  TI's official
+version of FLUID does not support FRBL entry at 230400 baud and such operation
+was clearly never intended or officially supported - instead the officially
+supported way for Leonardo and Leonardo-based customer designs was to use
+fluid -oo mode, which works through the boot ROM just like fc-loadtool.
+However, there is a possibility that Openmoko may have tried to turn this FRBL
+bug into a feature - we are still investigating.