--- name: "rte_malloc.h" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_malloc.h" --- # rte\_malloc.h(3) ## NAME rte\_malloc.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ ### Data Structures struct **rte\_malloc\_socket\_stats**\ ### Macros \#define **\_\_rte\_dealloc\_free** **\_\_rte\_dealloc**(**rte\_free**, 1)\ ### Functions void **rte\_free** (void \*ptr)\ void \* **rte\_malloc** (const char \*type, size\_t size, unsigned align) **\_\_rte\_alloc\_size**(2) **\_\_rte\_alloc\_align**(3) **\_\_rte\_malloc** **\_\_rte\_dealloc\_free**\ void \* **rte\_zmalloc** (const char \*type, size\_t size, unsigned align) **\_\_rte\_alloc\_size**(2) **\_\_rte\_alloc\_align**(3) **\_\_rte\_malloc** **\_\_rte\_dealloc\_free**\ void \* **rte\_calloc** (const char \*type, size\_t num, size\_t size, unsigned align) **\_\_rte\_alloc\_size**(2\ void \* **rte\_realloc** (void \*ptr, size\_t size, unsigned int align) **\_\_rte\_alloc\_size**(2) **\_\_rte\_alloc\_align**(3) **\_\_rte\_malloc** **\_\_rte\_dealloc\_free**\ void \* **rte\_realloc\_socket** (void \*ptr, size\_t size, unsigned int align, int socket) **\_\_rte\_alloc\_size**(2) **\_\_rte\_alloc\_align**(3) **\_\_rte\_malloc** **\_\_rte\_dealloc\_free**\ void \* **rte\_malloc\_socket** (const char \*type, size\_t size, unsigned align, int socket) **\_\_rte\_alloc\_size**(2) **\_\_rte\_alloc\_align**(3) **\_\_rte\_malloc** **\_\_rte\_dealloc\_free**\ void \* **rte\_zmalloc\_socket** (const char \*type, size\_t size, unsigned align, int socket) **\_\_rte\_alloc\_size**(2) **\_\_rte\_alloc\_align**(3) **\_\_rte\_malloc** **\_\_rte\_dealloc\_free**\ void \* **rte\_calloc\_socket** (const char \*type, size\_t num, size\_t size, unsigned align, int socket) **\_\_rte\_alloc\_size**(2\ int **rte\_malloc\_validate** (const void \*ptr, size\_t \*size)\ int **rte\_malloc\_get\_socket\_stats** (int socket, struct **rte\_malloc\_socket\_stats** \*socket\_stats)\ int **rte\_malloc\_heap\_memory\_add** (const char \*heap\_name, void \*va\_addr, size\_t len, **rte\_iova\_t** iova\_addrs\[\], unsigned int n\_pages, size\_t page\_sz)\ int **rte\_malloc\_heap\_memory\_remove** (const char \*heap\_name, void \*va\_addr, size\_t len)\ int **rte\_malloc\_heap\_memory\_attach** (const char \*heap\_name, void \*va\_addr, size\_t len)\ int **rte\_malloc\_heap\_memory\_detach** (const char \*heap\_name, void \*va\_addr, size\_t len)\ int **rte\_malloc\_heap\_create** (const char \*heap\_name)\ int **rte\_malloc\_heap\_destroy** (const char \*heap\_name)\ int **rte\_malloc\_heap\_get\_socket** (const char \*name)\ int **rte\_malloc\_heap\_socket\_is\_external** (int socket\_id)\ void **rte\_malloc\_dump\_stats** (FILE \*f, const char \*type)\ void **rte\_malloc\_dump\_heaps** (FILE \*f)\ **rte\_iova\_t** **rte\_malloc\_virt2iova** (const void \*addr)\ ## Detailed Description RTE Malloc. This library provides methods for dynamically allocating memory from hugepages. Definition in file **rte\_malloc.h**. ## Macro Definition Documentation ### #define \_\_rte\_dealloc\_free \_\_rte\_dealloc(rte\_free, 1) Functions that expect return value to be freed with **rte\_free()** Definition at line **37** of file **rte\_malloc.h**. ## Function Documentation ### void rte\_free (void \* ptr) Frees the memory space pointed to by the provided pointer. This pointer must have been returned by a previous call to **rte\_malloc()**, **rte\_zmalloc()**, **rte\_calloc()** or **rte\_realloc()**. The behaviour of **rte\_free()** is undefined if the pointer does not match this requirement. If the pointer is NULL, the function does nothing. **Parameters** *ptr* The pointer to memory to be freed. ### void \* rte\_malloc (const char \* type, size\_t size, unsigned align) This function allocates memory from the huge-page area of memory. The memory is not cleared. In NUMA systems, the memory allocated resides on the same NUMA socket as the core that calls this function. **Parameters** *type* A string identifying the type of allocated objects (useful for tracing). Can be NULL. \ *size* Size (in bytes) to be allocated. \ *align* If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. In this case, it must be a power of two. (Minimum alignment is the cacheline size, i.e. 64-bytes) **Returns** - • NULL on error. Not enough memory, or invalid arguments (size is 0, align is not a power of two). - • Otherwise, the pointer to the allocated object. ### void \* rte\_zmalloc (const char \* type, size\_t size, unsigned align) Allocate zeroed memory from the heap. Equivalent to **rte\_malloc()** except that the memory zone is initialised with zeros. In NUMA systems, the memory allocated resides on the same NUMA socket as the core that calls this function. **Parameters** *type* A string identifying the type of allocated objects (useful for tracing). Can be NULL. \ *size* Size (in bytes) to be allocated. \ *align* If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. In this case, it must obviously be a power of two. (Minimum alignment is the cacheline size, i.e. 64-bytes) **Returns** - • NULL on error. Not enough memory, or invalid arguments (size is 0, align is not a power of two). - • Otherwise, the pointer to the allocated object. ### void \* rte\_calloc (const char \* type, size\_t num, size\_t size, unsigned align) Replacement function for calloc(), using huge-page memory. Memory area is initialised with zeros. In NUMA systems, the memory allocated resides on the same NUMA socket as the core that calls this function. **Parameters** *type* A string identifying the type of allocated objects (useful for tracing). Can be NULL. \ *num* Number of elements to be allocated. \ *size* Size (in bytes) of a single element. \ *align* If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. In this case, it must obviously be a power of two. (Minimum alignment is the cacheline size, i.e. 64-bytes) **Returns** - • NULL on error. Not enough memory, or invalid arguments (size is 0, align is not a power of two). - • Otherwise, the pointer to the allocated object. ### void \* rte\_realloc (void \* ptr, size\_t size, unsigned int align) Replacement function for realloc(), using huge-page memory. Reserved area memory is resized, preserving contents. In NUMA systems, the new area may not reside on the same NUMA node as the old one. **Parameters** *ptr* Pointer to already allocated memory \ *size* Size (in bytes) of new area. If this is 0, memory is freed. \ *align* If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. In this case, it must obviously be a power of two. (Minimum alignment is the cacheline size, i.e. 64-bytes) **Returns** - • NULL on error. Not enough memory, or invalid arguments (size is 0, align is not a power of two). - • Otherwise, the pointer to the reallocated memory. ### void \* rte\_realloc\_socket (void \* ptr, size\_t size, unsigned int align, int socket) Replacement function for realloc(), using huge-page memory. Reserved area memory is resized, preserving contents. In NUMA systems, the new area resides on requested NUMA socket. **Parameters** *ptr* Pointer to already allocated memory \ *size* Size (in bytes) of new area. If this is 0, memory is freed. \ *align* If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. In this case, it must obviously be a power of two. (Minimum alignment is the cacheline size, i.e. 64-bytes) \ *socket* NUMA socket to allocate memory on. **Returns** - • NULL on error. Not enough memory, or invalid arguments (size is 0, align is not a power of two). - • Otherwise, the pointer to the reallocated memory. ### void \* rte\_malloc\_socket (const char \* type, size\_t size, unsigned align, int socket) This function allocates memory from the huge-page area of memory. The memory is not cleared. **Parameters** *type* A string identifying the type of allocated objects (useful for tracing). Can be NULL. \ *size* Size (in bytes) to be allocated. \ *align* If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. In this case, it must be a power of two. (Minimum alignment is the cacheline size, i.e. 64-bytes) \ *socket* NUMA socket to allocate memory on. If SOCKET\_ID\_ANY is used, this function will behave the same as **rte\_malloc()**. **Returns** - • NULL on error. Not enough memory, or invalid arguments (size is 0, align is not a power of two). - • Otherwise, the pointer to the allocated object. ### void \* rte\_zmalloc\_socket (const char \* type, size\_t size, unsigned align, int socket) Allocate zeroed memory from the heap. Equivalent to **rte\_malloc()** except that the memory zone is initialised with zeros. **Parameters** *type* A string identifying the type of allocated objects (useful for tracing). Can be NULL. \ *size* Size (in bytes) to be allocated. \ *align* If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. In this case, it must obviously be a power of two. (Minimum alignment is the cacheline size, i.e. 64-bytes) \ *socket* NUMA socket to allocate memory on. If SOCKET\_ID\_ANY is used, this function will behave the same as **rte\_zmalloc()**. **Returns** - • NULL on error. Not enough memory, or invalid arguments (size is 0, align is not a power of two). - • Otherwise, the pointer to the allocated object. ### void \* rte\_calloc\_socket (const char \* type, size\_t num, size\_t size, unsigned align, int socket) Replacement function for calloc(), using huge-page memory. Memory area is initialised with zeros. **Parameters** *type* A string identifying the type of allocated objects (useful for tracing). Can be NULL. \ *num* Number of elements to be allocated. \ *size* Size (in bytes) of a single element. \ *align* If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of *align*. In this case, it must obviously be a power of two. (Minimum alignment is the cacheline size, i.e. 64-bytes) \ *socket* NUMA socket to allocate memory on. If SOCKET\_ID\_ANY is used, this function will behave the same as **rte\_calloc()**. **Returns** - • NULL on error. Not enough memory, or invalid arguments (size is 0, align is not a power of two). - • Otherwise, the pointer to the allocated object. ### int rte\_malloc\_validate (const void \* ptr, size\_t \* size) If malloc debug is enabled, check a memory block for header and trailer markers to indicate that all is well with the block. If size is non-null, also return the size of the block. **Parameters** *ptr* pointer to the start of a data block, must have been returned by a previous call to **rte\_malloc()**, **rte\_zmalloc()**, **rte\_calloc()** or **rte\_realloc()** \ *size* if non-null, and memory block pointer is valid, returns the size of the memory block **Returns** \-1 on error, invalid pointer passed or header and trailer markers are missing or corrupted 0 on success ### int rte\_malloc\_get\_socket\_stats (int socket, struct rte\_malloc\_socket\_stats \* socket\_stats) Get heap statistics for the specified heap. **Note** This function is not thread-safe with respect to **rte\_malloc\_heap\_create()/rte\_malloc\_heap\_destroy() functions.** **Parameters** *socket* **An unsigned integer specifying the socket to get heap statistics for** \ *socket\_stats* **A structure which provides memory to store statistics** **Returns** **Null on error Pointer to structure storing statistics on success** ### int rte\_malloc\_heap\_memory\_add (const char \* heap\_name, void \* va\_addr, size\_t len, rte\_iova\_t iova\_addrs\[\], unsigned int n\_pages, size\_t page\_sz) **Add memory chunk to a heap with specified name.** **Note** **Multiple memory chunks can be added to the same heap** **Before accessing this memory in other processes, it needs to be attached in each of those processes by calling** `rte_malloc_heap_memory_attach` **in each other process.** **Memory must be previously allocated for DPDK to be able to use it as a malloc heap. Failing to do so will result in undefined behavior, up to and including segmentation faults.** **Calling this function will erase any contents already present at the supplied memory address.** **Parameters** *heap\_name* **Name of the heap to add memory chunk to** \ *va\_addr* **Start of virtual area to add to the heap. Must be aligned by** `page_sz`**.** \ *len* **Length of virtual area to add to the heap. Must be aligned by** `page_sz`**.** \ *iova\_addrs* **Array of page IOVA addresses corresponding to each page in this memory area. Can be NULL, in which case page IOVA addresses will be set to RTE\_BAD\_IOVA.** \ *n\_pages* **Number of elements in the iova\_addrs array. Ignored if** `iova_addrs` **is NULL.** \ *page\_sz* **Page size of the underlying memory** **Returns** - • **0 on success** - • **-1 in case of error, with rte\_errno set to one of the following: EINVAL - one of the parameters was invalid EPERM - attempted to add memory to a reserved heap ENOSPC - no more space in internal config to store a new memory chunk** ### int rte\_malloc\_heap\_memory\_remove (const char \* heap\_name, void \* va\_addr, size\_t len) **Remove memory chunk from heap with specified name.** **Note** **Memory chunk being removed must be the same as one that was added; partially removing memory chunks is not supported** **Memory area must not contain any allocated elements to allow its removal from the heap** **All other processes must detach from the memory chunk prior to it being removed from the heap.** **Parameters** *heap\_name* **Name of the heap to remove memory from** \ *va\_addr* **Virtual address to remove from the heap** \ *len* **Length of virtual area to remove from the heap** **Returns** - • **0 on success** - • **-1 in case of error, with rte\_errno set to one of the following: EINVAL - one of the parameters was invalid EPERM - attempted to remove memory from a reserved heap ENOENT - heap or memory chunk was not found EBUSY - memory chunk still contains data** ### int rte\_malloc\_heap\_memory\_attach (const char \* heap\_name, void \* va\_addr, size\_t len) **Attach to an already existing chunk of external memory in another process.** **Note** **This function must be called before any attempt is made to use an already existing external memory chunk. This function does** *not* **need to be called if a call to** `rte_malloc_heap_memory_add` **was made in the current process.** **Parameters** *heap\_name* **Heap name to which this chunk of memory belongs** \ *va\_addr* **Start address of memory chunk to attach to** \ *len* **Length of memory chunk to attach to** **Returns** **0 on successful attach -1 on unsuccessful attach, with rte\_errno set to indicate cause for error: EINVAL - one of the parameters was invalid EPERM - attempted to attach memory to a reserved heap ENOENT - heap or memory chunk was not found** ### int rte\_malloc\_heap\_memory\_detach (const char \* heap\_name, void \* va\_addr, size\_t len) **Detach from a chunk of external memory in secondary process.** **Note** **This function must be called in before any attempt is made to remove external memory from the heap in another process. This function does** *not* **need to be called if a call to** `rte_malloc_heap_memory_remove` **will be called in current process.** **Parameters** *heap\_name* **Heap name to which this chunk of memory belongs** \ *va\_addr* **Start address of memory chunk to attach to** \ *len* **Length of memory chunk to attach to** **Returns** **0 on successful detach -1 on unsuccessful detach, with rte\_errno set to indicate cause for error: EINVAL - one of the parameters was invalid EPERM - attempted to detach memory from a reserved heap ENOENT - heap or memory chunk was not found** ### int rte\_malloc\_heap\_create (const char \* heap\_name) **Creates a new empty malloc heap with a specified name.** **Note** **Heaps created via this call will automatically get assigned a unique socket ID, which can be found using rte\_malloc\_heap\_get\_socket()** **Parameters** *heap\_name* **Name of the heap to create.** **Returns** - • **0 on successful creation** - • **-1 in case of error, with rte\_errno set to one of the following: EINVAL -** `heap_name` **was NULL, empty or too long EEXIST - heap by name of** `heap_name` **already exists ENOSPC - no more space in internal config to store a new heap** ### int rte\_malloc\_heap\_destroy (const char \* heap\_name) **Destroys a previously created malloc heap with specified name.** **Note** **This function will return a failure result if not all memory allocated from the heap has been freed back to the heap** **This function will return a failure result if not all memory segments were removed from the heap prior to its destruction** **Parameters** *heap\_name* **Name of the heap to create.** **Returns** - • **0 on success** - • **-1 in case of error, with rte\_errno set to one of the following: EINVAL -** `heap_name` **was NULL, empty or too long ENOENT - heap by the name of** `heap_name` **was not found EPERM - attempting to destroy reserved heap EBUSY - heap still contains data** ### int rte\_malloc\_heap\_get\_socket (const char \* name) **Find socket ID corresponding to a named heap.** **Parameters** *name* **Heap name to find socket ID for** **Returns** **Socket ID in case of success (a non-negative number) -1 in case of error, with rte\_errno set to one of the following: EINVAL -** `name` **was NULL ENOENT - heap identified by the name** `name` **was not found** ### int rte\_malloc\_heap\_socket\_is\_external (int socket\_id) **Check if a given socket ID refers to externally allocated memory.** **Note** **Passing SOCKET\_ID\_ANY will return 0.** **Parameters** *socket\_id* **Socket ID to check** **Returns** **1 if socket ID refers to externally allocated memory 0 if socket ID refers to internal DPDK memory -1 if socket ID is invalid** ### void rte\_malloc\_dump\_stats (FILE \* f, const char \* type) **Dump statistics.** **Dump for the specified type to a file. If the type argument is NULL, all memory types will be dumped.** **Note** **This function is not thread-safe with respect to rte\_malloc\_heap\_create()/rte\_malloc\_heap\_destroy() functions.** **Parameters** *f* **A pointer to a file for output** \ *type* **Deprecated parameter unused.** ### void rte\_malloc\_dump\_heaps (FILE \* f) **Dump contents of all malloc heaps to a file.** **Note** **This function is not thread-safe with respect to rte\_malloc\_heap\_create()/rte\_malloc\_heap\_destroy() functions.** **Parameters** *f* **A pointer to a file for output** ### rte\_iova\_t rte\_malloc\_virt2iova (const void \* addr) **Return the IO address of a virtual address obtained through rte\_malloc** **Parameters** *addr* **Address obtained from a previous rte\_malloc call** **Returns** **RTE\_BAD\_IOVA on error otherwise return an address suitable for IO** ## Author **Generated automatically by Doxygen for DPDK from the source code.**