1 /* 2 * SPDX-FileCopyrightText: 2018-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #pragma once 7 8 #include <stddef.h> 9 #include "esp_err.h" 10 11 #ifdef __cplusplus 12 extern "C" { 13 #endif 14 15 //Opaque pointers as handles for ram/range data 16 typedef struct esp_himem_ramdata_t *esp_himem_handle_t; 17 typedef struct esp_himem_rangedata_t *esp_himem_rangehandle_t; 18 19 //ESP32 MMU block size 20 #define ESP_HIMEM_BLKSZ (0x8000) 21 22 #define ESP_HIMEM_MAPFLAG_RO 1 /*!< Indicates that a mapping will only be read from. Note that this is unused for now. */ 23 24 /** 25 * @brief Allocate a block in high memory 26 * 27 * @param size Size of the to-be-allocated block, in bytes. Note that this needs to be 28 * a multiple of the external RAM mmu block size (32K). 29 * @param[out] handle_out Handle to be returned 30 * @returns - ESP_OK if succesful 31 * - ESP_ERR_NO_MEM if out of memory 32 * - ESP_ERR_INVALID_SIZE if size is not a multiple of 32K 33 */ 34 esp_err_t esp_himem_alloc(size_t size, esp_himem_handle_t *handle_out); 35 36 37 /** 38 * @brief Allocate a memory region to map blocks into 39 * 40 * This allocates a contiguous CPU memory region that can be used to map blocks 41 * of physical memory into. 42 * 43 * @param size Size of the range to be allocated. Note this needs to be a multiple of 44 * the external RAM mmu block size (32K). 45 * @param[out] handle_out Handle to be returned 46 * @returns - ESP_OK if succesful 47 * - ESP_ERR_NO_MEM if out of memory or address space 48 * - ESP_ERR_INVALID_SIZE if size is not a multiple of 32K 49 */ 50 esp_err_t esp_himem_alloc_map_range(size_t size, esp_himem_rangehandle_t *handle_out); 51 52 /** 53 * @brief Map a block of high memory into the CPUs address space 54 * 55 * This effectively makes the block available for read/write operations. 56 * 57 * @note The region to be mapped needs to have offsets and sizes that are aligned to the 58 * SPI RAM MMU block size (32K) 59 * 60 * @param handle Handle to the block of memory, as given by esp_himem_alloc 61 * @param range Range handle to map the memory in 62 * @param ram_offset Offset into the block of physical memory of the block to map 63 * @param range_offset Offset into the address range where the block will be mapped 64 * @param len Length of region to map 65 * @param flags One of ESP_HIMEM_MAPFLAG_* 66 * @param[out] out_ptr Pointer to variable to store resulting memory pointer in 67 * @returns - ESP_OK if the memory could be mapped 68 * - ESP_ERR_INVALID_ARG if offset, range or len aren't MMU-block-aligned (32K) 69 * - ESP_ERR_INVALID_SIZE if the offsets/lengths don't fit in the allocated memory or range 70 * - ESP_ERR_INVALID_STATE if a block in the selected ram offset/length is already mapped, or 71 * if a block in the selected range offset/length already has a mapping. 72 */ 73 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); 74 75 76 /** 77 * @brief Free a block of physical memory 78 * 79 * This clears out the associated handle making the memory available for re-allocation again. 80 * This will only succeed if none of the memory blocks currently have a mapping. 81 * 82 * @param handle Handle to the block of memory, as given by esp_himem_alloc 83 * @returns - ESP_OK if the memory is succesfully freed 84 * - ESP_ERR_INVALID_ARG if the handle still is (partially) mapped 85 */ 86 esp_err_t esp_himem_free(esp_himem_handle_t handle); 87 88 89 90 /** 91 * @brief Free a mapping range 92 * 93 * This clears out the associated handle making the range available for re-allocation again. 94 * This will only succeed if none of the range blocks currently are used for a mapping. 95 * 96 * @param handle Handle to the range block, as given by esp_himem_alloc_map_range 97 * @returns - ESP_OK if the memory is succesfully freed 98 * - ESP_ERR_INVALID_ARG if the handle still is (partially) mapped to 99 */ 100 esp_err_t esp_himem_free_map_range(esp_himem_rangehandle_t handle); 101 102 103 /** 104 * @brief Unmap a region 105 * 106 * @param range Range handle 107 * @param ptr Pointer returned by esp_himem_map 108 * @param len Length of the block to be unmapped. Must be aligned to the SPI RAM MMU blocksize (32K) 109 * @returns - ESP_OK if the memory is succesfully unmapped, 110 * - ESP_ERR_INVALID_ARG if ptr or len are invalid. 111 */ 112 esp_err_t esp_himem_unmap(esp_himem_rangehandle_t range, void *ptr, size_t len); 113 114 115 /** 116 * @brief Get total amount of memory under control of himem API 117 * 118 * @returns Amount of memory, in bytes 119 */ 120 size_t esp_himem_get_phys_size(void); 121 122 /** 123 * @brief Get free amount of memory under control of himem API 124 * 125 * @returns Amount of free memory, in bytes 126 */ 127 size_t esp_himem_get_free_size(void); 128 129 130 /** 131 * @brief Get amount of SPI memory address space needed for bankswitching 132 * 133 * @note This is also weakly defined in esp32/spiram.c and returns 0 there, so 134 * if no other function in this file is used, no memory is reserved. 135 * 136 * @returns Amount of reserved area, in bytes 137 */ 138 size_t esp_himem_reserved_area_size(void); 139 140 141 #ifdef __cplusplus 142 } 143 #endif 144
