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