DPDK: Data Plane Development Kit

18.08.0-rc1
rte_memory.h File Reference
#include <stdint.h>
#include <stddef.h>
#include <stdio.h>
#include <rte_common.h>
#include <rte_compat.h>
#include <rte_config.h>

Go to the source code of this file.

Macros

#define SOCKET_ID_ANY   -1
#define RTE_CACHE_LINE_MASK   (RTE_CACHE_LINE_SIZE-1)
#define RTE_CACHE_LINE_ROUNDUP(size)   (RTE_CACHE_LINE_SIZE * ((size + RTE_CACHE_LINE_SIZE - 1) / RTE_CACHE_LINE_SIZE))
#define RTE_CACHE_LINE_MIN_SIZE   64
#define __rte_cache_aligned   __rte_aligned(RTE_CACHE_LINE_SIZE)
#define __rte_cache_min_aligned   __rte_aligned(RTE_CACHE_LINE_MIN_SIZE)
#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 uint64_t phys_addr_t
typedef uint64_t rte_iova_t
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)
__rte_experimental void * rte_mem_iova2virt (rte_iova_t iova)
__rte_experimental struct
rte_memseg * 
rte_mem_virt2memseg (const void *virt, const struct rte_memseg_list *msl)
__rte_experimental struct
rte_memseg_list
rte_mem_virt2memseg_list (const void *virt)
int __rte_experimental rte_memseg_walk (rte_memseg_walk_t func, void *arg)
int __rte_experimental rte_memseg_contig_walk (rte_memseg_contig_walk_t func, void *arg)
int __rte_experimental rte_memseg_list_walk (rte_memseg_list_walk_t func, void *arg)
int __rte_experimental rte_memseg_walk_thread_unsafe (rte_memseg_walk_t func, void *arg)
int __rte_experimental rte_memseg_contig_walk_thread_unsafe (rte_memseg_contig_walk_t func, void *arg)
int __rte_experimental rte_memseg_list_walk_thread_unsafe (rte_memseg_list_walk_t func, void *arg)
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_eal_using_phys_addrs (void)
int __rte_experimental rte_mem_event_callback_register (const char *name, rte_mem_event_callback_t clb, void *arg)
int __rte_experimental rte_mem_event_callback_unregister (const char *name, void *arg)
int __rte_experimental 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_experimental rte_mem_alloc_validator_unregister (const char *name, int socket_id)
 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
#define RTE_CACHE_LINE_MASK   (RTE_CACHE_LINE_SIZE-1)

Cache line mask.

Definition at line 44 of file rte_memory.h.

#define RTE_CACHE_LINE_ROUNDUP (   size)    (RTE_CACHE_LINE_SIZE * ((size + RTE_CACHE_LINE_SIZE - 1) / RTE_CACHE_LINE_SIZE))

Return the first cache-aligned value greater or equal to size. Cache line size in terms of log2

Examples:
examples/flow_classify/flow_classify.c.

Definition at line 46 of file rte_memory.h.

#define RTE_CACHE_LINE_MIN_SIZE   64

Minimum Cache line size.

Definition at line 61 of file rte_memory.h.

struct rte_eth_txq_info __rte_cache_min_aligned   __rte_aligned(RTE_CACHE_LINE_MIN_SIZE)

Force minimum cache line alignment.

Definition at line 71 of file rte_memory.h.

#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 88 of file rte_memory.h.

#define RTE_MEM_EVENT_CALLBACK_NAME_LEN   64

maximum length of callback name

Definition at line 382 of file rte_memory.h.

#define RTE_MEM_ALLOC_VALIDATOR_NAME_LEN   64

maximum length of alloc validator name

Definition at line 438 of file rte_memory.h.

Typedef Documentation

typedef uint64_t phys_addr_t

Physical address.

Definition at line 73 of file rte_memory.h.

typedef uint64_t rte_iova_t

IO virtual address type. When the physical addressing mode (IOVA as PA) is in use, the translation from an IO virtual address (IOVA) to a physical address is a direct mapping, i.e. the same value. Otherwise, in virtual mode (IOVA as VA), an IOMMU may do the translation.

Definition at line 82 of file rte_memory.h.

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 188 of file rte_memory.h.

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 are 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 200 of file rte_memory.h.

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 211 of file rte_memory.h.

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 388 of file rte_memory.h.

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 446 of file rte_memory.h.

Enumeration Type Documentation

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 378 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
virtThe 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
virtThe 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.

Parameters
virtThe virtual address.
Returns
The IO address or RTE_BAD_IOVA on error.
__rte_experimental 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
iovaThe iova address.
Returns
Virtual address corresponding to iova address (or NULL if address does not exist within DPDK memory map).
__rte_experimental struct rte_memseg* rte_mem_virt2memseg ( const void *  virt,
const struct rte_memseg_list msl 
)
read

Get memseg to which a particular virtual address belongs.

Parameters
virtThe virtual address.
mslThe memseg list in which to look up based on virt address (can be NULL).
Returns
Memseg pointer on success, or NULL on error.
__rte_experimental struct rte_memseg_list* rte_mem_virt2memseg_list ( const void *  virt)
read

Get memseg list corresponding to virtual memory address.

Parameters
virtThe virtual address.
Returns
Memseg list to which this virtual address belongs to.
int __rte_experimental 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.
Parameters
funcIterator function
argArgument passed to iterator
Returns
0 if walked over the entire list 1 if stopped by the user -1 if user function reported error
int __rte_experimental 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.
Parameters
funcIterator function
argArgument passed to iterator
Returns
0 if walked over the entire list 1 if stopped by the user -1 if user function reported error
int __rte_experimental 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.
Parameters
funcIterator function
argArgument passed to iterator
Returns
0 if walked over the entire list 1 if stopped by the user -1 if user function reported error
int __rte_experimental 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
funcIterator function
argArgument passed to iterator
Returns
0 if walked over the entire list 1 if stopped by the user -1 if user function reported error
int __rte_experimental 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
funcIterator function
argArgument passed to iterator
Returns
0 if walked over the entire list 1 if stopped by the user -1 if user function reported error
int __rte_experimental 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
funcIterator function
argArgument passed to iterator
Returns
0 if walked over the entire list 1 if stopped by the user -1 if user function reported error
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
fA pointer to a file for output
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.
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.
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.
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.
int __rte_experimental 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
nameName associated with specified callback to be added to the list.
clbCallback function pointer.
argArgument 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_experimental rte_mem_event_callback_unregister ( const char *  name,
void *  arg 
)

Function used to unregister callbacks for memory events.

Parameters
nameName associated with specified callback to be removed from the list.
argArgument 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_experimental 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
nameName associated with specified callback to be added to the list.
clbCallback function pointer.
socket_idSocket ID on which to watch for allocations.
limitLimit 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_experimental rte_mem_alloc_validator_unregister ( const char *  name,
int  socket_id 
)

Unregister validator callback for memory allocations.

Parameters
nameName associated with specified callback to be removed from the list.
socket_idSocket 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.