--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Flash-boot-wa	Sun Feb 10 21:51:28 2019 +0000
@@ -0,0 +1,39 @@
+There is a tiny (120 bytes SREC file) program called flash-boot-wa that was
+written in the spring of 2017 for the purpose of working around a problem that
+happened on only one first-batch FCDEV3B board and never happened on any other
+board - but Murphy's law had it that this one troubled board just had to be the
+one on which my (Mother Mychaela's) very initial development and bring-up work
+was done.
+
+The defect exhibited on that one board was as follows: it had no problem booting
+serially (fc-iram, fc-loadtool, fc-xram) and it had no problem booting from
+flash in mode 0 (see the Flash-boot-modes article in the freecalypso-docs
+repository), but booting from flash in mode 1 (the flash boot mode used by
+FC Magnetite, which is our primary firmware) was troubled.  The exact failure
+mode and the root cause were never solved, but the issue most likely involved
+the watchdog reset in some way (it occurs as part of flash boot mode 1 but not
+in mode 0 and not in serial downloading), and because Calypso's FDP output goes
+low during watchdog reset (or at least TI's CAL000 document says so), it is
+plausible that the root cause involved the Spansion flash chip getting unhappy
+as a result of being jerked with extra resets which don't meet its reset timing
+requirements.
+
+Our new FCDEV3B V2 boards no longer use Calypso's FDP output (it is left
+unconnected) and feature a new flash reset circuit of our own design that meets
+the reset timing requirements of our Spansion flash chip, hence the flash boot
+problem seen on that one FCDEV3B S/N 001 board is not expected to recur on any
+of our current or future boards.  However, our little flash-boot-wa program is
+kept around: removing a previously-released 120-byte program for no good reason
+is not the way of FOSS.
+
+This flash-boot-wa program is loaded serially via fc-iram; it disables the boot
+ROM and jumps to address 0 (the opposite of what we do in compalstage for Mot
+C1xx phones), thereby indirectly booting the made-for-boot-mode-1 firmware image
+in the flash.  The intended usage was as follows:
+
+fc-iram -h fcfam /dev/ttyXXX /opt/freecalypso/target-bin/flash-boot-wa.srec rvinterf
+
+It is also worth noting that fc-iram has been extended to support second program
+invokation just like fc-xram (used in the invokation line above) just for this
+peculiar use case.  The flash-boot-wa.srec helper can also be booted via
+fc-xram.