Line data Source code
1 0 : /* 2 : * Copyright (c) 2020 Intel Corporation 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : #ifndef ZEPHYR_INCLUDE_KERNEL_MM_H 8 : #define ZEPHYR_INCLUDE_KERNEL_MM_H 9 : 10 : #include <zephyr/sys/util.h> 11 : #include <zephyr/toolchain.h> 12 : #if defined(CONFIG_ARM_MMU) && defined(CONFIG_ARM64) 13 : #include <zephyr/arch/arm64/arm_mem.h> 14 : #endif /* CONFIG_ARM_MMU && CONFIG_ARM64 */ 15 : 16 : #include <zephyr/kernel/internal/mm.h> 17 : 18 : /** 19 : * @brief Kernel Memory Management 20 : * @defgroup kernel_memory_management Kernel Memory Management 21 : * @ingroup kernel_apis 22 : * @{ 23 : */ 24 : 25 : /** 26 : * @name Caching mode definitions. 27 : * 28 : * These are mutually exclusive. 29 : * 30 : * @{ 31 : */ 32 : 33 : /** No caching. Most drivers want this. */ 34 1 : #define K_MEM_CACHE_NONE 2 35 : 36 : /** Write-through caching. Used by certain drivers. */ 37 1 : #define K_MEM_CACHE_WT 1 38 : 39 : /** Full write-back caching. Any RAM mapped wants this. */ 40 1 : #define K_MEM_CACHE_WB 0 41 : 42 : /* 43 : * ARM64 Specific flags are defined in arch/arm64/arm_mem.h, 44 : * pay attention to be not conflicted when updating these flags. 45 : */ 46 : 47 : /** Reserved bits for cache modes in k_map() flags argument */ 48 1 : #define K_MEM_CACHE_MASK (BIT(3) - 1) 49 : 50 : /** @} */ 51 : 52 : /** 53 : * @name Region permission attributes. 54 : * 55 : * Default is read-only, no user, no exec 56 : * 57 : * @{ 58 : */ 59 : 60 : /** Region will have read/write access (and not read-only) */ 61 1 : #define K_MEM_PERM_RW BIT(3) 62 : 63 : /** Region will be executable (normally forbidden) */ 64 1 : #define K_MEM_PERM_EXEC BIT(4) 65 : 66 : /** Region will be accessible to user mode (normally supervisor-only) */ 67 1 : #define K_MEM_PERM_USER BIT(5) 68 : 69 : /** @} */ 70 : 71 : /** 72 : * @name Region mapping behaviour attributes 73 : * 74 : * @{ 75 : */ 76 : 77 : /** Region will be mapped to 1:1 virtual and physical address */ 78 1 : #define K_MEM_DIRECT_MAP BIT(6) 79 : 80 : /** @} */ 81 : 82 : #ifndef _ASMLANGUAGE 83 : #include <stdint.h> 84 : #include <stddef.h> 85 : #include <inttypes.h> 86 : 87 : #ifdef __cplusplus 88 : extern "C" { 89 : #endif 90 : 91 : /** 92 : * @name k_mem_map() control flags 93 : * 94 : * @{ 95 : */ 96 : 97 : /** 98 : * @brief The mapped region is not guaranteed to be zeroed. 99 : * 100 : * This may improve performance. The associated page frames may contain 101 : * indeterminate data, zeroes, or even sensitive information. 102 : * 103 : * This may not be used with K_MEM_PERM_USER as there are no circumstances 104 : * where this is safe. 105 : */ 106 1 : #define K_MEM_MAP_UNINIT BIT(16) 107 : 108 : /** 109 : * Region will be pinned in memory and never paged 110 : * 111 : * Such memory is guaranteed to never produce a page fault due to page-outs 112 : * or copy-on-write once the mapping call has returned. Physical page frames 113 : * will be pre-fetched as necessary and pinned. 114 : */ 115 1 : #define K_MEM_MAP_LOCK BIT(17) 116 : 117 : /** 118 : * Region will be unpaged i.e. not mapped into memory 119 : * 120 : * This is meant to be used by kernel code and not by application code. 121 : * 122 : * Corresponding memory address range will be set so no actual memory will 123 : * be allocated initially. Allocation will happen through demand paging when 124 : * addresses in that range are accessed. This is incompatible with 125 : * K_MEM_MAP_LOCK. 126 : * 127 : * When this flag is specified, the phys argument to arch_mem_map() 128 : * is interpreted as a backing store location value not a physical address. 129 : * This is very similar to arch_mem_page_out() in that regard. 130 : * Two special location values are defined: ARCH_UNPAGED_ANON_ZERO and 131 : * ARCH_UNPAGED_ANON_UNINIT. Those are to be used with anonymous memory 132 : * mappings for zeroed and uninitialized pages respectively. 133 : */ 134 1 : #define K_MEM_MAP_UNPAGED BIT(18) 135 : 136 : /** @} */ 137 : 138 : /** 139 : * Return the amount of free memory available 140 : * 141 : * The returned value will reflect how many free RAM page frames are available. 142 : * If demand paging is enabled, it may still be possible to allocate more. 143 : * 144 : * The information reported by this function may go stale immediately if 145 : * concurrent memory mappings or page-ins take place. 146 : * 147 : * @return Free physical RAM, in bytes 148 : */ 149 1 : size_t k_mem_free_get(void); 150 : 151 : /** 152 : * Map anonymous memory into Zephyr's address space 153 : * 154 : * This function effectively increases the data space available to Zephyr. 155 : * The kernel will choose a base virtual address and return it to the caller. 156 : * The memory will have access permissions for all contexts set per the 157 : * provided flags argument. 158 : * 159 : * If user thread access control needs to be managed in any way, do not enable 160 : * K_MEM_PERM_USER flags here; instead manage the region's permissions 161 : * with memory domain APIs after the mapping has been established. Setting 162 : * K_MEM_PERM_USER here will allow all user threads to access this memory 163 : * which is usually undesirable. 164 : * 165 : * Unless K_MEM_MAP_UNINIT is used, the returned memory will be zeroed. 166 : * 167 : * The mapped region is not guaranteed to be physically contiguous in memory. 168 : * Physically contiguous buffers should be allocated statically and pinned 169 : * at build time. 170 : * 171 : * Pages mapped in this way have write-back cache settings. 172 : * 173 : * The returned virtual memory pointer will be page-aligned. The size 174 : * parameter, and any base address for re-mapping purposes must be page- 175 : * aligned. 176 : * 177 : * Note that the allocation includes two guard pages immediately before 178 : * and after the requested region. The total size of the allocation will be 179 : * the requested size plus the size of these two guard pages. 180 : * 181 : * Many K_MEM_MAP_* flags have been implemented to alter the behavior of this 182 : * function, with details in the documentation for these flags. 183 : * 184 : * @param size Size of the memory mapping. This must be page-aligned. 185 : * @param flags K_MEM_PERM_*, K_MEM_MAP_* control flags. 186 : * @return The mapped memory location, or NULL if insufficient virtual address 187 : * space, insufficient physical memory to establish the mapping, 188 : * or insufficient memory for paging structures. 189 : */ 190 1 : static inline void *k_mem_map(size_t size, uint32_t flags) 191 : { 192 : return k_mem_map_phys_guard((uintptr_t)NULL, size, flags, true); 193 : } 194 : 195 : #ifdef CONFIG_DEMAND_MAPPING 196 : /** 197 : * Create an unpaged mapping 198 : * 199 : * This maps backing-store "location" tokens into Zephyr's address space. 200 : * Corresponding memory address range will be set so no actual memory will 201 : * be allocated initially. Allocation will happen through demand paging when 202 : * addresses in the mapped range are accessed. 203 : * 204 : * The kernel will choose a base virtual address and return it to the caller. 205 : * The memory access permissions for all contexts will be set per the 206 : * provided flags argument. 207 : * 208 : * If user thread access control needs to be managed in any way, do not enable 209 : * K_MEM_PERM_USER flags here; instead manage the region's permissions 210 : * with memory domain APIs after the mapping has been established. Setting 211 : * K_MEM_PERM_USER here will allow all user threads to access this memory 212 : * which is usually undesirable. 213 : * 214 : * This is incompatible with K_MEM_MAP_LOCK. 215 : * 216 : * The provided backing-store "location" token must be linearly incrementable 217 : * by a page size across the entire mapping. 218 : * 219 : * Allocated pages will have write-back cache settings. 220 : * 221 : * The returned virtual memory pointer will be page-aligned. The size 222 : * parameter, and any base address for re-mapping purposes must be page- 223 : * aligned. 224 : * 225 : * Note that the allocation includes two guard pages immediately before 226 : * and after the requested region. The total size of the allocation will be 227 : * the requested size plus the size of these two guard pages. 228 : * 229 : * @param location Backing store initial location token 230 : * @param size Size of the memory mapping. This must be page-aligned. 231 : * @param flags K_MEM_PERM_*, K_MEM_MAP_* control flags. 232 : * @return The mapping location, or NULL if insufficient virtual address 233 : * space to establish the mapping, or insufficient memory for paging 234 : * structures. 235 : */ 236 : static inline void *k_mem_map_unpaged(uintptr_t location, size_t size, uint32_t flags) 237 : { 238 : flags |= K_MEM_MAP_UNPAGED; 239 : return k_mem_map_phys_guard(location, size, flags, false); 240 : } 241 : #endif 242 : 243 : /** 244 : * Un-map mapped memory 245 : * 246 : * This removes a memory mapping for the provided page-aligned region. 247 : * Associated page frames will be free and the kernel may re-use the associated 248 : * virtual address region. Any paged out data pages may be discarded. 249 : * 250 : * Calling this function on a region which was not mapped to begin with is 251 : * undefined behavior. 252 : * 253 : * @param addr Page-aligned memory region base virtual address 254 : * @param size Page-aligned memory region size 255 : */ 256 1 : static inline void k_mem_unmap(void *addr, size_t size) 257 : { 258 : k_mem_unmap_phys_guard(addr, size, true); 259 : } 260 : 261 : /** 262 : * Modify memory mapping attribute flags 263 : * 264 : * This updates caching, access and control flags for the provided 265 : * page-aligned memory region. 266 : * 267 : * Calling this function on a region which was not mapped to begin with is 268 : * undefined behavior. However system memory implicitly mapped at boot time 269 : * is supported. 270 : * 271 : * @param addr Page-aligned memory region base virtual address 272 : * @param size Page-aligned memory region size 273 : * @param flags K_MEM_PERM_*, K_MEM_MAP_* control flags. 274 : * @return 0 for success, negative error code otherwise. 275 : */ 276 1 : int k_mem_update_flags(void *addr, size_t size, uint32_t flags); 277 : 278 : /** 279 : * Given an arbitrary region, provide a aligned region that covers it 280 : * 281 : * The returned region will have both its base address and size aligned 282 : * to the provided alignment value. 283 : * 284 : * @param[out] aligned_addr Aligned address 285 : * @param[out] aligned_size Aligned region size 286 : * @param[in] addr Region base address 287 : * @param[in] size Region size 288 : * @param[in] align What to align the address and size to 289 : * @retval offset between aligned_addr and addr 290 : */ 291 1 : size_t k_mem_region_align(uintptr_t *aligned_addr, size_t *aligned_size, 292 : uintptr_t addr, size_t size, size_t align); 293 : 294 : #ifdef __cplusplus 295 : } 296 : #endif 297 : 298 : /** @} */ 299 : 300 : #endif /* !_ASMLANGUAGE */ 301 : #endif /* ZEPHYR_INCLUDE_KERNEL_MM_H */
