rte_malloc.h(3)

📦
version 25.11 · 6 versions
, in centos-stream 9

💖 rte_malloc.h(3) 💖

okay so this is the DPDK page for rte_malloc.h and bestie, it's a whole vibe ✨ — it's the malloc situation for hugepages. Buckle up, we're going through literally all of it, no skips 👑

🌸 SYNOPSIS 🌸

#include <stdio.h>
#include <stddef.h>
#include <rte_memory.h>

🎀 Data Structures 🎀

  • struct rte_malloc_socket_stats

🦋 Macros 🦋

  • #define __rte_dealloc_free __rte_dealloc(rte_free, 1)

⭐ Functions ⭐

void rte_free (void *ptr)
__rte_experimental void rte_free_sensitive (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 is literally your go-to for dynamically allocating memory out of hugepages 🧚 — it's giving "let me grab some memory for you bestie" energy.

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() 💅 (so like, if you're getting something back from these, it's rte_free()'s job to clean it up, periodt).

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. Slay, memory reclaimed ✨

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 😭 — so like, do not just hand it a random pointer, that's not the move.

If the pointer is NULL, the function does nothing. Chill. No drama 🙈

Parameters:

  • ptr — The pointer to memory to be freed.

💀 __rte_experimental void rte_free_sensitive (void * ptr)

Warning — EXPERIMENTAL: this API may change without prior notice. ⚠️ So like, don't build your whole personality on it.

Frees the memory space pointed to by the provided pointer and guarantees it will be zero'd before reuse 🔥 — yes, that's the whole point. This function is slower than simple rte_free() and it should only be used for security keys and other sensitive data 🔐 (iykyk — you use this when the data is the kind you can't have lingering).

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 — same-socket energy, we love to see it.

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 — lowkey a glow-up that moved neighborhoods, ngl.

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 the requested NUMA socket 🎯 (you picked the socket, you get the socket, main character energy).

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 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_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(...)

void* rte_calloc_socket (const char * type, size_t num, size_t size,
    unsigned align, int socket)

Okay so this is the replacement function for calloc(), but make it huge-page memory ✨. And the memory area? It gets initialised with zeros, so no gross leftover garbage data, she's clean.

Parameters (the whole roster, bestie):

  • type — a string identifying the type of allocated objects. It's useful for tracing. Can be NULL, no pressure.
  • 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 that case it must obviously be a power of two 🔥. (Minimum alignment is the cacheline size, i.e. 64-bytes, so don't get cute with it.)
  • 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. Either not enough memory, or invalid arguments (size is 0, or align is not a power of two). Not us failing a vibe check, just math.
  • Otherwise, the pointer to the allocated object 🎀

🕵️ int rte_malloc_validate(...)

int rte_malloc_validate (const void * ptr, size_t * size)

If malloc debug is enabled, this lil detective checks a memory block for header and trailer markers to make sure everything is, in fact, all well with the block 💖. And if size is non-null, she also returns the size of the block. Very generous.

Parameters:

  • ptr — pointer to the start of a data block, and it must have been returned by a previous call to rte_malloc(), rte_zmalloc(), rte_calloc() or rte_realloc(). No random pointers, please, that's giving chaos 🙈
  • size — if non-null, and the 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 rte_malloc_get_socket_stats (int socket, struct rte_malloc_socket_stats
    * socket_stats)

Get heap statistics for the specified heap. Numbers, but make it fashion 💅

Note: This function is not thread-safe with respect to rte_malloc_heap_create()/rte_malloc_heap_destroy() functions. Lowkey important, don't say I didn't warn you 🫶

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. (And yes, the doc literally says "Null" and "Pointer" for a function that returns int — the docs are just quirky like that, not my fault 😭)

🧱 int rte_malloc_heap_memory_add(...)

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 a memory chunk to a heap with specified name. Feeding the heap, icon behaviour 🍓

Notes, and these are loud ones: - 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. Genuinely do not test this one 🙏 - Calling this function will erase any contents already present at the supplied memory address. So like, if you had stuff there, it's gone. Poof. 💀

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(...)

int rte_malloc_heap_memory_remove (const char * heap_name, void * va_addr,
    size_t len)

Remove a memory chunk from the heap with the specified name. It's giving cleanup era 🧹

Notes: - Memory chunk being removed must be the same as one that was added; partially removing memory chunks is not supported. All or nothing, periodt. - 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(...)

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. Long-distance relationship but make it shared memory 🦋

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. iykyk.

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(...)

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. It's not me, it's the memory chunk 💔

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(...)

int rte_malloc_heap_create (const char * heap_name)

Creates a new empty malloc heap with a specified name. Main character energy, brand new, untouched ✨

Note: Heaps created via this call will automatically get assigned a unique socket ID, which can be found using rte_malloc_heap_get_socket(). Cute, she comes with her own ID 🎀

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(...)

int rte_malloc_heap_destroy (const char * heap_name)

Destroys a previously created malloc heap with specified name. Rest in peace, heap 🕊️

Notes: - 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. (that is literally what the docs say, even though we're destroying it — copy-paste moment, iykyk 😭)

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(...)

int rte_malloc_heap_get_socket (const char * name)

Find the socket ID corresponding to a named heap. Matching besties to their IDs 🫶

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 rte_malloc_heap_socket_is_external (int socket_id)

Check if a given socket ID refers to externally allocated memory. Vibe check on the socket 💅

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(...)

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. Every single one, no crumbs left 🌈

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. She's retired, leave her be 💜

🗂️ void rte_malloc_dump_heaps(...)

void rte_malloc_dump_heaps (FILE * f)

Dump the contents of all malloc heaps to a file. Full tour of the whole lineup 👑

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(...)

rte_iova_t rte_malloc_virt2iova (const void * addr)

Return the IO address of a virtual address obtained through rte_malloc. Glow-up from virtual to IO 🔥

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. Not a human, just a very diligent little doc machine doing its thing 🤖💖

Okay bestie, that's the whole page — every last flag, error code, and note, intact and accounted for 💅 This was rte_malloc.h(3) from DPDK version 25.11.0, dated Fri Jan 30 2026 — go forth and allocate responsibly, mwah 🫶🌸

📦 where this page comes from