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