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