--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Flash-boot-mode-hack	Tue May 02 02:53:36 2017 +0000
@@ -0,0 +1,27 @@
+There are two ways in which a flashed firmware image may be booted, which we
+call mode 0 and mode 1 - see the Flash-boot-modes write-up in the
+freecalypso-tools repository for the details.  All TI official firmwares
+including our TCS211 reference version have used flash boot mode 1, and the
+present Magnetite firmware is unchanged in this regard.
+
+Some FCDEV3B boards have a non-understood hardware problem that causes flash
+boot to fail (the visible symptom is a dead hang with even JTAG not working)
+when the firmware image in flash uses boot mode 1.  It is not currently known
+how many boards are affected by this problem; it is possible that the Mother's
+S/N 001 board is the only one that exhibits this oddity.
+
+Once the discovery was made that the flash boot problem occurs only when the fw
+image uses flash boot mode 1, a workaround became apparent: switch to using
+flash boot mode 0.  Redesigning Magnetite fw to use interrupt and exception
+vectors in the ROM branching to 0x80001C-0x800034 in IRAM is not in line with
+the Mother's vision, but a surgical hack to make the Magnetite fw flash image
+receive control from the boot ROM in mode 0, disable the boot ROM via the
+FFFF:FB10 register and jump to 0 as if in mode 1 is quite doable, and it
+accomplishes the job of producing a flash image of FC Magnetite that boots
+without a hitch on the flash-boot-challenged FCDEV3B.
+
+The standard FC Magnetite build is unchanged and unaffected, i.e., the hack in
+question is NOT applied by default.  However, if you have a board that has
+trouble booting the regular Magnetite fwimage.bin that uses flash boot mode 1,
+you can run 'make fwimage.mode0' in your build directory to get an image patched
+with the flash boot mode 0 hack.