-# Example: himem
+# _Himem API example_
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example uses the Himem API to run a memory test of the upper 4MiB of an 8MiB PSRAM chip.
+
+The ESP32 has the ability to access external SPI RAM in the same way as internal memory can be accessed, that is, if
+enabled in menuconfig, you can allocate memory in external RAM using standard C allocation APIs like `malloc()`, `calloc()`, etc.
+
+However, because of hardware limitations, this only works for up to 4MiB of external memory. If you have, for instance,
+an ESP32-WROVER module with 8MiB of PSRAM, you cannot use the upper 4MiB of PSRAM this way. However, this memory is not wasted,
+using the Himem API (which essentially is a bank switching scheme for the upper memory regions), it is still usable.
+
+The Himem subsystem does this by reserving some amount of address space, then allowing applications to swap in and out normally
+unreachable ranges of physical SPI RAM. While this does not allow transparent access in the way memory allocated with `malloc()` does,
+it does provide an usable way to store data for e.g. large audio or video buffers in the upper 4MiB.
+
+This example uses the Himem API to run a simple memory test of the entire range of upper memory. It illustrates how to allocate
+address space to bankswitch the physical memory in, allocate the physical memory, and switch it in or out of the allocated address space.
+
+## How to use example
+
+### Hardware Required
+
+This example requires an ESP32 with external SPI RAM connected, for instance an ESP32-WROVER module. The example is intended to run on
+an ESP32 with 8MiB external RAM connected. It will still run on an ESP32 with 4MiB external RAM, but in practice using Himem with such
+a setup does not make much sense.
+
+### Configure the project
+
+```
+make menuconfig
+```
+
+* Set serial port under Serial Flasher Options.
+
+* Make sure that SPI RAM bank switching is enabled. (Compiling the example with default values will automatically enable this.) It can be found under
+ Component config -> ESP32-specific -> Support for external, SPI-connected RAM -> SPI RAM config .
+
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+make -j4 flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+rst:0x1 (POWERON_RESET),boot:0x1e (SPI_FAST_FLASH_BOOT)
+configsip: 0, SPIWP:0xee
+clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
+mode:DIO, clock div:2
+load:0x3fff0018,len:4
+load:0x3fff001c,len:6124
+load:0x40078000,len:10084
+load:0x40080400,len:6552
+entry 0x40080764
+I (28) boot: ESP-IDF v3.2-dev-1455-ga51d5706f-dirty 2nd stage bootloader
+I (29) boot: compile time 18:51:28
+I (30) boot: Enabling RNG early entropy source...
+I (35) boot: SPI Speed : 40MHz
+I (39) boot: SPI Mode : DIO
+I (43) boot: SPI Flash Size : 4MB
+I (47) boot: Partition Table:
+I (51) boot: ## Label Usage Type ST Offset Length
+I (58) boot: 0 nvs WiFi data 01 02 00009000 00006000
+I (66) boot: 1 phy_init RF data 01 01 0000f000 00001000
+I (73) boot: 2 factory factory app 00 00 00010000 00100000
+I (81) boot: End of partition table
+I (85) esp_image: segment 0: paddr=0x00010020 vaddr=0x3f400020 size=0x0dde0 ( 56800) map
+I (114) esp_image: segment 1: paddr=0x0001de08 vaddr=0x3ff80000 size=0x00000 ( 0) load
+I (114) esp_image: segment 2: paddr=0x0001de10 vaddr=0x3ff80000 size=0x00000 ( 0) load
+I (120) esp_image: segment 3: paddr=0x0001de18 vaddr=0x3ffb0000 size=0x01fb4 ( 8116) load
+I (132) esp_image: segment 4: paddr=0x0001fdd4 vaddr=0x3ffb1fb4 size=0x00000 ( 0) load
+I (138) esp_image: segment 5: paddr=0x0001fddc vaddr=0x40080000 size=0x00234 ( 564) load
+I (147) esp_image: segment 6: paddr=0x00020018 vaddr=0x400d0018 size=0x180d4 ( 98516) map
+I (191) esp_image: segment 7: paddr=0x000380f4 vaddr=0x40080234 size=0x001cc ( 460) load
+I (191) esp_image: segment 8: paddr=0x000382c8 vaddr=0x40080400 size=0x0e14c ( 57676) load
+I (221) esp_image: segment 9: paddr=0x0004641c vaddr=0x400c0000 size=0x00000 ( 0) load
+I (222) esp_image: segment 10: paddr=0x00046424 vaddr=0x50000000 size=0x00000 ( 0) load
+I (228) esp_image: segment 11: paddr=0x0004642c vaddr=0x50000000 size=0x00000 ( 0) load
+I (245) boot: Loaded app from partition at offset 0x10000
+I (246) boot: Disabling RNG early entropy source...
+I (250) spiram: Found 64MBit SPI RAM device
+I (254) spiram: SPI RAM mode: flash 40m sram 40m
+I (259) spiram: PSRAM initialized, cache is in low/high (2-core) mode.
+I (266) cpu_start: Pro cpu up.
+I (270) cpu_start: Starting app cpu, entry point is 0x40081174
+I (0) cpu_start: App cpu up.
+I (735) spiram: SPI SRAM memory test OK
+I (735) heap_init: Initializing. RAM available for dynamic allocation:
+I (735) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM
+I (741) heap_init: At 3FFB3448 len 0002CBB8 (178 KiB): DRAM
+I (748) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM
+I (754) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
+I (760) heap_init: At 4008E54C len 00011AB4 (70 KiB): IRAM
+I (767) cpu_start: Pro cpu start user code
+I (771) spiram: Adding pool of 2112K of external SPI memory to heap allocator
+I (121) esp_himem: Initialized. Using last 62 32KB address blocks for bank switching on 6080 KB of physical memory.
+I (122) cpu_start: Starting scheduler on PRO CPU.
+I (0) cpu_start: Starting scheduler on APP CPU.
+I (132) spiram: Reserving pool of 32K of internal memory for DMA/internal allocations
+Himem has 6080KiB of memory, 6080KiB of which is free. Testing the free memory...
+Done!
+```
-This test tests the upper memory of an ESP32 system with 8MiB of PSRAM
-attached. Note that this (obviously) will not work unless the ESP32
-you're running this on actually does have 8MiB pf PSRAM.
projects / esp-idf / commitdiff