1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2014 Intel Corporation 3 */ 4 5 #ifndef _RTE_MEMZONE_H_ 6 #define _RTE_MEMZONE_H_ 7 8 /** 9 * @file 10 * RTE Memzone 11 * 12 * The goal of the memzone allocator is to reserve contiguous 13 * portions of physical memory. These zones are identified by a name. 14 * 15 * The memzone descriptors are shared by all partitions and are 16 * located in a known place of physical memory. This zone is accessed 17 * using rte_eal_get_configuration(). The lookup (by name) of a 18 * memory zone can be done in any partition and returns the same 19 * physical address. 20 * 21 * A reserved memory zone cannot be unreserved. The reservation shall 22 * be done at initialization time only. 23 */ 24 25 #include <stdio.h> 26 #include <rte_memory.h> 27 #include <rte_common.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 #define RTE_MEMZONE_2MB 0x00000001 /**< Use 2MB pages. */ 34 #define RTE_MEMZONE_1GB 0x00000002 /**< Use 1GB pages. */ 35 #define RTE_MEMZONE_16MB 0x00000100 /**< Use 16MB pages. */ 36 #define RTE_MEMZONE_16GB 0x00000200 /**< Use 16GB pages. */ 37 #define RTE_MEMZONE_256KB 0x00010000 /**< Use 256KB pages. */ 38 #define RTE_MEMZONE_256MB 0x00020000 /**< Use 256MB pages. */ 39 #define RTE_MEMZONE_512MB 0x00040000 /**< Use 512MB pages. */ 40 #define RTE_MEMZONE_4GB 0x00080000 /**< Use 4GB pages. */ 41 #define RTE_MEMZONE_SIZE_HINT_ONLY 0x00000004 /**< Use available page size */ 42 #define RTE_MEMZONE_IOVA_CONTIG 0x00100000 /**< Ask for IOVA-contiguous memzone. */ 43 44 /** 45 * A structure describing a memzone, which is a contiguous portion of 46 * physical memory identified by a name. 47 */ 48 struct __rte_packed_begin rte_memzone { 49 50 #define RTE_MEMZONE_NAMESIZE 32 /**< Maximum length of memory zone name.*/ 51 char name[RTE_MEMZONE_NAMESIZE]; /**< Name of the memory zone. */ 52 53 rte_iova_t iova; /**< Start IO address. */ 54 union { 55 void *addr; /**< Start virtual address. */ 56 uint64_t addr_64; /**< Makes sure addr is always 64-bits */ 57 }; 58 size_t len; /**< Length of the memzone. */ 59 60 uint64_t hugepage_sz; /**< The page size of underlying memory */ 61 62 int32_t socket_id; /**< NUMA socket ID. */ 63 64 uint32_t flags; /**< Characteristics of this memzone. */ 65 } __rte_packed_end; 66 67 /** 68 * Set the maximum number of memzones. 69 * 70 * This function can only be called prior to rte_eal_init(). 71 * 72 * @param max 73 * Maximum number of memzones. 74 * @return 75 * 0 on success, -1 otherwise. 76 */ 77 int rte_memzone_max_set(size_t max); 78 79 /** 80 * Get the maximum number of memzones. 81 * 82 * @note: The maximum value will not change after calling rte_eal_init(). 83 * 84 * @return 85 * Maximum number of memzones. 86 */ 87 size_t rte_memzone_max_get(void); 88 89 /** 90 * Reserve a portion of physical memory. 91 * 92 * This function reserves some memory and returns a pointer to a 93 * correctly filled memzone descriptor. If the allocation cannot be 94 * done, return NULL. 95 * 96 * @note Reserving memzones with len set to 0 will only attempt to allocate 97 * memzones from memory that is already available. It will not trigger any 98 * new allocations. 99 * 100 * @note: When reserving memzones with len set to 0, it is preferable to also 101 * set a valid socket_id. Setting socket_id to SOCKET_ID_ANY is supported, but 102 * will likely not yield expected results. Specifically, the resulting memzone 103 * may not necessarily be the biggest memzone available, but rather biggest 104 * memzone available on socket id corresponding to an lcore from which 105 * reservation was called. 106 * 107 * @param name 108 * The name of the memzone. If it already exists, the function will 109 * fail and return NULL. 110 * @param len 111 * The size of the memory to be reserved. If it 112 * is 0, the biggest contiguous zone will be reserved. 113 * @param socket_id 114 * The socket identifier in the case of 115 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA 116 * constraint for the reserved zone. 117 * @param flags 118 * The flags parameter is used to request memzones to be 119 * taken from specifically sized hugepages. 120 * - RTE_MEMZONE_2MB - Reserved from 2MB pages 121 * - RTE_MEMZONE_1GB - Reserved from 1GB pages 122 * - RTE_MEMZONE_16MB - Reserved from 16MB pages 123 * - RTE_MEMZONE_16GB - Reserved from 16GB pages 124 * - RTE_MEMZONE_256KB - Reserved from 256KB pages 125 * - RTE_MEMZONE_256MB - Reserved from 256MB pages 126 * - RTE_MEMZONE_512MB - Reserved from 512MB pages 127 * - RTE_MEMZONE_4GB - Reserved from 4GB pages 128 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if 129 * the requested page size is unavailable. 130 * If this flag is not set, the function 131 * will return error on an unavailable size 132 * request. 133 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous. 134 * This option should be used when allocating 135 * memory intended for hardware rings etc. 136 * @return 137 * A pointer to a correctly-filled read-only memzone descriptor, or NULL 138 * on error. 139 * On error case, rte_errno will be set appropriately: 140 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure 141 * - ENOSPC - the maximum number of memzones has already been allocated 142 * - EEXIST - a memzone with the same name already exists 143 * - ENOMEM - no appropriate memory area found in which to create memzone 144 * - EINVAL - invalid parameters 145 */ 146 const struct rte_memzone *rte_memzone_reserve(const char *name, 147 size_t len, int socket_id, 148 unsigned flags); 149 150 /** 151 * Reserve a portion of physical memory with alignment on a specified 152 * boundary. 153 * 154 * This function reserves some memory with alignment on a specified 155 * boundary, and returns a pointer to a correctly filled memzone 156 * descriptor. If the allocation cannot be done or if the alignment 157 * is not a power of 2, returns NULL. 158 * 159 * @note Reserving memzones with len set to 0 will only attempt to allocate 160 * memzones from memory that is already available. It will not trigger any 161 * new allocations. 162 * 163 * @note: When reserving memzones with len set to 0, it is preferable to also 164 * set a valid socket_id. Setting socket_id to SOCKET_ID_ANY is supported, but 165 * will likely not yield expected results. Specifically, the resulting memzone 166 * may not necessarily be the biggest memzone available, but rather biggest 167 * memzone available on socket id corresponding to an lcore from which 168 * reservation was called. 169 * 170 * @param name 171 * The name of the memzone. If it already exists, the function will 172 * fail and return NULL. 173 * @param len 174 * The size of the memory to be reserved. If it 175 * is 0, the biggest contiguous zone will be reserved. 176 * @param socket_id 177 * The socket identifier in the case of 178 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA 179 * constraint for the reserved zone. 180 * @param flags 181 * The flags parameter is used to request memzones to be 182 * taken from specifically sized hugepages. 183 * - RTE_MEMZONE_2MB - Reserved from 2MB pages 184 * - RTE_MEMZONE_1GB - Reserved from 1GB pages 185 * - RTE_MEMZONE_16MB - Reserved from 16MB pages 186 * - RTE_MEMZONE_16GB - Reserved from 16GB pages 187 * - RTE_MEMZONE_256KB - Reserved from 256KB pages 188 * - RTE_MEMZONE_256MB - Reserved from 256MB pages 189 * - RTE_MEMZONE_512MB - Reserved from 512MB pages 190 * - RTE_MEMZONE_4GB - Reserved from 4GB pages 191 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if 192 * the requested page size is unavailable. 193 * If this flag is not set, the function 194 * will return error on an unavailable size 195 * request. 196 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous. 197 * This option should be used when allocating 198 * memory intended for hardware rings etc. 199 * @param align 200 * Alignment for resulting memzone. Must be a power of 2. 201 * @return 202 * A pointer to a correctly-filled read-only memzone descriptor, or NULL 203 * on error. 204 * On error case, rte_errno will be set appropriately: 205 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure 206 * - ENOSPC - the maximum number of memzones has already been allocated 207 * - EEXIST - a memzone with the same name already exists 208 * - ENOMEM - no appropriate memory area found in which to create memzone 209 * - EINVAL - invalid parameters 210 */ 211 const struct rte_memzone *rte_memzone_reserve_aligned(const char *name, 212 size_t len, int socket_id, 213 unsigned flags, unsigned align); 214 215 /** 216 * Reserve a portion of physical memory with specified alignment and 217 * boundary. 218 * 219 * This function reserves some memory with specified alignment and 220 * boundary, and returns a pointer to a correctly filled memzone 221 * descriptor. If the allocation cannot be done or if the alignment 222 * or boundary are not a power of 2, returns NULL. 223 * Memory buffer is reserved in a way, that it wouldn't cross specified 224 * boundary. That implies that requested length should be less or equal 225 * then boundary. 226 * 227 * @note Reserving memzones with len set to 0 will only attempt to allocate 228 * memzones from memory that is already available. It will not trigger any 229 * new allocations. 230 * 231 * @note: When reserving memzones with len set to 0, it is preferable to also 232 * set a valid socket_id. Setting socket_id to SOCKET_ID_ANY is supported, but 233 * will likely not yield expected results. Specifically, the resulting memzone 234 * may not necessarily be the biggest memzone available, but rather biggest 235 * memzone available on socket id corresponding to an lcore from which 236 * reservation was called. 237 * 238 * @param name 239 * The name of the memzone. If it already exists, the function will 240 * fail and return NULL. 241 * @param len 242 * The size of the memory to be reserved. If it 243 * is 0, the biggest contiguous zone will be reserved. 244 * @param socket_id 245 * The socket identifier in the case of 246 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA 247 * constraint for the reserved zone. 248 * @param flags 249 * The flags parameter is used to request memzones to be 250 * taken from specifically sized hugepages. 251 * - RTE_MEMZONE_2MB - Reserved from 2MB pages 252 * - RTE_MEMZONE_1GB - Reserved from 1GB pages 253 * - RTE_MEMZONE_16MB - Reserved from 16MB pages 254 * - RTE_MEMZONE_16GB - Reserved from 16GB pages 255 * - RTE_MEMZONE_256KB - Reserved from 256KB pages 256 * - RTE_MEMZONE_256MB - Reserved from 256MB pages 257 * - RTE_MEMZONE_512MB - Reserved from 512MB pages 258 * - RTE_MEMZONE_4GB - Reserved from 4GB pages 259 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if 260 * the requested page size is unavailable. 261 * If this flag is not set, the function 262 * will return error on an unavailable size 263 * request. 264 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous. 265 * This option should be used when allocating 266 * memory intended for hardware rings etc. 267 * @param align 268 * Alignment for resulting memzone. Must be a power of 2. 269 * @param bound 270 * Boundary for resulting memzone. Must be a power of 2 or zero. 271 * Zero value implies no boundary condition. 272 * @return 273 * A pointer to a correctly-filled read-only memzone descriptor, or NULL 274 * on error. 275 * On error case, rte_errno will be set appropriately: 276 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure 277 * - ENOSPC - the maximum number of memzones has already been allocated 278 * - EEXIST - a memzone with the same name already exists 279 * - ENOMEM - no appropriate memory area found in which to create memzone 280 * - EINVAL - invalid parameters 281 */ 282 const struct rte_memzone *rte_memzone_reserve_bounded(const char *name, 283 size_t len, int socket_id, 284 unsigned flags, unsigned align, unsigned bound); 285 286 /** 287 * Free a memzone. 288 * 289 * @param mz 290 * A pointer to the memzone 291 * @return 292 * -EINVAL - invalid parameter. 293 * 0 - success 294 */ 295 int rte_memzone_free(const struct rte_memzone *mz); 296 297 /** 298 * Lookup for a memzone. 299 * 300 * Get a pointer to a descriptor of an already reserved memory 301 * zone identified by the name given as an argument. 302 * 303 * @param name 304 * The name of the memzone. 305 * @return 306 * A pointer to a read-only memzone descriptor. 307 */ 308 const struct rte_memzone *rte_memzone_lookup(const char *name); 309 310 /** 311 * Dump all reserved memzones to a file. 312 * 313 * @param f 314 * A pointer to a file for output 315 */ 316 void rte_memzone_dump(FILE *f); 317 318 /** 319 * Walk list of all memzones 320 * 321 * @param func 322 * Iterator function 323 * @param arg 324 * Argument passed to iterator 325 */ 326 void rte_memzone_walk(void (*func)(const struct rte_memzone *, void *arg), 327 void *arg); 328 329 #ifdef __cplusplus 330 } 331 #endif 332 333 #endif /* _RTE_MEMZONE_H_ */ 334