--- a/doc/Config-vars	Sat Jan 12 17:53:32 2019 +0000
+++ b/doc/Config-vars	Sat Jan 12 19:46:58 2019 +0000
@@ -91,6 +91,7 @@
 	in the firmware version ID string compiled into the image.  The naming
 	of suffixes is up to you, but here are some examples:
 
+	DISABLE_SLEEP=1 SUFFIX=-nosleep
 	DSAMPLE_FULL_COLOR=0 UI_CONFIG=bigbw SUFFIX=-bw
 	L1_DYN_DSP_DWNLD=0 SUFFIX=-nodyn
 	MELODY_E2=0 SUFFIX=-noe2

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

--- a/doc/FCDEV3B-hardware-bug	Sat Jan 12 17:53:32 2019 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,60 +0,0 @@
-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.  Oscilloscope probing on a decased Pirelli
-  DP-L10 motherboard on which Calypso's FDP output is accessible seems to
-  confirm my (Mychaela's) suspicion that this FDP signal goes low during all
-  sleep modes, and the current working hypothesis is that 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.  However, re-enabling all of these sleep
-  modes with AT%SLEEP=4 works fine when the firmware image executes out of RAM
-  instead of flash, further supporting our current working hypothesis as to the
-  root cause.
-
-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 require a new PCB spin to change the flash reset wiring:
-instead of driving it with Calypso's FDP output, use the ON_nOFF master reset
-signal from Iota's VRPC block, fed through a logic voltage level translating
-buffer to change it from 1.5 V to 2.8 V logic.  The flash chip we are using has
-lower power consumption when it is NOT held in reset, hence unlike TI's intent
-with FDP, we don't want our flash chip to go into reset during any sleep at all.
-
-The new PCB revision with this change is now in the process of being finalized,
-and we will soon need the funding to produce the new boards.  Anyone who is
-interested in helping to make FCDEV3B V2 a reality should email Mychaela.