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