rte_malloc.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

🌸 rte_malloc.h(3) — Library Functions Manual 🌸

okay bestie, come sit with me 💖 this is the manual page for rte_malloc.h(3), from the Library Functions Manual, and it's a big one, so grab a snack. We're doing part 1 today, and I'm gonna tell you every single thing it says, no skips, no skimming, no cap. 🫶

✨ NAME ✨

rte_malloc.h

🎀 SYNOPSIS 🎀

Like, the includes first, obviously:

#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 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. So like… don't be cute and pass it a random pointer, bestie. 💀

If the pointer is NULL, the function does nothing. (Iconic chill behaviour, honestly.)

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

Frees the memory space pointed to by the provided pointer and guarantees it will be zero'd before reuse. This function is slower than simple rte_free(), it should only be used for security keys and other sensitive data. 🔐

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

okay and that's where part 1 stops, bestie — there's more coming in part 2, so hold that thought 💜

💖 rte_calloc_socket — the calloc() glow-up, but on huge pages

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

Bestie, this is literally just replacement function for calloc(), except it pulls its memory from huge pages and the whole area comes pre-zeroed. Immaculate. ✨

Parameters 🫶

  • type — A string identifying the type of allocated objects (super useful for tracing). Can be NULL, no drama.
  • 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 (same way malloc() does it). Otherwise, the return is a pointer that's a multiple of align, which obviously has to 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. Could be not enough memory, or invalid arguments (size is 0, align is not a power of two).
  • Otherwise, the pointer to the allocated object. Slay.

🔍 rte_malloc_validate — the vibe check for memory blocks

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

If malloc debug is enabled, this checks a memory block for its header and trailer markers to confirm all is well with the block. And if size is non-null, it also hands you back the size of the block. Very giving. 🎁

Parameters

  • ptr — Pointer to the start of a data block. This must have been returned by a previous call to rte_malloc(), rte_zmalloc(), rte_calloc() or rte_realloc() — no random pointers, bestie.
  • 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 the header and trailer markers are missing or corrupted 😭
  • 0 on success ✨

📊 rte_malloc_get_socket_stats — stats o'clock for one specific heap

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. Keep that in mind, bestie 💀

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 💖

🧩 rte_malloc_heap_memory_add — adding a whole chunk of memory to a named heap

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 the specified name.

Note (yes, several, buckle up 🎀) - 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. Not a vibe. 💀 - Calling this function will erase any contents already present at the supplied memory address. 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

🗑️ rte_malloc_heap_memory_remove — taking that chunk back out

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

Remove memory chunk from heap with the specified name.

Note 🙈 - The memory chunk being removed must be the same as the one that was added; partially removing memory chunks is not supported. - The 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

🔗 rte_malloc_heap_memory_attach — linking up to memory another process already made

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

✂️ rte_malloc_heap_memory_detach — un-linking from external memory, secondary-process style

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

🎀 rte_malloc_heap_create — brand new empty heap, just for you

int rte_malloc_heap_create (const char * heap_name)

Creates a new empty malloc heap with a specified name. Fresh start energy ✨

Note — Heaps created via this call will automatically get assigned a unique socket ID, which can be found using rte_malloc_heap_get_socket(). It's giving "the app assigned you a seat." 👑

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

💀 rte_malloc_heap_destroy — bye bye heap (only if it's actually clean)

int rte_malloc_heap_destroy (const char * heap_name)

Destroys a previously created malloc heap with the 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

🔎 rte_malloc_heap_get_socket — matching a heap name to its socket ID

int rte_malloc_heap_get_socket (const char * name)

Find socket ID corresponding to a named heap. Cute little lookup. 🌸

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.

🌍 rte_malloc_heap_socket_is_external — is this socket even ours?

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. No cap. 🫶

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.

📝 rte_malloc_dump_stats — dump that stats data

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. Everything, everywhere, all at once. 💅

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. Retired. Living its best life elsewhere. 👋

🗂️ rte_malloc_dump_heaps — dump all the heaps

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_malloc_virt2iova — virtual address in, IO address out

rte_iova_t rte_malloc_virt2iova (const void * addr)

Return the IO address of a virtual address obtained through rte_malloc. One address, transmuted into another. Iconic. ⭐

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 me writing my own bio, the robots did it 🤖)

okay bestie that's the whole page, no notes 💖 this was DPDK Version 25.11.3 of rte_malloc.h(3) — go forth and allocate responsibly, mwah 💅🎀🦋

📦 where this page comes from