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