1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2019 Intel Corporation 3 */ 4 5 #ifndef _RTE_MALLOC_H_ 6 #define _RTE_MALLOC_H_ 7 8 /** 9 * @file 10 * RTE Malloc. This library provides methods for dynamically allocating memory 11 * from hugepages. 12 */ 13 14 #include <stdio.h> 15 #include <stddef.h> 16 #include <rte_memory.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** 23 * Structure to hold heap statistics obtained from rte_malloc_get_socket_stats function. 24 */ 25 struct rte_malloc_socket_stats { 26 size_t heap_totalsz_bytes; /**< Total bytes on heap */ 27 size_t heap_freesz_bytes; /**< Total free bytes on heap */ 28 size_t greatest_free_size; /**< Size in bytes of largest free block */ 29 unsigned free_count; /**< Number of free elements on heap */ 30 unsigned alloc_count; /**< Number of allocated elements on heap */ 31 size_t heap_allocsz_bytes; /**< Total allocated bytes on heap */ 32 }; 33 34 /** 35 * Functions that expect return value to be freed with rte_free() 36 */ 37 #define __rte_dealloc_free __rte_dealloc(rte_free, 1) 38 39 /** 40 * Frees the memory space pointed to by the provided pointer. 41 * 42 * This pointer must have been returned by a previous call to 43 * rte_malloc(), rte_zmalloc(), rte_calloc() or rte_realloc(). The behaviour of 44 * rte_free() is undefined if the pointer does not match this requirement. 45 * 46 * If the pointer is NULL, the function does nothing. 47 * 48 * @param ptr 49 * The pointer to memory to be freed. 50 */ 51 void 52 rte_free(void *ptr); 53 54 /** 55 * This function allocates memory from the huge-page area of memory. The memory 56 * is not cleared. In NUMA systems, the memory allocated resides on the same 57 * NUMA socket as the core that calls this function. 58 * 59 * @param type 60 * A string identifying the type of allocated objects (useful for tracing). 61 * Can be NULL. 62 * @param size 63 * Size (in bytes) to be allocated. 64 * @param align 65 * If 0, the return is a pointer that is suitably aligned for any kind of 66 * variable (in the same manner as malloc()). 67 * Otherwise, the return is a pointer that is a multiple of *align*. In 68 * this case, it must be a power of two. (Minimum alignment is the 69 * cacheline size, i.e. 64-bytes) 70 * @return 71 * - NULL on error. Not enough memory, or invalid arguments (size is 0, 72 * align is not a power of two). 73 * - Otherwise, the pointer to the allocated object. 74 */ 75 void * 76 rte_malloc(const char *type, size_t size, unsigned align) 77 __rte_alloc_size(2) __rte_alloc_align(3) 78 __rte_malloc __rte_dealloc_free; 79 80 /** 81 * Allocate zeroed memory from the heap. 82 * 83 * Equivalent to rte_malloc() except that the memory zone is 84 * initialised with zeros. In NUMA systems, the memory allocated resides on the 85 * same NUMA socket as the core that calls this function. 86 * 87 * @param type 88 * A string identifying the type of allocated objects (useful for tracing). 89 * Can be NULL. 90 * @param size 91 * Size (in bytes) to be allocated. 92 * @param align 93 * If 0, the return is a pointer that is suitably aligned for any kind of 94 * variable (in the same manner as malloc()). 95 * Otherwise, the return is a pointer that is a multiple of *align*. In 96 * this case, it must obviously be a power of two. (Minimum alignment is the 97 * cacheline size, i.e. 64-bytes) 98 * @return 99 * - NULL on error. Not enough memory, or invalid arguments (size is 0, 100 * align is not a power of two). 101 * - Otherwise, the pointer to the allocated object. 102 */ 103 void * 104 rte_zmalloc(const char *type, size_t size, unsigned align) 105 __rte_alloc_size(2) __rte_alloc_align(3) 106 __rte_malloc __rte_dealloc_free; 107 108 /** 109 * Replacement function for calloc(), using huge-page memory. Memory area is 110 * initialised with zeros. In NUMA systems, the memory allocated resides on the 111 * same NUMA socket as the core that calls this function. 112 * 113 * @param type 114 * A string identifying the type of allocated objects (useful for tracing). 115 * Can be NULL. 116 * @param num 117 * Number of elements to be allocated. 118 * @param size 119 * Size (in bytes) of a single element. 120 * @param align 121 * If 0, the return is a pointer that is suitably aligned for any kind of 122 * variable (in the same manner as malloc()). 123 * Otherwise, the return is a pointer that is a multiple of *align*. In 124 * this case, it must obviously be a power of two. (Minimum alignment is the 125 * cacheline size, i.e. 64-bytes) 126 * @return 127 * - NULL on error. Not enough memory, or invalid arguments (size is 0, 128 * align is not a power of two). 129 * - Otherwise, the pointer to the allocated object. 130 */ 131 void * 132 rte_calloc(const char *type, size_t num, size_t size, unsigned align) 133 __rte_alloc_size(2, 3) __rte_alloc_align(4) 134 __rte_malloc __rte_dealloc_free; 135 136 /** 137 * Replacement function for realloc(), using huge-page memory. Reserved area 138 * memory is resized, preserving contents. In NUMA systems, the new area 139 * may not reside on the same NUMA node as the old one. 140 * 141 * @param ptr 142 * Pointer to already allocated memory 143 * @param size 144 * Size (in bytes) of new area. If this is 0, memory is freed. 145 * @param align 146 * If 0, the return is a pointer that is suitably aligned for any kind of 147 * variable (in the same manner as malloc()). 148 * Otherwise, the return is a pointer that is a multiple of *align*. In 149 * this case, it must obviously be a power of two. (Minimum alignment is the 150 * cacheline size, i.e. 64-bytes) 151 * @return 152 * - NULL on error. Not enough memory, or invalid arguments (size is 0, 153 * align is not a power of two). 154 * - Otherwise, the pointer to the reallocated memory. 155 */ 156 void * 157 rte_realloc(void *ptr, size_t size, unsigned int align) 158 __rte_alloc_size(2) __rte_alloc_align(3) 159 __rte_malloc __rte_dealloc_free; 160 161 /** 162 * Replacement function for realloc(), using huge-page memory. Reserved area 163 * memory is resized, preserving contents. In NUMA systems, the new area 164 * resides on requested NUMA socket. 165 * 166 * @param ptr 167 * Pointer to already allocated memory 168 * @param size 169 * Size (in bytes) of new area. If this is 0, memory is freed. 170 * @param align 171 * If 0, the return is a pointer that is suitably aligned for any kind of 172 * variable (in the same manner as malloc()). 173 * Otherwise, the return is a pointer that is a multiple of *align*. In 174 * this case, it must obviously be a power of two. (Minimum alignment is the 175 * cacheline size, i.e. 64-bytes) 176 * @param socket 177 * NUMA socket to allocate memory on. 178 * @return 179 * - NULL on error. Not enough memory, or invalid arguments (size is 0, 180 * align is not a power of two). 181 * - Otherwise, the pointer to the reallocated memory. 182 */ 183 void * 184 rte_realloc_socket(void *ptr, size_t size, unsigned int align, int socket) 185 __rte_alloc_size(2) __rte_alloc_align(3) 186 __rte_malloc __rte_dealloc_free; 187 188 /** 189 * This function allocates memory from the huge-page area of memory. The memory 190 * is not cleared. 191 * 192 * @param type 193 * A string identifying the type of allocated objects (useful for tracing). 194 * Can be NULL. 195 * @param size 196 * Size (in bytes) to be allocated. 197 * @param align 198 * If 0, the return is a pointer that is suitably aligned for any kind of 199 * variable (in the same manner as malloc()). 200 * Otherwise, the return is a pointer that is a multiple of *align*. In 201 * this case, it must be a power of two. (Minimum alignment is the 202 * cacheline size, i.e. 64-bytes) 203 * @param socket 204 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function 205 * will behave the same as rte_malloc(). 206 * @return 207 * - NULL on error. Not enough memory, or invalid arguments (size is 0, 208 * align is not a power of two). 209 * - Otherwise, the pointer to the allocated object. 210 */ 211 void * 212 rte_malloc_socket(const char *type, size_t size, unsigned align, int socket) 213 __rte_alloc_size(2) __rte_alloc_align(3) 214 __rte_malloc __rte_dealloc_free; 215 216 /** 217 * Allocate zeroed memory from the heap. 218 * 219 * Equivalent to rte_malloc() except that the memory zone is 220 * initialised with zeros. 221 * 222 * @param type 223 * A string identifying the type of allocated objects (useful for tracing). 224 * Can be NULL. 225 * @param size 226 * Size (in bytes) to be allocated. 227 * @param align 228 * If 0, the return is a pointer that is suitably aligned for any kind of 229 * variable (in the same manner as malloc()). 230 * Otherwise, the return is a pointer that is a multiple of *align*. In 231 * this case, it must obviously be a power of two. (Minimum alignment is the 232 * cacheline size, i.e. 64-bytes) 233 * @param socket 234 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function 235 * will behave the same as rte_zmalloc(). 236 * @return 237 * - NULL on error. Not enough memory, or invalid arguments (size is 0, 238 * align is not a power of two). 239 * - Otherwise, the pointer to the allocated object. 240 */ 241 void * 242 rte_zmalloc_socket(const char *type, size_t size, unsigned align, int socket) 243 __rte_alloc_size(2) __rte_alloc_align(3) 244 __rte_malloc __rte_dealloc_free; 245 246 /** 247 * Replacement function for calloc(), using huge-page memory. Memory area is 248 * initialised with zeros. 249 * 250 * @param type 251 * A string identifying the type of allocated objects (useful for tracing). 252 * Can be NULL. 253 * @param num 254 * Number of elements to be allocated. 255 * @param size 256 * Size (in bytes) of a single element. 257 * @param align 258 * If 0, the return is a pointer that is suitably aligned for any kind of 259 * variable (in the same manner as malloc()). 260 * Otherwise, the return is a pointer that is a multiple of *align*. In 261 * this case, it must obviously be a power of two. (Minimum alignment is the 262 * cacheline size, i.e. 64-bytes) 263 * @param socket 264 * NUMA socket to allocate memory on. If SOCKET_ID_ANY is used, this function 265 * will behave the same as rte_calloc(). 266 * @return 267 * - NULL on error. Not enough memory, or invalid arguments (size is 0, 268 * align is not a power of two). 269 * - Otherwise, the pointer to the allocated object. 270 */ 271 void * 272 rte_calloc_socket(const char *type, size_t num, size_t size, unsigned align, int socket) 273 __rte_alloc_size(2, 3) __rte_alloc_align(4) 274 __rte_malloc __rte_dealloc_free; 275 276 /** 277 * If malloc debug is enabled, check a memory block for header 278 * and trailer markers to indicate that all is well with the block. 279 * If size is non-null, also return the size of the block. 280 * 281 * @param ptr 282 * pointer to the start of a data block, must have been returned 283 * by a previous call to rte_malloc(), rte_zmalloc(), rte_calloc() 284 * or rte_realloc() 285 * @param size 286 * if non-null, and memory block pointer is valid, returns the size 287 * of the memory block 288 * @return 289 * -1 on error, invalid pointer passed or header and trailer markers 290 * are missing or corrupted 291 * 0 on success 292 */ 293 int 294 rte_malloc_validate(const void *ptr, size_t *size); 295 296 /** 297 * Get heap statistics for the specified heap. 298 * 299 * @note This function is not thread-safe with respect to 300 * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions. 301 * 302 * @param socket 303 * An unsigned integer specifying the socket to get heap statistics for 304 * @param socket_stats 305 * A structure which provides memory to store statistics 306 * @return 307 * Null on error 308 * Pointer to structure storing statistics on success 309 */ 310 int 311 rte_malloc_get_socket_stats(int socket, 312 struct rte_malloc_socket_stats *socket_stats); 313 314 /** 315 * Add memory chunk to a heap with specified name. 316 * 317 * @note Multiple memory chunks can be added to the same heap 318 * 319 * @note Before accessing this memory in other processes, it needs to be 320 * attached in each of those processes by calling 321 * ``rte_malloc_heap_memory_attach`` in each other process. 322 * 323 * @note Memory must be previously allocated for DPDK to be able to use it as a 324 * malloc heap. Failing to do so will result in undefined behavior, up to and 325 * including segmentation faults. 326 * 327 * @note Calling this function will erase any contents already present at the 328 * supplied memory address. 329 * 330 * @param heap_name 331 * Name of the heap to add memory chunk to 332 * @param va_addr 333 * Start of virtual area to add to the heap. Must be aligned by ``page_sz``. 334 * @param len 335 * Length of virtual area to add to the heap. Must be aligned by ``page_sz``. 336 * @param iova_addrs 337 * Array of page IOVA addresses corresponding to each page in this memory 338 * area. Can be NULL, in which case page IOVA addresses will be set to 339 * RTE_BAD_IOVA. 340 * @param n_pages 341 * Number of elements in the iova_addrs array. Ignored if ``iova_addrs`` 342 * is NULL. 343 * @param page_sz 344 * Page size of the underlying memory 345 * 346 * @return 347 * - 0 on success 348 * - -1 in case of error, with rte_errno set to one of the following: 349 * EINVAL - one of the parameters was invalid 350 * EPERM - attempted to add memory to a reserved heap 351 * ENOSPC - no more space in internal config to store a new memory chunk 352 */ 353 int 354 rte_malloc_heap_memory_add(const char *heap_name, void *va_addr, size_t len, 355 rte_iova_t iova_addrs[], unsigned int n_pages, size_t page_sz); 356 357 /** 358 * Remove memory chunk from heap with specified name. 359 * 360 * @note Memory chunk being removed must be the same as one that was added; 361 * partially removing memory chunks is not supported 362 * 363 * @note Memory area must not contain any allocated elements to allow its 364 * removal from the heap 365 * 366 * @note All other processes must detach from the memory chunk prior to it being 367 * removed from the heap. 368 * 369 * @param heap_name 370 * Name of the heap to remove memory from 371 * @param va_addr 372 * Virtual address to remove from the heap 373 * @param len 374 * Length of virtual area to remove from the heap 375 * 376 * @return 377 * - 0 on success 378 * - -1 in case of error, with rte_errno set to one of the following: 379 * EINVAL - one of the parameters was invalid 380 * EPERM - attempted to remove memory from a reserved heap 381 * ENOENT - heap or memory chunk was not found 382 * EBUSY - memory chunk still contains data 383 */ 384 int 385 rte_malloc_heap_memory_remove(const char *heap_name, void *va_addr, size_t len); 386 387 /** 388 * Attach to an already existing chunk of external memory in another process. 389 * 390 * @note This function must be called before any attempt is made to use an 391 * already existing external memory chunk. This function does *not* need to 392 * be called if a call to ``rte_malloc_heap_memory_add`` was made in the 393 * current process. 394 * 395 * @param heap_name 396 * Heap name to which this chunk of memory belongs 397 * @param va_addr 398 * Start address of memory chunk to attach to 399 * @param len 400 * Length of memory chunk to attach to 401 * @return 402 * 0 on successful attach 403 * -1 on unsuccessful attach, with rte_errno set to indicate cause for error: 404 * EINVAL - one of the parameters was invalid 405 * EPERM - attempted to attach memory to a reserved heap 406 * ENOENT - heap or memory chunk was not found 407 */ 408 int 409 rte_malloc_heap_memory_attach(const char *heap_name, void *va_addr, size_t len); 410 411 /** 412 * Detach from a chunk of external memory in secondary process. 413 * 414 * @note This function must be called in before any attempt is made to remove 415 * external memory from the heap in another process. This function does *not* 416 * need to be called if a call to ``rte_malloc_heap_memory_remove`` will be 417 * called in current process. 418 * 419 * @param heap_name 420 * Heap name to which this chunk of memory belongs 421 * @param va_addr 422 * Start address of memory chunk to attach to 423 * @param len 424 * Length of memory chunk to attach to 425 * @return 426 * 0 on successful detach 427 * -1 on unsuccessful detach, with rte_errno set to indicate cause for error: 428 * EINVAL - one of the parameters was invalid 429 * EPERM - attempted to detach memory from a reserved heap 430 * ENOENT - heap or memory chunk was not found 431 */ 432 int 433 rte_malloc_heap_memory_detach(const char *heap_name, void *va_addr, size_t len); 434 435 /** 436 * Creates a new empty malloc heap with a specified name. 437 * 438 * @note Heaps created via this call will automatically get assigned a unique 439 * socket ID, which can be found using ``rte_malloc_heap_get_socket()`` 440 * 441 * @param heap_name 442 * Name of the heap to create. 443 * 444 * @return 445 * - 0 on successful creation 446 * - -1 in case of error, with rte_errno set to one of the following: 447 * EINVAL - ``heap_name`` was NULL, empty or too long 448 * EEXIST - heap by name of ``heap_name`` already exists 449 * ENOSPC - no more space in internal config to store a new heap 450 */ 451 int 452 rte_malloc_heap_create(const char *heap_name); 453 454 /** 455 * Destroys a previously created malloc heap with specified name. 456 * 457 * @note This function will return a failure result if not all memory allocated 458 * from the heap has been freed back to the heap 459 * 460 * @note This function will return a failure result if not all memory segments 461 * were removed from the heap prior to its destruction 462 * 463 * @param heap_name 464 * Name of the heap to create. 465 * 466 * @return 467 * - 0 on success 468 * - -1 in case of error, with rte_errno set to one of the following: 469 * EINVAL - ``heap_name`` was NULL, empty or too long 470 * ENOENT - heap by the name of ``heap_name`` was not found 471 * EPERM - attempting to destroy reserved heap 472 * EBUSY - heap still contains data 473 */ 474 int 475 rte_malloc_heap_destroy(const char *heap_name); 476 477 /** 478 * Find socket ID corresponding to a named heap. 479 * 480 * @param name 481 * Heap name to find socket ID for 482 * @return 483 * Socket ID in case of success (a non-negative number) 484 * -1 in case of error, with rte_errno set to one of the following: 485 * EINVAL - ``name`` was NULL 486 * ENOENT - heap identified by the name ``name`` was not found 487 */ 488 int 489 rte_malloc_heap_get_socket(const char *name); 490 491 /** 492 * Check if a given socket ID refers to externally allocated memory. 493 * 494 * @note Passing SOCKET_ID_ANY will return 0. 495 * 496 * @param socket_id 497 * Socket ID to check 498 * @return 499 * 1 if socket ID refers to externally allocated memory 500 * 0 if socket ID refers to internal DPDK memory 501 * -1 if socket ID is invalid 502 */ 503 int 504 rte_malloc_heap_socket_is_external(int socket_id); 505 506 /** 507 * Dump statistics. 508 * 509 * Dump for the specified type to a file. If the type argument is 510 * NULL, all memory types will be dumped. 511 * 512 * @note This function is not thread-safe with respect to 513 * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions. 514 * 515 * @param f 516 * A pointer to a file for output 517 * @param type 518 * Deprecated parameter unused. 519 */ 520 void 521 rte_malloc_dump_stats(FILE *f, const char *type); 522 523 /** 524 * Dump contents of all malloc heaps to a file. 525 * 526 * @note This function is not thread-safe with respect to 527 * ``rte_malloc_heap_create()``/``rte_malloc_heap_destroy()`` functions. 528 * 529 * @param f 530 * A pointer to a file for output 531 */ 532 void 533 rte_malloc_dump_heaps(FILE *f); 534 535 /** 536 * Return the IO address of a virtual address obtained through 537 * rte_malloc 538 * 539 * @param addr 540 * Address obtained from a previous rte_malloc call 541 * @return 542 * RTE_BAD_IOVA on error 543 * otherwise return an address suitable for IO 544 */ 545 rte_iova_t 546 rte_malloc_virt2iova(const void *addr); 547 548 #ifdef __cplusplus 549 } 550 #endif 551 552 #endif /* _RTE_MALLOC_H_ */ 553