Spiram: Add option to reserve MMU banks; add himem API to make use of those banks

docs/Doxyfile

@@ -147,6 +147,8 @@ INPUT = \
     ../../components/heap/include/esp_heap_trace.h \
     ../../components/heap/include/esp_heap_caps_init.h \
     ../../components/heap/include/multi_heap.h \
+    ## Himem
+    ../../components/esp32/include/esp_himem.h \
     ## Interrupt Allocation
     ../../components/esp32/include/esp_intr_alloc.h \
     ## Watchdogs

docs/en/api-reference/system/himem.rst

@@ -0,0 +1,33 @@
+The himem allocation API
+========================
+
+Overview
+--------
+
+The ESP32 can access external SPI RAM transparently, so you can use it as normal memory in your program code. However, because the address
+space for external memory is limited in size, only the first 4MiB can be used as such. Access to the remaining memory is still possible,
+however this needs to go through a bankswitching scheme controlled by the himem API.
+
+Specifically, what is implemented by the himem API is a bankswitching scheme. Hardware-wise, the 4MiB region for external SPI RAM is 
+mapped into the CPU address space by a MMU, which maps a configurable 32K bank/page of external SPI RAM into each of the 32K pages in the
+4MiB region accessed by the CPU. For external memories that are <=4MiB, this MMU is configured to unity mapping, effectively mapping each
+CPU address 1-to-1 to the external SPI RAM address.
+
+In order to use the himem API, you have to enable it in the menuconfig using :envvar:`CONFIG_SPIRAM_BANKSWITCH_ENABLE`, as well as set the amount 
+of banks reserved for this in :envvar:`CONFIG_SPIRAM_BANKSWITCH_RESERVE`. This decreases
+the amount of external memory allocated by functions like ``malloc()``, but it allows you to use the himem api to map any of the remaining memory
+into the reserved banks.
+
+The himem API is more-or-less an abstraction of the bankswitching scheme: it allows you to claim one or more banks of address space
+(called 'regions' in the API) as well as one or more of banks of memory to map into the ranges.
+
+Example
+-------
+
+An example doing a simple memory test of the high memory range is available in esp-idf: :example:`system/himem`
+
+
+API Reference
+-------------
+
+.. include:: /_build/inc/esp_himem.inc

docs/en/api-reference/system/index.rst

@@ -8,6 +8,7 @@ System API
    FreeRTOS Additions <freertos_additions>
    Heap Memory Allocation <mem_alloc>
    Heap Memory Debugging <heap_debug>
+   Himem (large external SPI RAM) API <himem>
    Interrupt Allocation <intr_alloc>
    Watchdogs <wdts>
    Inter-Processor Call <ipc>

docs/en/api-reference/system/mem_alloc.rst

@@ -40,6 +40,9 @@ which it can't do for a normal malloc() call. This can help to use all the avail
 Memory allocated with MALLOC_CAP_32BIT can *only* be accessed via 32-bit reads and writes, any other type of access will
 generate a fatal LoadStoreError exception.
 
+External SPI RAM under 4MiB in size can be allocated using standard ``malloc`` calls, if that is enabled in menuconfig. To
+use the region above the 4MiB limit, you can use the :doc:`himem API</api-reference/system/himem>`.
+
 API Reference - Heap Allocation
 -------------------------------
 

docs/zh_CN/api-reference/system/himem.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/system/himem.rst