From cb20ba50b14f83ad998030a0651def089b40cba9 Mon Sep 17 00:00:00 2001 From: Jeroen Domburg Date: Wed, 31 Oct 2018 18:56:21 +0800 Subject: [PATCH] Proper README.md for himem example --- examples/system/himem/README.md | 116 ++++++++++++++++++++++++++++++-- 1 file changed, 112 insertions(+), 4 deletions(-) diff --git a/examples/system/himem/README.md b/examples/system/himem/README.md index 700df059f1..0bc8a624c2 100644 --- a/examples/system/himem/README.md +++ b/examples/system/himem/README.md @@ -1,5 +1,113 @@ -# 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.