Enable 128K virtual memory via external SPI SRAM (#6994)

Provides a transparently accessible additional block of RAM of 128K to
8MB by using an external SPI SRAM.  This memory is managed using the UMM
memory manager and can be used by the core as if it were internal RAM
(albeit much slower to read or write).

The use case would be for things which are quite large but not
particularly frequently used or compute intensive.  For example, the SSL
buffers of 16K++ are a good fit for this, as are the contents of Strings
(both to avoid main heap fragmentation as well as allowing Strings of
>30KB).

A fully associative LRU cache is used to limit the SPI bus bottleneck,
and background writeback is supported.

Uses a define in boards.txt to enable.  If this value is not defined,
then the entire VM routines should not be linked in to user apps
so there should be no space penalty w/o it.

UMM `malloc` and `new` are modified to support internal and external
heap regions.  By default, everything comes from the standard heap, but
a call to `ESP.setExternalHeap()` before the allocation (followed by a
call to `ESP.resetHeap()` will make the allocation come from external
RAM.  See the `virtualmem.ino` example for use.

If there is no external RAM installed, the `setExternalHeap` call is a
no-op.

The String and BearSSL libraries have been modified to use this external
RAM automatically.

Theory of Operation:

The Xtensa core generates a hardware exception (unrelated to C++
exceptions) when an address that's defined as invalid for load or store.
The XTOS ROM routines capture the machine state and call a standard C
exception handler routine (or the default one which resets the system).

We hook into this exception callback and decode the EXCVADDR (the
address being accessed) and use the exception PC to read out the
faulting instruction. We decode that instruction and simulate it's
behavior (i.e. either loading or storing some data to a
register/external memory) and then return to the calling application.

We use the hardware SPI interface to talk to an external SRAM/PSRAM,
and implement a simple cache to minimize the amount of times we need
to go out over the (slow) SPI bus. The SPI is set up in a DIO mode
which uses no more pins than normal SPI, but provides for ~2X faster
transfers.  SIO mode is also supported.

NOTE: This works fine for processor accesses, but cannot be used by
any of the peripherals' DMA. For that, we'd need a real MMU.

Hardware Configuration (only use 3.3V compatible SRAMs!):

  SPI byte-addressible SRAM/PSRAM: 23LC1024 or smaller
    CS   -> GPIO15
    SCK  -> GPIO14
    MOSI -> GPIO13
    MISO -> GPIO12
 (note these are GPIO numbers, not the Arduino Dxx pin names.  Refer
  to your ESP8266 board schematic for the mapping of GPIO to pin.)

Higher density PSRAM (ESP-PSRAM64H/etc.) should work as well, but
I'm still waiting on my chips so haven't done any testing.  Biggest
concern is their command set and functionality in DIO mode.  If DIO
mode isn't supported, then a fallback to SIO is possible.

This PR originated with code from @pvvx's esp8266web server at
https://github.com/pvvx/esp8266web (licensed in the public domain)
but doesn't resemble it much any more.  Thanks, @pvvx!

Keep a list of the last 8 lines in RAM (~.5KB of RAM) and use that to
speed up things like memcpys and other operations where the source and
destination addresses are inside VM RAM.

A custom set of SPI routines is used in the VM system for speed and code
size (and because the core cannot be dependent on a library).

Because UMM manages RAM in 8 byte chunks, attempting to manage the
entire 1M available space on a 1M PSRAM causes the block IDs to
overflow, crashing things at some point.  Limit the UMM allocation to
only 256K in this case.  The remaining space can manually be assigned to
buffers/etc. managed by the application, not malloc()/free().

Author: earlephilhower

boards.txt

@@ -29,7 +29,6 @@
 
 #include "coredecls.h"
 #include "umm_malloc/umm_malloc.h"
-// #include "core_esp8266_vm.h"
 #include <pgmspace.h>
 #include "reboot_uart_dwnld.h"
 
@@ -984,22 +983,11 @@ String EspClass::getSketchMD5()
     return result;
 }
 
-void EspClass::enableVM()
-{
-#ifdef UMM_HEAP_EXTERNAL
-    if (!vmEnabled)
-        install_vm_exception_handler();
-    vmEnabled = true;
-#endif
-}
-
 void EspClass::setExternalHeap()
 {
 #ifdef UMM_HEAP_EXTERNAL
-    if (vmEnabled) {
-        if (!umm_push_heap(UMM_HEAP_EXTERNAL)) {
-            panic();
-        }
+    if (!umm_push_heap(UMM_HEAP_EXTERNAL)) {
+        panic();
     }
 #endif
 }
@@ -1016,10 +1004,8 @@ void EspClass::setIramHeap()
 void EspClass::setDramHeap()
 {
 #if defined(UMM_HEAP_EXTERNAL) && !defined(UMM_HEAP_IRAM)
-    if (vmEnabled) {
-        if (!umm_push_heap(UMM_HEAP_DRAM)) {
-            panic();
-        }
+    if (!umm_push_heap(UMM_HEAP_DRAM)) {
+        panic();
     }
 #elif defined(UMM_HEAP_IRAM)
     if (!umm_push_heap(UMM_HEAP_DRAM)) {
@@ -1031,10 +1017,8 @@ void EspClass::setDramHeap()
 void EspClass::resetHeap()
 {
 #if defined(UMM_HEAP_EXTERNAL) && !defined(UMM_HEAP_IRAM)
-    if (vmEnabled) {
-        if (!umm_pop_heap()) {
-            panic();
-        }
+    if (!umm_pop_heap()) {
+        panic();
     }
 #elif defined(UMM_HEAP_IRAM)
     if (!umm_pop_heap()) {

cores/esp8266/Esp.cpp

@@ -221,13 +221,6 @@ class EspClass {
 #else
         uint32_t getCycleCount();
 #endif // !defined(CORE_MOCK)
-        /**
-         * @brief Installs VM exception handler to support External memory (Experimental)
-         *
-         * @param none
-         * @return none
-         */
-        void enableVM();
         /**
          * @brief Push current Heap selection and set Heap selection to DRAM.
          *
@@ -258,9 +251,6 @@ class EspClass {
          */
         void resetHeap();
     private:
-#ifdef UMM_HEAP_EXTERNAL
-        bool vmEnabled = false;
-#endif
         /**
          * @brief Replaces @a byteCount bytes of a 4 byte block on flash
          *

cores/esp8266/Esp.h

@@ -37,6 +37,7 @@ extern "C" {
 #include "flash_quirks.h"
 #include <umm_malloc/umm_malloc.h>
 #include <core_esp8266_non32xfer.h>
+#include "core_esp8266_vm.h"
 
 
 #define LOOP_TASK_PRIORITY 1
@@ -348,9 +349,14 @@ extern "C" void user_init(void) {
 
     cont_init(g_pcont);
 
+#if defined(UMM_HEAP_EXTERNAL)
+    install_vm_exception_handler();
+#endif
+
 #if defined(NON32XFER_HANDLER) || defined(MMU_IRAM_HEAP)
     install_non32xfer_exception_handler();
 #endif
+
 #if defined(MMU_IRAM_HEAP)
     umm_init_iram();
 #endif

cores/esp8266/core_esp8266_main.cpp

@@ -64,51 +64,10 @@ static
 IRAM_ATTR void non32xfer_exception_handler(struct __exception_frame *ef, int cause)
 {
   do {
-    /*
-       In adapting the public domain version, a crash would come or go away with
-       the slightest unrelated changes elsewhere in the function. Observed that
-       register a15 was used for epc1, then clobbered by `rsr.` I now believe a
-       "&" on the output register would have resolved the problem.
-
-       However, I have refactored the Extended ASM to reduce and consolidate
-       register usage and corrected the issue.
-
-       The positioning of the Extended ASM block (as early as possible in the
-       compiled function) is in part controlled by the immediate need for
-       output variable `insn`. This placement aids in getting excvaddr read as
-       early as possible.
-     */
     uint32_t insn, excvaddr;
-#if 1
-    {
-      uint32_t tmp;
-      __asm__ (
-        "rsr.excvaddr %[vaddr]\n\t"             /* Read faulting address as early as possible */
-        "movi.n %[tmp],  ~3\n\t"                /* prepare a mask for the EPC */
-        "and    %[tmp],  %[tmp],  %[epc]\n\t"   /* apply mask for 32-bit aligned base */
-        "ssa8l  %[epc]\n\t"                     /* set up shift register for src op */
-        "l32i   %[insn], %[tmp],  0\n\t"        /* load part 1 */
-        "l32i   %[tmp],  %[tmp],  4\n\t"        /* load part 2 */
-        "src    %[insn], %[tmp],  %[insn]\n\t"  /* right shift to get faulting instruction */
-        : [vaddr]"=&r"(excvaddr), [insn]"=&r"(insn), [tmp]"=&r"(tmp)
-        : [epc]"r"(ef->epc) :);
-    }
 
-#else
-    {
-      __asm__ __volatile__ ("rsr.excvaddr %0;" : "=r"(excvaddr):: "memory");
-      /*
-        "C" reference code for the ASM to document intent.
-        May also prove useful when issolating possible issues with Extended ASM,
-        optimizations, new compilers, etc.
-      */
-      uint32_t epc = ef->epc;
-      uint32_t *pWord = (uint32_t *)(epc & ~3);
-      uint64_t big_word = ((uint64_t)pWord[1] << 32) | pWord[0];
-      uint32_t pos = (epc & 3) * 8;
-      insn = (uint32_t)(big_word >>= pos);
-    }
-#endif
+    /* Extract instruction and faulting data address */
+    __EXCEPTION_HANDLER_PREAMBLE(ef, excvaddr, insn);
 
     uint32_t what = insn & LOAD_MASK;
     uint32_t valmask = 0;

cores/esp8266/core_esp8266_non32xfer.cpp

@@ -7,6 +7,54 @@ extern "C" {
 
 extern void install_non32xfer_exception_handler();
 
+
+    /*
+       In adapting the public domain version, a crash would come or go away with
+       the slightest unrelated changes elsewhere in the function. Observed that
+       register a15 was used for epc1, then clobbered by `rsr.` I now believe a
+       "&" on the output register would have resolved the problem.
+
+       However, I have refactored the Extended ASM to reduce and consolidate
+       register usage and corrected the issue.
+
+       The positioning of the Extended ASM block (as early as possible in the
+       compiled function) is in part controlled by the immediate need for
+       output variable `insn`. This placement aids in getting excvaddr read as
+       early as possible.
+     */
+
+#if 0
+    {
+      __asm__ __volatile__ ("rsr.excvaddr %0;" : "=r"(excvaddr):: "memory");
+      /*
+        "C" reference code for the ASM to document intent.
+        May also prove useful when issolating possible issues with Extended ASM,
+        optimizations, new compilers, etc.
+      */
+      uint32_t epc = ef->epc;
+      uint32_t *pWord = (uint32_t *)(epc & ~3);
+      uint64_t big_word = ((uint64_t)pWord[1] << 32) | pWord[0];
+      uint32_t pos = (epc & 3) * 8;
+      insn = (uint32_t)(big_word >>= pos);
+    }
+#endif
+
+#define __EXCEPTION_HANDLER_PREAMBLE(ef, excvaddr, insn) \
+    { \
+      uint32_t tmp; \
+      __asm__ ( \
+        "rsr.excvaddr %[vaddr]\n\t"             /* Read faulting address as early as possible */ \
+        "movi.n %[tmp],  ~3\n\t"                /* prepare a mask for the EPC */ \
+        "and    %[tmp],  %[tmp],  %[epc]\n\t"   /* apply mask for 32-bit aligned base */ \
+        "ssa8l  %[epc]\n\t"                     /* set up shift register for src op */ \
+        "l32i   %[insn], %[tmp],  0\n\t"        /* load part 1 */ \
+        "l32i   %[tmp],  %[tmp],  4\n\t"        /* load part 2 */ \
+        "src    %[insn], %[tmp],  %[insn]\n\t"  /* right shift to get faulting instruction */ \
+        : [vaddr]"=&r"(excvaddr), [insn]"=&r"(insn), [tmp]"=&r"(tmp) \
+        : [epc]"r"(ef->epc) :); \
+    }
+
+
 #ifdef __cplusplus
 }
 #endif