--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FCDEV3B-V1-issues	Sat Jan 12 19:46:58 2019 +0000
@@ -0,0 +1,73 @@
+Our early FCDEV3B boards (the first two batches made in 2017, now retroactively
+called FCDEV3B V1) had a hardware design defect that affected sleep modes; this
+defect has been fixed on our current FCDEV3B V2 boards.  The design defect on
+FCDEV3B V1 was as follows: the reset input to the flash chip was 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.  Calypso always drives its FDP output low during all sleep
+periods, including small sleep which can be arbitrarily short, and while TI may
+have thought it was a good idea to plunge the flash chip into reset during all
+sleeps, even ultra-short ones, newer flash chips like our current Spansion part
+are not happy with such reset timing.  The datasheet for S29PL-N flash (the
+flash part of S71PL-N MCPs) says that the minimum reset pulse width must be
+30 us, and the "dance" put out on FDP by the Calypso during certain rapid
+sleep-wake sequences appears to violate this timing requirement.  Furthermore,
+with our current flash chips (both our chosen Spansion part and OM's original
+Samsung K5A32xx) there is no power saving advantage to putting the flash chip
+into reset (in fact, with Spansion flash it is the opposite according to the
+datasheet!), hence the solution is straightforward: on our current FCDEV3B V2
+boards we have disconnected FDP from the flash chip, and we use a different
+circuit to provide our flash chip with the reset which it requires.
+
+The practical effect of the just-described hw defect on FCDEV3B V1 boards is
+that all sleep modes must be disabled when the firmware is running from flash
+(run-from-RAM firmwares are not affected), otherwise the firmware will
+erratically hang or self-reboot on certain sleep-wake sequences.  If you have
+an FCDEV3B V1 board and you would like to run our current FC Magnetite firmware
+on it, you have two options for disabling sleep:
+
+Option 1: You can flash a regular sleep-enabled fw build, and then on every
+boot, before doing anything else, issue an AT%SLEEP=0 command to disable all
+sleep modes.
+
+Option 2: You can compile a special fw build that boots with all sleep modes
+disabled:
+
+./configure.sh fcdev3b hybrid DISABLE_SLEEP=1 SUFFIX=-nosleep
+
+Additionally, there was one (only one) FCDEV3B V1 board from the very first
+batch (kept by the Mother and not sold or given away to anyone) that had
+trouble booting from flash on normal power-up.  By Murphy's law, it just
+happened to be the one board on which our very initial bring-up work was done.
+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, but
+regular flash boot exhibited erratic behaviour.  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.
+
+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 without a hardware respin 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.
+
+Just to reiterate, none of these hacks are needed for our current FCDEV3B V2
+boards - instead I am merely preserving our development history here.