--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FCDEV3B-hardware-bug	Sun Mar 25 07:07:49 2018 +0000
@@ -0,0 +1,49 @@
+Our current FCDEV3B boards exhibit a hardware bug: the reset input to the flash
+chip is connected to Calypso's FDP output per both TI's Leonardo reference
+schematics and Openmoko's working design, but this arrangement turns out to be
+unsuitable for the high-capacity Spansion S71PL129NC0HFW4B flash+pSRAM chip we
+are using, copied from Pirelli DP-L10.  This hardware bug has manifested itself
+in two different ways so far:
+
+* Out of the 20 boards we've built so far, on just one board there was an issue
+  where our standard Magnetite fw would have trouble booting from flash, but
+  RAM-loaded fw booted fine.  Interrupting the boot process serially and having
+  the serially loaded code jump to the image in flash also worked fine.
+  Eventually it was found that the flash boot problem on that one board occurs
+  only when flash boot mode 1 is used, whereas flash boot mode 0 works fine.  I
+  (Mychaela) suspect that the problem has something to do with the watchdog
+  reset that happens as part of flash boot mode 1, the FDP output behaviour
+  during that watchdog reset, and the flash chip's reaction to the latter.
+
+* On all of the boards there is a problem with sleep modes: when the firmware
+  is running from flash as opposed to RAM, certain sleep-wake sequences cause
+  an erratic self-reboot or a hang.  It is suspected (though not proven yet)
+  that the FDP output goes low during all sleep modes, our Spansion flash chip
+  gets unhappy with the reset timing it gets subjected to, and some flash reads
+  (instruction fetches) don't work after wakeup.  So far the only workable
+  solution has been to disable all sleep modes in all FCDEV3B fw builds;
+  nothing else has been successful.
+
+The fcdev3b-hacks directory contains two hacks that can be applied to FCDEV3B
+firmware images (fwimage.bin builds) as xxd binary patches:
+
+* The first hack dating from 2017-05 patches the fw to use flash boot mode 0
+  instead of TI's original flash boot mode 1, but after boot the FFFF:FB10
+  register is set to put the flash and not the internal ROM at address 0, so
+  the interrupt and exception vectors go to the flash like in TI's original fw,
+  not through the internal ROM.  This hack was put together for the purpose of
+  producing flashable fw images that boot without problems on that one board on
+  which flash boot mode 1 didn't work, and worked successfully for that purpose.
+
+* The second hack dating from 2018-03 patches the fw to not only use flash boot
+  mode 0, but also route the interrupt and exception vectors through Calypso's
+  internal ROM.  I was hoping that this hack would make the sleep mode problem
+  go away by having the Calypso execute some cycles out of its internal ROM and
+  RAM before hitting the flash after wakeup, but nope, bringing up the SIM
+  interface with AT+CFUN=1 in the l1reconst config when running from flash with
+  small sleep enabled still triggers erratic misbehaviour even with this patch.
+
+The proper fix will be to change the PCB to not connect the flash chip's reset
+input to FDP any more, and connect it to a pull-up resistor instead.  But this
+fix will require an expensive PCB respin, hence some experiments to test this
+idea will need to be done first.

--- a/doc/Flash-boot-mode-hack	Sun Mar 25 06:02:12 2018 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,27 +0,0 @@
-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.