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 CONFIG_SPIRAM_BANKSWITCH_ENABLE, as well as set the amount of banks reserved for this in 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: system/himem

API Reference

Functions

esp_err_t esp_himem_alloc(size_t size, esp_himem_handle_t *handle_out)

Allocate a block in high memory.

Return
- ESP_OK if succesful
  • ESP_ERR_NO_MEM if out of memory
  • ESP_ERR_INVALID_SIZE if size is not a multiple of 32K
Parameters
  • size: Size of the to-be-allocated block, in bytes. Note that this needs to be a multiple of the external RAM mmu block size (32K).
  • handle_out: Handle to be returned

esp_err_t esp_himem_alloc_map_range(size_t size, esp_himem_rangehandle_t *handle_out)

Allocate a memory region to map blocks into.

This allocates a contiguous CPU memory region that can be used to map blocks of physical memory into.

Return
- ESP_OK if succesful
  • ESP_ERR_NO_MEM if out of memory or address space
  • ESP_ERR_INVALID_SIZE if size is not a multiple of 32K
Parameters
  • size: Size of the range to be allocated. Note this needs to be a multiple of the external RAM mmu block size (32K).
  • handle_out: Handle to be returned

esp_err_t esp_himem_map(esp_himem_handle_t handle, esp_himem_rangehandle_t range, size_t ram_offset, size_t range_offset, size_t len, int flags, void **out_ptr)

Map a block of high memory into the CPUs address space.

This effectively makes the block available for read/write operations.

Note
The region to be mapped needs to have offsets and sizes that are aligned to the SPI RAM MMU block size (32K)
Return
- ESP_OK if the memory could be mapped
  • ESP_ERR_INVALID_ARG if offset, range or len aren’t MMU-block-aligned (32K)
  • ESP_ERR_INVALID_SIZE if the offsets/lengths don’t fit in the allocated memory or range
  • ESP_ERR_INVALID_STATE if a block in the selected ram offset/length is already mapped, or if a block in the selected range offset/length already has a mapping.
Parameters
  • handle: Handle to the block of memory, as given by esp_himem_alloc
  • range: Range handle to map the memory in
  • ram_offset: Offset into the block of physical memory of the block to map
  • range_offset: Offset into the address range where the block will be mapped
  • len: Length of region to map
  • flags: One of ESP_HIMEM_MAPFLAG_*
  • out_ptr: Pointer to variable to store resulting memory pointer in

esp_err_t esp_himem_free(esp_himem_handle_t handle)

Free a block of physical memory.

This clears out the associated handle making the memory available for re-allocation again. This will only succeed if none of the memory blocks currently have a mapping.

Return
- ESP_OK if the memory is succesfully freed
  • ESP_ERR_INVALID_ARG if the handle still is (partially) mapped
Parameters
  • handle: Handle to the block of memory, as given by esp_himem_alloc

esp_err_t esp_himem_free_map_range(esp_himem_rangehandle_t handle)

Free a mapping range.

This clears out the associated handle making the range available for re-allocation again. This will only succeed if none of the range blocks currently are used for a mapping.

Return
- ESP_OK if the memory is succesfully freed
  • ESP_ERR_INVALID_ARG if the handle still is (partially) mapped to
Parameters
  • handle: Handle to the range block, as given by esp_himem_alloc_map_range

esp_err_t esp_himem_unmap(esp_himem_rangehandle_t range, void *ptr, size_t len)

Unmap a region.

Return
- ESP_OK if the memory is succesfully unmapped,
  • ESP_ERR_INVALID_ARG if ptr or len are invalid.
Parameters
  • range: Range handle
  • ptr: Pointer returned by esp_himem_map
  • len: Length of the block to be unmapped. Must be aligned to the SPI RAM MMU blocksize (32K)

size_t esp_himem_get_phys_size()

Get total amount of memory under control of himem API.

Return
Amount of memory, in bytes

size_t esp_himem_get_free_size()

Get free amount of memory under control of himem API.

Return
Amount of free memory, in bytes

size_t esp_himem_reserved_area_size()

Get amount of SPI memory address space needed for bankswitching.

Note
This is also weakly defined in esp32/spiram.c and returns 0 there, so if no other function in this file is used, no memory is reserved.
Return
Amount of reserved area, in bytes

Macros

ESP_HIMEM_BLKSZ
ESP_HIMEM_MAPFLAG_RO

Indicates that a mapping will only be read from. Note that this is unused for now.

Type Definitions

typedef struct esp_himem_ramdata_t *esp_himem_handle_t
typedef struct esp_himem_rangedata_t *esp_himem_rangehandle_t