rte_memory.h(3)
π¦ rte_memory.h β memory API bestie check π¦
okay so this is the rte_memory.h(3) page from the Library Functions Manual, and it's literally the memory-related RTE API. It is giving low-level memory main character energy, so hydrate and let's go. π
π NAME π
rte_memory.h β that's the name. No extra lore. Periodt. π
β¨ SYNOPSIS β¨
First things first, include these headers exactly, bestie:
#include <stdint.h>
#include <stddef.h>
#include <stdio.h>
#include <rte_bitops.h>
#include <rte_common.h>
#include <rte_config.h>
#include <rte_eal_memconfig.h>
#include <rte_fbarray.h>
π§± Data Structures π§±
struct rte_memsegstruct rte_memseg_list
π§Έ Macros π§Έ
#define SOCKET_ID_ANY -1
#define RTE_MEMSEG_FLAG_DO_NOT_FREE RTE_BIT32(0)
#define RTE_MEMSEG_FLAG_DIRTY RTE_BIT32(1)
#define RTE_MEM_EVENT_CALLBACK_NAME_LEN 64
#define RTE_MEM_ALLOC_VALIDATOR_NAME_LEN 64
𧬠Typedefs π§¬
typedef int(* rte_memseg_walk_t) (const struct rte_memseg_list *msl,
const struct rte_memseg *ms, void *arg)
typedef int(* rte_memseg_contig_walk_t) (const struct rte_memseg_list
*msl, const struct rte_memseg *ms, size_t len, void *arg)
typedef int(* rte_memseg_list_walk_t) (const struct rte_memseg_list
*msl, void *arg)
typedef void(* rte_mem_event_callback_t) (enum rte_mem_event event_type,
const void *addr, size_t len, void *arg)
typedef int(* rte_mem_alloc_validator_t) (int socket_id, size_t
cur_limit, size_t new_len)
π Enumerations π
enum rte_mem_event { RTE_MEM_EVENT_ALLOC = 0, RTE_MEM_EVENT_FREE }
π οΈ Functions π οΈ
int rte_mem_lock_page (const void *virt)
phys_addr_t rte_mem_virt2phy (const void *virt)
rte_iova_t rte_mem_virt2iova (const void *virt)
void * rte_mem_iova2virt (rte_iova_t iova)
struct rte_memseg * rte_mem_virt2memseg (const void *virt, const struct
rte_memseg_list *msl)
struct rte_memseg_list * rte_mem_virt2memseg_list (const void *virt)
int rte_memseg_walk (rte_memseg_walk_t func, void *arg)
int rte_memseg_contig_walk (rte_memseg_contig_walk_t func, void *arg)
int rte_memseg_list_walk (rte_memseg_list_walk_t func, void *arg)
__rte_locks_excluded(rte_mcfg_mem_get_lock())
int rte_memseg_walk_thread_unsafe (rte_memseg_walk_t func, void *arg)
int rte_memseg_contig_walk_thread_unsafe (rte_memseg_contig_walk_t func,
void *arg)
int rte_memseg_list_walk_thread_unsafe (rte_memseg_list_walk_t func,
void *arg)
int rte_memseg_get_fd (const struct rte_memseg *ms)
int rte_memseg_get_fd_thread_unsafe (const struct rte_memseg *ms)
int rte_memseg_get_fd_offset (const struct rte_memseg *ms, size_t
*offset)
int rte_memseg_get_fd_offset_thread_unsafe (const struct rte_memseg *ms,
size_t *offset)
int rte_extmem_register (void *va_addr, size_t len, rte_iova_t
iova_addrs[], unsigned int n_pages, size_t page_sz)
int rte_extmem_unregister (void *va_addr, size_t len)
int rte_extmem_attach (void *va_addr, size_t len)
int rte_extmem_detach (void *va_addr, size_t len)
void rte_dump_physmem_layout (FILE *f)
uint64_t rte_eal_get_physmem_size (void)
unsigned rte_memory_get_nchannel (void)
unsigned rte_memory_get_nrank (void)
int rte_mem_check_dma_mask (uint8_t maskbits)
int rte_mem_check_dma_mask_thread_unsafe (uint8_t maskbits)
void rte_mem_set_dma_mask (uint8_t maskbits)
int rte_eal_using_phys_addrs (void)
int rte_mem_event_callback_register (const char *name,
rte_mem_event_callback_t clb, void *arg)
int rte_mem_event_callback_unregister (const char *name, void *arg)
int rte_mem_alloc_validator_register (const char *name,
rte_mem_alloc_validator_t clb, int socket_id, size_t limit)
Register validator callback for memory allocations.
int rte_mem_alloc_validator_unregister (const char *name, int socket_id)
Unregister validator callback for memory allocations.
__rte_experimental void rte_memzero_explicit (void *dst, size_t sz)
static __rte_experimental bool rte_memeq_timingsafe (const void *a,
const void *b, size_t n)
Also, the synopsis specifically says:
rte_mem_alloc_validator_registerβ Register validator callback for memory allocations.rte_mem_alloc_validator_unregisterβ Unregister validator callback for memory allocations.
π Detailed Description π
Memory-related RTE API.
Definition in file rte_memory.h.
π§· Macro Definition Documentation π§·
#define SOCKET_ID_ANY -1
Any NUMA socket.
Definition at line 39 of file rte_memory.h.
#define RTE_MEMSEG_FLAG_DO_NOT_FREE RTE_BIT32(0)
Prevent this segment from being freed back to the OS.
Definition at line 42 of file rte_memory.h.
#define RTE_MEMSEG_FLAG_DIRTY RTE_BIT32(1)
This segment is not filled with zeros.
Definition at line 44 of file rte_memory.h.
#define RTE_MEM_EVENT_CALLBACK_NAME_LEN 64
maximum length of callback name
Definition at line 609 of file rte_memory.h.
#define RTE_MEM_ALLOC_VALIDATOR_NAME_LEN 64
maximum length of alloc validator name
Definition at line 665 of file rte_memory.h.
π§΅ Typedef Documentation π§΅
rte_memseg_walk_t
typedef int(* rte_memseg_walk_t) (const struct rte_memseg_list *msl, const
struct rte_memseg *ms, void *arg)
Memseg walk function prototype.
- Returning
0will continue walk. - Returning
1will stop the walk. - Returning
-1will stop the walk and report error.
Definition at line 167 of file rte_memory.h.
rte_memseg_contig_walk_t
typedef int(* rte_memseg_contig_walk_t) (const struct rte_memseg_list *msl,
const struct rte_memseg *ms, size_t len, void *arg)
Memseg contig walk function prototype. This will trigger a callback on every VA-contiguous area starting at memseg ms, so total valid VA space at each callback call will be [ms->addr, ms->addr + len).
- Returning
0will continue walk. - Returning
1will stop the walk. - Returning
-1will stop the walk and report error.
Definition at line 179 of file rte_memory.h.
rte_memseg_list_walk_t
typedef int(* rte_memseg_list_walk_t) (const struct rte_memseg_list *msl,
void *arg)
Memseg list walk function prototype. This will trigger a callback on every allocated memseg list.
- Returning
0will continue walk. - Returning
1will stop the walk. - Returning
-1will stop the walk and report error.
Definition at line 190 of file rte_memory.h.
rte_mem_event_callback_t
typedef void(* rte_mem_event_callback_t) (enum rte_mem_event event_type,
const void *addr, size_t len, void *arg)
Function typedef used to register callbacks for memory events.
Definition at line 615 of file rte_memory.h.
rte_mem_alloc_validator_t
typedef int(* rte_mem_alloc_validator_t) (int socket_id, size_t cur_limit,
size_t new_len)
Function typedef used to register memory allocation validation callbacks.
- Returning
0will allow allocation attempt to continue. - Returning
-1will prevent allocation from succeeding.
Definition at line 673 of file rte_memory.h.
π Enumeration Type Documentation π
enum rte_mem_event
Enum indicating which kind of memory event has happened. Used by callbacks to distinguish between memory allocations and deallocations.
RTE_MEM_EVENT_ALLOCβ Allocation event.RTE_MEM_EVENT_FREEβ Deallocation event.
Definition at line 605 of file rte_memory.h.
π» Function Documentation π»
int rte_mem_lock_page (const void * virt)
Lock page in physical memory and prevent from swapping.
Parameters
- virt β The virtual address.
Returns
0 on success, negative on error.
phys_addr_t rte_mem_virt2phy (const void * virt)
Get physical address of any mapped virtual address in the current process. It is found by browsing the /proc/self/pagemap special file. The page must be locked.
Parameters
- virt β The virtual address.
Returns
The physical address or RTE_BAD_IOVA on error.
rte_iova_t rte_mem_virt2iova (const void * virt)
Get IO virtual address of any mapped virtual address in the current process.
Note: This function will not check internal page table. Instead, in IOVA as PA mode, it will fall back to getting real physical address (which may not match the expected IOVA, such as what was specified for external memory).
Parameters
- virt β The virtual address.
Returns
The IO address or RTE_BAD_IOVA on error.
void * rte_mem_iova2virt (rte_iova_t iova)
Get virtual memory address corresponding to iova address.
Note: This function read-locks the memory hotplug subsystem, and thus cannot be used within memory-related callback functions.
Parameters
- iova β The iova address.
Returns
Virtual address corresponding to iova address (or NULL if address does not exist within DPDK memory map).
struct rte_memseg * rte_mem_virt2memseg (const void * virt, const struct rte_memseg_list * msl)
Get memseg to which a particular virtual address belongs.
Parameters
- virt β The virtual address.
- msl β The memseg list in which to look up based on virt address (can be
NULL).
Returns
Memseg pointer on success, or NULL on error.
struct rte_memseg_list * rte_mem_virt2memseg_list (const void * virt)
Get memseg list corresponding to virtual memory address.
Parameters
- virt β The virtual address.
Returns
Memseg list to which this virtual address belongs to.
int rte_memseg_walk (rte_memseg_walk_t func, void * arg)
Walk list of all memsegs.
Note: This function read-locks the memory hotplug subsystem, and thus cannot be used within memory-related callback functions. This function will also walk through externally allocated segments. It is up to the user to decide whether to skip through these segments.
Parameters
- func β Iterator function
- arg β Argument passed to iterator
Returns
0if walked over the entire list1if stopped by the user-1if user function reported error
int rte_memseg_contig_walk (rte_memseg_contig_walk_t func, void * arg)
Walk each VA-contiguous area.
Note: This function read-locks the memory hotplug subsystem, and thus cannot be used within memory-related callback functions. This function will also walk through externally allocated segments. It is up to the user to decide whether to skip through these segments.
Parameters
- func β Iterator function
- arg β Argument passed to iterator
Returns
0if walked over the entire list1if stopped by the user-1if user function reported error
int rte_memseg_list_walk (rte_memseg_list_walk_t func, void * arg)
Walk each allocated memseg list.
Note: This function read-locks the memory hotplug subsystem, and thus cannot be used within memory-related callback functions. This function will also walk through externally allocated segments. It is up to the user to decide whether to skip through these segments.
Parameters
- func β Iterator function
- arg β Argument passed to iterator
Returns
0if walked over the entire list1if stopped by the user-1if user function reported error
int rte_memseg_walk_thread_unsafe (rte_memseg_walk_t func, void * arg)
Walk list of all memsegs without performing any locking.
Note: This function does not perform any locking, and is only safe to call from within memory-related callback functions.
Parameters
- func β Iterator function
- arg β Argument passed to iterator
β¦and wrapping up that last one, here's how it reports back:
Returns β 0 if it walked over the entire list, 1 if you (the user) stopped it, and -1 if your user function reported an error β¨
int rte_memseg_contig_walk_thread_unsafe(rte_memseg_contig_walk_t func, void * arg)
Walks every VA-contiguous area, and does it without doing any locking π
Note β bestie, this one does not perform any locking, and it's only safe to call from within memory-related callback functions. That's the whole deal, iykyk.
funcβ the iterator functionargβ the argument that gets passed to the iterator
Returns β 0 if it walked over the entire list, 1 if the user stopped it, -1 if the user function reported an error π«Ά
int rte_memseg_list_walk_thread_unsafe(rte_memseg_list_walk_t func, void * arg)
Walks each allocated memseg list, no locking involved, periodt β¨
Note β same warning as above: no locking here, and it's only safe to call from within memory-related callback functions.
funcβ the iterator functionargβ the argument passed to the iterator
Returns β 0 if it walked over the entire list, 1 if the user stopped it, -1 if the user function reported an error π
int rte_memseg_get_fd(const struct rte_memseg * ms)
Hands you the file descriptor tied to a particular memseg (if one's available) πΈ
Note β this function read-locks the memory hotplug subsystem, so no cap, it cannot be used inside memory-related callback functions. Deadlock city. π Also: this returns an internal file descriptor. Doing literally any operations on this fd is inherently dangerous, so treat it as read-only for all intents and purposes. Like, respectfully, don't touch. π
msβ a pointer to the memseg you want the file descriptor for
Returns β a valid file descriptor on success; -1 on error, with rte_errno set to one of these:
EINVALβ themspointer wasNULLor didn't point to a valid memsegENODEVβmsfd is not availableENOENTβmsis an unused segmentENOTSUPβ segment fd's are not supported
int rte_memseg_get_fd_thread_unsafe(const struct rte_memseg * ms)
Same energy as above β returns the file descriptor associated with a particular memseg (if available), just the thread-unsafe flavour π
Note β this function does not perform any locking, and is only safe to call from within memory-related callback functions. And again: internal file descriptor alert π¨ performing any operations on it is inherently dangerous, so treat it as read-only for all intents and purposes.
msβ a pointer to memseg for which to get the file descriptor
Returns β valid file descriptor on success; -1 on error, with rte_errno set to:
EINVALβmspointer wasNULLor didn't point to a valid memsegENODEVβmsfd is not availableENOENTβmsis an unused segmentENOTSUPβ segment fd's are not supported
int rte_memseg_get_fd_offset(const struct rte_memseg * ms, size_t * offset)
Gets the offset into the segment file descriptor associated with a particular memseg (if it's available) π
Note β this one read-locks the memory hotplug subsystem, so it cannot be used within memory-related callback functions. No exceptions, bestie.
msβ a pointer to memseg for which to get the file descriptoroffsetβ a pointer to the offset value where the result will be stored
Returns β valid file descriptor on success; -1 on error, with rte_errno set to:
EINVALβmspointer wasNULLor didn't point to a valid memsegEINVALβoffsetpointer wasNULLENODEVβmsfd is not availableENOENTβmsis an unused segmentENOTSUPβ segment fd's are not supported
(Yes, EINVAL shows up twice β that's not a typo, that's just how it is π)
int rte_memseg_get_fd_offset_thread_unsafe(const struct rte_memseg * ms, size_t * offset)
The no-locking twin: gets the offset into the segment file descriptor for a particular memseg (if available) π¦
Note β does not perform any locking, and it's only safe to call from within memory-related callback functions.
msβ a pointer to memseg for which to get the file descriptoroffsetβ a pointer to the offset value where the result will be stored
Returns β valid file descriptor on success; -1 on error, with rte_errno set to:
EINVALβmspointer wasNULLor did not point to a valid memsegEINVALβoffsetpointer wasNULLENODEVβmsfd is not availableENOENTβmsis an unused segmentENOTSUPβ segment fd's are not supported
int rte_extmem_register(void * va_addr, size_t len, rte_iova_t iova_addrs[], unsigned int n_pages, size_t page_sz)
Registers an external memory chunk with DPDK π§
Note β using this API is mutually exclusive with therte_mallocfamily of API's. Pick a lane, babe. This API will not perform any DMA mapping. It's expected that the user does that themselves. You got this. π«Ά Before accessing this memory in other processes, it needs to be attached in each of those processes by callingrte_extmem_attachin each other process.
va_addrβ start of the virtual area to register. Must be aligned bypage_sz.lenβ length of the virtual area to register. Must be aligned bypage_sz.iova_addrsβ array of page IOVA addresses corresponding to each page in this memory area. Can beNULL, in which case page IOVA addresses will be set toRTE_BAD_IOVA.n_pagesβ number of elements in theiova_addrsarray. Ignored ifiova_addrsisNULL.page_szβ page size of the underlying memory
Returns
0on success π-1in case of error, withrte_errnoset to one of the following:EINVALβ one of the parameters was invalidEEXISTβ memory chunk is already registeredENOSPCβ no more space in internal config to store a new memory chunk
int rte_extmem_unregister(void * va_addr, size_t len)
Unregisters an external memory chunk with DPDK π
Note β mutually exclusive with therte_mallocfamily of API's, same as above. This API will not perform any DMA unmapping. It's expected that the user will do that themselves. Before calling this function, all other processes must callrte_extmem_detachto detach from the memory area. Like, every single one. π
va_addrβ start of the virtual area to unregisterlenβ length of the virtual area to unregister
Returns
0on success β¨-1in case of error, withrte_errnoset to one of the following:EINVALβ one of the parameters was invalidENOENTβ memory chunk was not found
int rte_extmem_attach(void * va_addr, size_t len)
Attaches to an external memory chunk that was registered in another process π
Note β mutually exclusive with the rte_malloc family of API's. This API will not perform any DMA mapping β the user is expected to do that themselves. (No, we're not gonna do it for you.)
va_addrβ start of the virtual area to registerlenβ length of the virtual area to register
Returns
0on success β-1in case of error, withrte_errnoset to one of the following:EINVALβ one of the parameters was invalidENOENTβ memory chunk was not found
int rte_extmem_detach(void * va_addr, size_t len)
Detaches from an external memory chunk that was registered in another process π¦
Note β yep, mutually exclusive with the rte_malloc family of API's. This API will not perform any DMA unmapping β it's expected that the user will do that themselves. (Seeing a pattern? π)
va_addrβ start of the virtual area to unregisterlenβ length of the virtual area to unregister
Returns
0on success π-1in case of error, withrte_errnoset to one of the following:EINVALβ one of the parameters was invalidENOENTβ memory chunk was not found
void rte_dump_physmem_layout(FILE * f)
Dumps the physical memory layout to a file π β honestly kinda iconic for debugging.
Note β this function read-locks the memory hotplug subsystem, so it cannot be used within memory-related callback functions.
fβ a pointer to a file for output
uint64_t rte_eal_get_physmem_size(void)
Gets the total amount of available physical memory π
Note β read-locks the memory hotplug subsystem, so nope, not allowed inside memory-related callback functions.
Returns β the total amount of available physical memory, in bytes π
unsigned rte_memory_get_nchannel(void)
Gets the number of memory channels π
Returns β the number of memory channels on the system. The value is 0 if it's unknown or if it's not the same on all devices.
unsigned rte_memory_get_nrank(void)
Gets the number of memory ranks π
Returns β the number of memory ranks on the system. The value is 0 if it's unknown or if it's not the same on all devices.
int rte_mem_check_dma_mask(uint8_t maskbits)
Checks whether all currently allocated memory segments are compliant with the supplied DMA address width π
maskbitsβ address width to check against
int rte_mem_check_dma_mask_thread_unsafe(uint8_t maskbits)
Same vibe check as above β checks if all currently allocated memory segments are compliant with the supplied DMA address width β but this one uses rte_memseg_walk_thread_unsafe instead of rte_memseg_walk, which implies memory_hotplug_lock will not be acquired, avoiding deadlock during memory initialization πβ¨
Important β this function is just for EAL core memory internal use. Drivers should use the previous rte_mem_check_dma_mask. Like, read the room. π
maskbitsβ address width to check against
void rte_mem_set_dma_mask(uint8_t maskbits)
Sets the dma mask to use once memory initialization is done πΈ
Heads up: the previous functions rte_mem_check_dma_mask and rte_mem_check_dma_mask_thread_unsafe cannot be used safely until memory has been initialized. So like, order matters, bestie. π
int rte_eal_using_phys_addrs(void)
Okay so this one's got lore: drivers based on uio will not load unless physical addresses are obtainable, and it's only possible to get physical addresses when running as a privileged user π
Returns β 1 if the system is able to obtain physical addresses, 0 if it's using DMA addresses through an IOMMU.
int rte_mem_event_callback_register(const char * name, rte_mem_event_callback_t clb, void * arg)
The function you use to register callbacks for memory events π₯
Note β callbacks will happen while the memory hotplug subsystem is write-locked, which means some functions (e.g.rte_memseg_walk()) will cause a deadlock when called from within such callbacks. Do not do that. π Also, mem event callbacks not being supported is an expected error condition, so your user code needs to handle this situation. In those cases, the return value will be-1, andrte_errnowill be set toENOTSUP. Not a bug, just a vibe π
π Parameters π
nameβ Name associated with specified callback to be added to the list.clbβ Callback function pointer.argβ Argument to pass to the callback.
πΈ Returns πΈ
0 on successful callback register, -1 on unsuccessful callback register, with rte_errno value indicating reason for failure.
π¦ int rte_mem_event_callback_unregister (const char * name, void * arg) π¦
Function used to unregister callbacks for memory events.
π Parameters π
nameβ Name associated with specified callback to be removed from the list.argβ Argument to look for among callbacks with specified callback name.
πΈ Returns πΈ
0 on successful callback unregister, -1 on unsuccessful callback unregister, with rte_errno value indicating reason for failure.
π int rte_mem_alloc_validator_register (const char * name, rte_mem_alloc_validator_t clb, int socket_id, size_t limit) π
Register validator callback for memory allocations. Callbacks registered by this function will be called right before memory allocator is about to trigger allocation of more pages from the system if said allocation will bring total memory usage above specified limit on specified socket. User will be able to cancel pending allocation if callback returns -1.
Note β callbacks will happen while memory hotplug subsystem is write-locked, therefore some functions (e.g. rte_memseg_walk()) will cause a deadlock when called from within such callbacks.
Note β validator callbacks not being supported is an expected error condition, so user code needs to handle this situation. In these cases, return value will be-1, andrte_errnowill be set toENOTSUP.
π Parameters π
nameβ Name associated with specified callback to be added to the list.clbβ Callback function pointer.socket_idβ Socket ID on which to watch for allocations.limitβ Limit above which to trigger callbacks.
πΈ Returns πΈ
0 on successful callback register, -1 on unsuccessful callback register, with rte_errno value indicating reason for failure.
π¦ int rte_mem_alloc_validator_unregister (const char * name, int socket_id) π¦
Unregister validator callback for memory allocations.
π Parameters π
nameβ Name associated with specified callback to be removed from the list.socket_idβ Socket ID on which to watch for allocations.
πΈ Returns πΈ
0 on successful callback unregister, -1 on unsuccessful callback unregister, with rte_errno value indicating reason for failure.
β¨ __rte_experimental void rte_memzero_explicit (void * dst, size_t sz) β¨
Warning β EXPERIMENTAL: this API may change without prior notice.
Fill memory with zero's (e.g. sensitive keys). Normally using memset() is fine, but in cases where clearing out local data before going out of scope is required, use rte_memzero_explicit() instead to prevent the compiler from optimizing away the zeroing operation.
π Parameters π
dstβ Target buffer.szβ Number of bytes to fill.
π₯ __rte_experimental bool rte_memeq_timingsafe (const void * a, const void * b, size_t n) [inline], [static] π₯
Warning β EXPERIMENTAL: this API may change without prior notice.
Timing-safe memory equality comparison.
This function compares two memory regions in constant time, making it resistant to timing side-channel attacks. The execution time depends only on the length parameter, not on the actual data values being compared.
This is particularly important for cryptographic operations where timing differences could leak information about secret keys, passwords, or other sensitive data.
π Parameters π
aβ Pointer to the first memory region to compare.bβ Pointer to the second memory region to compare.nβ Number of bytes to compare.
πΈ Returns πΈ
true if the memory regions are identical, false if they differ.
Definition at line 775 of file rte_memory.h.
π Author π
Generated automatically by Doxygen for DPDK from the source code.
And thatβs the whole page, bestie: it was generated automatically from source, and the footerβs source/version/date line stamps it as DPDK Version 26.03.0, page rte_memory.h(3) β iconic auto-doc energy, no cap. π
β¨
π¦ where this page comes from
- nixos 26.05: dpdk 26.03
- nixpkgs unstable: dpdk 26.03
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms