--- /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.