#include <stdint.h>
#include <stddef.h>
#include <stdio.h>
#include <rte_common.h>
#include <rte_compat.h>
#include <rte_config.h>
#include <rte_fbarray.h>

Data Structures
struct	rte_memseg_list

Macros
#define	SOCKET_ID_ANY -1

#define	RTE_MEMSEG_FLAG_DO_NOT_FREE (1 << 0)

#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)

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

int	rte_mem_alloc_validator_unregister (const char *name, int socket_id)
	Unregister validator callback for memory allocations. More...

Detailed Description

Memory-related RTE API.

Definition in file rte_memory.h.

Macro Definition Documentation

◆ SOCKET_ID_ANY

#define SOCKET_ID_ANY -1

Any NUMA socket.

Examples:: examples/ip_fragmentation/main.c, examples/ip_pipeline/link.c, examples/ip_reassembly/main.c, examples/l3fwd-graph/main.c, and examples/pipeline/obj.c.

Definition at line 38 of file rte_memory.h.

◆ RTE_MEMSEG_FLAG_DO_NOT_FREE

#define RTE_MEMSEG_FLAG_DO_NOT_FREE (1 << 0)

Physical memory segment descriptor.Prevent this segment from being freed back to the OS.

Definition at line 43 of file rte_memory.h.

◆ RTE_MEM_EVENT_CALLBACK_NAME_LEN

#define RTE_MEM_EVENT_CALLBACK_NAME_LEN 64

maximum length of callback name

Definition at line 606 of file rte_memory.h.

◆ RTE_MEM_ALLOC_VALIDATOR_NAME_LEN

#define RTE_MEM_ALLOC_VALIDATOR_NAME_LEN 64

maximum length of alloc validator name

Definition at line 662 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 0 will continue walk Returning 1 will stop the walk Returning -1 will stop the walk and report error

Definition at line 165 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 0 will continue walk Returning 1 will stop the walk Returning -1 will stop the walk and report error

Definition at line 177 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 0 will continue walk Returning 1 will stop the walk Returning -1 will stop the walk and report error

Definition at line 188 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 612 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 0 will allow allocation attempt to continue. Returning -1 will prevent allocation from succeeding.

Definition at line 670 of file rte_memory.h.

Enumeration Type Documentation

◆ rte_mem_event

enum rte_mem_event

Enum indicating which kind of memory event has happened. Used by callbacks to distinguish between memory allocations and deallocations.

Enumerator
RTE_MEM_EVENT_ALLOC	Allocation event.
RTE_MEM_EVENT_FREE	Deallocation event.

Definition at line 602 of file rte_memory.h.

Function Documentation

◆ rte_mem_lock_page()

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.

◆ rte_mem_virt2phy()

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

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.

◆ rte_mem_iova2virt()

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

◆ rte_mem_virt2memseg()

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.

◆ rte_mem_virt2memseg_list()

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.

◆ rte_memseg_walk()

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: 0 if walked over the entire list 1 if stopped by the user -1 if user function reported error

◆ rte_memseg_contig_walk()

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: 0 if walked over the entire list 1 if stopped by the user -1 if user function reported error

◆ rte_memseg_list_walk()

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: 0 if walked over the entire list 1 if stopped by the user -1 if user function reported error

◆ rte_memseg_walk_thread_unsafe()

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

Returns: 0 if walked over the entire list 1 if stopped by the user -1 if user function reported error

◆ rte_memseg_contig_walk_thread_unsafe()

int rte_memseg_contig_walk_thread_unsafe	(	rte_memseg_contig_walk_t	func,
		void *	arg
	)

Walk each VA-contiguous area 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

Returns: 0 if walked over the entire list 1 if stopped by the user -1 if user function reported error

◆ rte_memseg_list_walk_thread_unsafe()

int rte_memseg_list_walk_thread_unsafe	(	rte_memseg_list_walk_t	func,
		void *	arg
	)

Walk each allocated memseg list 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

Returns: 0 if walked over the entire list 1 if stopped by the user -1 if user function reported error

◆ rte_memseg_get_fd()

int rte_memseg_get_fd ( const struct rte_memseg * ms )

Return file descriptor associated with a particular memseg (if available).

Note: This function read-locks the memory hotplug subsystem, and thus cannot be used within memory-related callback functions.; This returns an internal file descriptor. Performing any operations on this file descriptor is inherently dangerous, so it should be treated as read-only for all intents and purposes.

Parameters

ms	A pointer to memseg for which to get file descriptor.

Returns

Valid file descriptor in case of success. -1 in case of error, with rte_errno set to the following values:

EINVAL - ms pointer was NULL or did not point to a valid memseg
ENODEV - ms fd is not available
ENOENT - ms is an unused segment
ENOTSUP - segment fd's are not supported

◆ rte_memseg_get_fd_thread_unsafe()

int rte_memseg_get_fd_thread_unsafe ( const struct rte_memseg * ms )

Return file descriptor associated with a particular memseg (if available).

Note: This function does not perform any locking, and is only safe to call from within memory-related callback functions.; This returns an internal file descriptor. Performing any operations on this file descriptor is inherently dangerous, so it should be treated as read-only for all intents and purposes.

Parameters

ms	A pointer to memseg for which to get file descriptor.

Returns

Valid file descriptor in case of success. -1 in case of error, with rte_errno set to the following values:

EINVAL - ms pointer was NULL or did not point to a valid memseg
ENODEV - ms fd is not available
ENOENT - ms is an unused segment
ENOTSUP - segment fd's are not supported

◆ rte_memseg_get_fd_offset()

int rte_memseg_get_fd_offset	(	const struct rte_memseg *	ms,
		size_t *	offset
	)

Get offset into segment file descriptor associated with a particular memseg (if available).

Note: This function read-locks the memory hotplug subsystem, and thus cannot be used within memory-related callback functions.

Parameters

ms	A pointer to memseg for which to get file descriptor.
offset	A pointer to offset value where the result will be stored.

Returns

Valid file descriptor in case of success. -1 in case of error, with rte_errno set to the following values:

EINVAL - ms pointer was NULL or did not point to a valid memseg
EINVAL - offset pointer was NULL
ENODEV - ms fd is not available
ENOENT - ms is an unused segment
ENOTSUP - segment fd's are not supported

◆ rte_memseg_get_fd_offset_thread_unsafe()

int rte_memseg_get_fd_offset_thread_unsafe	(	const struct rte_memseg *	ms,
		size_t *	offset
	)

Get offset into segment file descriptor associated with a particular memseg (if available).

Note: This function does not perform any locking, and is only safe to call from within memory-related callback functions.

Parameters

ms	A pointer to memseg for which to get file descriptor.
offset	A pointer to offset value where the result will be stored.

Returns

Valid file descriptor in case of success. -1 in case of error, with rte_errno set to the following values:

EINVAL - ms pointer was NULL or did not point to a valid memseg
EINVAL - offset pointer was NULL
ENODEV - ms fd is not available
ENOENT - ms is an unused segment
ENOTSUP - segment fd's are not supported

◆ rte_extmem_register()

int rte_extmem_register	(	void *	va_addr,
		size_t	len,
		rte_iova_t	iova_addrs[],
		unsigned int	n_pages,
		size_t	page_sz
	)

Register external memory chunk with DPDK.

Note: Using this API is mutually exclusive with rte_malloc family of API's.; This API will not perform any DMA mapping. It is expected that user will do that themselves.; Before accessing this memory in other processes, it needs to be attached in each of those processes by calling rte_extmem_attach in each other process.

Parameters

va_addr	Start of virtual area to register. Must be aligned by `page_sz`.
len	Length of virtual area to register. 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 EEXIST - memory chunk is already registered ENOSPC - no more space in internal config to store a new memory chunk

◆ rte_extmem_unregister()

int rte_extmem_unregister	(	void *	va_addr,
		size_t	len
	)

Unregister external memory chunk with DPDK.

Note: Using this API is mutually exclusive with rte_malloc family of API's.; This API will not perform any DMA unmapping. It is expected that user will do that themselves.; Before calling this function, all other processes must call rte_extmem_detach to detach from the memory area.

Parameters

va_addr	Start of virtual area to unregister
len	Length of virtual area to unregister

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 ENOENT - memory chunk was not found

◆ rte_extmem_attach()

int rte_extmem_attach	(	void *	va_addr,
		size_t	len
	)

Attach to external memory chunk registered in another process.

Note: Using this API is mutually exclusive with rte_malloc family of API's.; This API will not perform any DMA mapping. It is expected that user will do that themselves.

Parameters

va_addr	Start of virtual area to register
len	Length of virtual area to register

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 ENOENT - memory chunk was not found

◆ rte_extmem_detach()

int rte_extmem_detach	(	void *	va_addr,
		size_t	len
	)

Detach from external memory chunk registered in another process.

Note: Using this API is mutually exclusive with rte_malloc family of API's.; This API will not perform any DMA unmapping. It is expected that user will do that themselves.

Parameters

va_addr	Start of virtual area to unregister
len	Length of virtual area to unregister

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 ENOENT - memory chunk was not found

◆ rte_dump_physmem_layout()

void rte_dump_physmem_layout ( FILE * f )

Dump the physical memory layout to a file.

Note: This function read-locks the memory hotplug subsystem, and thus cannot be used within memory-related callback functions.

Parameters

f	A pointer to a file for output

◆ rte_eal_get_physmem_size()

uint64_t rte_eal_get_physmem_size ( void )

Get the total amount of available physical memory.

Note: This function read-locks the memory hotplug subsystem, and thus cannot be used within memory-related callback functions.

Returns: The total amount of available physical memory in bytes.

◆ rte_memory_get_nchannel()

unsigned rte_memory_get_nchannel ( void )

Get the number of memory channels.

Returns: The number of memory channels on the system. The value is 0 if unknown or not the same on all devices.

◆ rte_memory_get_nrank()

unsigned rte_memory_get_nrank ( void )

Get the number of memory ranks.

Returns: The number of memory ranks on the system. The value is 0 if unknown or not the same on all devices.

◆ rte_mem_check_dma_mask()

int rte_mem_check_dma_mask ( uint8_t maskbits )

Check if all currently allocated memory segments are compliant with supplied DMA address width.

Parameters

maskbits Address width to check against.

◆ rte_mem_check_dma_mask_thread_unsafe()

int rte_mem_check_dma_mask_thread_unsafe ( uint8_t maskbits )

Check if all currently allocated memory segments are compliant with supplied DMA address width. This function will use rte_memseg_walk_thread_unsafe instead of rte_memseg_walk implying memory_hotplug_lock will not be acquired avoiding deadlock during memory initialization.

This function is just for EAL core memory internal use. Drivers should use the previous rte_mem_check_dma_mask.

Parameters

maskbits Address width to check against.

◆ rte_mem_set_dma_mask()

void rte_mem_set_dma_mask ( uint8_t maskbits )

Set dma mask to use once memory initialization is done. Previous functions rte_mem_check_dma_mask and rte_mem_check_dma_mask_thread_unsafe can not be used safely until memory has been initialized.

◆ rte_eal_using_phys_addrs()

int rte_eal_using_phys_addrs ( void )

Drivers based on uio will not load unless physical addresses are obtainable. It is 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 using DMA addresses through an IOMMU.

◆ rte_mem_event_callback_register()

int rte_mem_event_callback_register	(	const char *	name,
		rte_mem_event_callback_t	clb,
		void *	arg
	)

Function used to register callbacks for memory events.

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.; mem event 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, and rte_errno will be set to ENOTSUP.

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.

◆ rte_mem_event_callback_unregister()

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.

◆ rte_mem_alloc_validator_register()

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.; 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, and rte_errno will be set to ENOTSUP.

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.

◆ rte_mem_alloc_validator_unregister()

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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SOCKET_ID_ANY

◆ RTE_MEMSEG_FLAG_DO_NOT_FREE

◆ RTE_MEM_EVENT_CALLBACK_NAME_LEN

◆ RTE_MEM_ALLOC_VALIDATOR_NAME_LEN

Typedef Documentation

◆ rte_memseg_walk_t

◆ rte_memseg_contig_walk_t

◆ rte_memseg_list_walk_t

◆ rte_mem_event_callback_t

◆ rte_mem_alloc_validator_t

Enumeration Type Documentation

◆ rte_mem_event

Function Documentation

◆ rte_mem_lock_page()

◆ rte_mem_virt2phy()

◆ rte_mem_virt2iova()

◆ rte_mem_iova2virt()

◆ rte_mem_virt2memseg()

◆ rte_mem_virt2memseg_list()

◆ rte_memseg_walk()

◆ rte_memseg_contig_walk()

◆ rte_memseg_list_walk()

◆ rte_memseg_walk_thread_unsafe()

◆ rte_memseg_contig_walk_thread_unsafe()

◆ rte_memseg_list_walk_thread_unsafe()

◆ rte_memseg_get_fd()

◆ rte_memseg_get_fd_thread_unsafe()

◆ rte_memseg_get_fd_offset()

◆ rte_memseg_get_fd_offset_thread_unsafe()

◆ rte_extmem_register()

◆ rte_extmem_unregister()

◆ rte_extmem_attach()

◆ rte_extmem_detach()

◆ rte_dump_physmem_layout()

◆ rte_eal_get_physmem_size()

◆ rte_memory_get_nchannel()

◆ rte_memory_get_nrank()

◆ rte_mem_check_dma_mask()

◆ rte_mem_check_dma_mask_thread_unsafe()

◆ rte_mem_set_dma_mask()

◆ rte_eal_using_phys_addrs()

◆ rte_mem_event_callback_register()

◆ rte_mem_event_callback_unregister()

◆ rte_mem_alloc_validator_register()

◆ rte_mem_alloc_validator_unregister()