#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <errno.h>
#include <inttypes.h>
#include <sys/queue.h>
#include <rte_spinlock.h>
#include <rte_log.h>
#include <rte_debug.h>
#include <rte_lcore.h>
#include <rte_memory.h>
#include <rte_branch_prediction.h>
#include <rte_ring.h>
#include <rte_memcpy.h>
#include <rte_common.h>

Data Structures
struct	rte_mempool_cache
struct	rte_mempool_objsz
struct	rte_mempool_objhdr
struct	rte_mempool_memhdr
struct	rte_mempool
struct	rte_mempool_ops
struct	rte_mempool_ops_table

Macros
#define	RTE_MEMPOOL_HEADER_COOKIE1 0xbadbadbadadd2e55ULL
#define	RTE_MEMPOOL_HEADER_COOKIE2 0xf2eef2eedadd2e55ULL
#define	RTE_MEMPOOL_TRAILER_COOKIE 0xadd2e55badbadbadULL
#define	MEMPOOL_PG_NUM_DEFAULT 1
#define	MEMPOOL_F_NO_SPREAD 0x0001
#define	MEMPOOL_F_NO_CACHE_ALIGN 0x0002
#define	MEMPOOL_F_SP_PUT 0x0004
#define	MEMPOOL_F_SC_GET 0x0008
#define	MEMPOOL_F_POOL_CREATED 0x0010
#define	MEMPOOL_F_NO_PHYS_CONTIG 0x0020
#define	MEMPOOL_HEADER_SIZE(mp, cs)
#define	RTE_MEMPOOL_OPS_NAMESIZE 32
#define	RTE_MEMPOOL_MAX_OPS_IDX 16
#define	MEMPOOL_REGISTER_OPS(ops)

Typedefs
typedef void(	rte_mempool_memchunk_free_cb_t )(struct rte_mempool_memhdr memhdr, void opaque)
typedef int(*	rte_mempool_alloc_t )(struct rte_mempool *mp)
typedef void(*	rte_mempool_free_t )(struct rte_mempool *mp)
typedef int(*	rte_mempool_enqueue_t )(struct rte_mempool mp, void const *obj_table, unsigned int n)
typedef int(*	rte_mempool_dequeue_t )(struct rte_mempool mp, void *obj_table, unsigned int n)
typedef unsigned(*	rte_mempool_get_count )(const struct rte_mempool *mp)
typedef void(	rte_mempool_obj_cb_t )(struct rte_mempool mp, void opaque, void *obj, unsigned obj_idx)
typedef void(	rte_mempool_mem_cb_t )(struct rte_mempool mp, void opaque, struct rte_mempool_memhdr *memhdr, unsigned mem_idx)
typedef void(	rte_mempool_ctor_t )(struct rte_mempool , void )

Functions
	STAILQ_HEAD (rte_mempool_objhdr_list, rte_mempool_objhdr)
	STAILQ_HEAD (rte_mempool_memhdr_list, rte_mempool_memhdr)
static struct rte_mempool *	rte_mempool_from_obj (void *obj)
int	rte_mempool_set_ops_byname (struct rte_mempool mp, const char name, void *pool_config)
int	rte_mempool_register_ops (const struct rte_mempool_ops *ops)
struct rte_mempool *	rte_mempool_create (const char name, unsigned n, unsigned elt_size, unsigned cache_size, unsigned private_data_size, rte_mempool_ctor_t mp_init, void mp_init_arg, rte_mempool_obj_cb_t obj_init, void *obj_init_arg, int socket_id, unsigned flags)
struct rte_mempool *	rte_mempool_xmem_create (const char name, unsigned n, unsigned elt_size, unsigned cache_size, unsigned private_data_size, rte_mempool_ctor_t mp_init, void mp_init_arg, rte_mempool_obj_cb_t obj_init, void obj_init_arg, int socket_id, unsigned flags, void vaddr, const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift)
struct rte_mempool *	rte_mempool_create_empty (const char *name, unsigned n, unsigned elt_size, unsigned cache_size, unsigned private_data_size, int socket_id, unsigned flags)
void	rte_mempool_free (struct rte_mempool *mp)
int	rte_mempool_populate_phys (struct rte_mempool mp, char vaddr, phys_addr_t paddr, size_t len, rte_mempool_memchunk_free_cb_t free_cb, void opaque)
int	rte_mempool_populate_phys_tab (struct rte_mempool mp, char vaddr, const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift, rte_mempool_memchunk_free_cb_t free_cb, void opaque)
int	rte_mempool_populate_virt (struct rte_mempool mp, char addr, size_t len, size_t pg_sz, rte_mempool_memchunk_free_cb_t free_cb, void opaque)
int	rte_mempool_populate_default (struct rte_mempool *mp)
int	rte_mempool_populate_anon (struct rte_mempool *mp)
uint32_t	rte_mempool_obj_iter (struct rte_mempool mp, rte_mempool_obj_cb_t obj_cb, void *obj_cb_arg)
uint32_t	rte_mempool_mem_iter (struct rte_mempool mp, rte_mempool_mem_cb_t mem_cb, void *mem_cb_arg)
void	rte_mempool_dump (FILE f, struct rte_mempool mp)
struct rte_mempool_cache *	rte_mempool_cache_create (uint32_t size, int socket_id)
void	rte_mempool_cache_free (struct rte_mempool_cache *cache)
static void	rte_mempool_cache_flush (struct rte_mempool_cache cache, struct rte_mempool mp)
static struct rte_mempool_cache *	rte_mempool_default_cache (struct rte_mempool *mp, unsigned lcore_id)
static void	rte_mempool_generic_put (struct rte_mempool mp, void const obj_table, unsigned n, struct rte_mempool_cache cache, __rte_unused int flags)
static __rte_deprecated void	rte_mempool_mp_put_bulk (struct rte_mempool mp, void const *obj_table, unsigned n)
static __rte_deprecated void	rte_mempool_sp_put_bulk (struct rte_mempool mp, void const *obj_table, unsigned n)
static void	rte_mempool_put_bulk (struct rte_mempool mp, void const *obj_table, unsigned n)
static __rte_deprecated void	rte_mempool_mp_put (struct rte_mempool mp, void obj)
static __rte_deprecated void	rte_mempool_sp_put (struct rte_mempool mp, void obj)
static void	rte_mempool_put (struct rte_mempool mp, void obj)
static int	rte_mempool_generic_get (struct rte_mempool mp, void obj_table, unsigned n, struct rte_mempool_cache cache, __rte_unused int flags)
static __rte_deprecated int	rte_mempool_mc_get_bulk (struct rte_mempool mp, void *obj_table, unsigned n)
static __rte_deprecated int	rte_mempool_sc_get_bulk (struct rte_mempool mp, void *obj_table, unsigned n)
static int	rte_mempool_get_bulk (struct rte_mempool mp, void *obj_table, unsigned n)
static __rte_deprecated int	rte_mempool_mc_get (struct rte_mempool mp, void *obj_p)
static __rte_deprecated int	rte_mempool_sc_get (struct rte_mempool mp, void *obj_p)
static int	rte_mempool_get (struct rte_mempool mp, void *obj_p)
unsigned int	rte_mempool_avail_count (const struct rte_mempool *mp)
__rte_deprecated unsigned	rte_mempool_count (const struct rte_mempool *mp)
unsigned int	rte_mempool_in_use_count (const struct rte_mempool *mp)
static __rte_deprecated unsigned	rte_mempool_free_count (const struct rte_mempool *mp)
static int	rte_mempool_full (const struct rte_mempool *mp)
static int	rte_mempool_empty (const struct rte_mempool *mp)
static phys_addr_t	rte_mempool_virt2phy (__rte_unused const struct rte_mempool mp, const void elt)
void	rte_mempool_audit (struct rte_mempool *mp)
static void *	rte_mempool_get_priv (struct rte_mempool *mp)
void	rte_mempool_list_dump (FILE *f)
struct rte_mempool *	rte_mempool_lookup (const char *name)
uint32_t	rte_mempool_calc_obj_size (uint32_t elt_size, uint32_t flags, struct rte_mempool_objsz *sz)
size_t	rte_mempool_xmem_size (uint32_t elt_num, size_t total_elt_sz, uint32_t pg_shift)
ssize_t	rte_mempool_xmem_usage (void *vaddr, uint32_t elt_num, size_t total_elt_sz, const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift)
void	rte_mempool_walk (void(func)(struct rte_mempool , void arg), void arg)

Variables
struct rte_mempool_ops_table	rte_mempool_ops_table

Detailed Description

RTE Mempool.

A memory pool is an allocator of fixed-size object. It is identified by its name, and uses a ring to store free objects. It provides some other optional services, like a per-core object cache, and an alignment helper to ensure that objects are padded to spread them equally on all RAM channels, ranks, and so on.

Objects owned by a mempool should never be added in another mempool. When an object is freed using rte_mempool_put() or equivalent, the object data is not modified; the user can save some meta-data in the object data and retrieve them when allocating a new object.

Note: the mempool implementation is not preemptable. A lcore must not be interrupted by another task that uses the same mempool (because it uses a ring which is not preemptable). Also, mempool functions must not be used outside the DPDK environment: for example, in linuxapp environment, a thread that is not created by the EAL must not use mempools. This is due to the per-lcore cache that won't work as rte_lcore_id() will not return a correct value.

Definition in file rte_mempool.h.

Macro Definition Documentation

#define RTE_MEMPOOL_HEADER_COOKIE1 0xbadbadbadadd2e55ULL

Header cookie.

Definition at line 84 of file rte_mempool.h.

#define RTE_MEMPOOL_HEADER_COOKIE2 0xf2eef2eedadd2e55ULL

Header cookie.

Definition at line 85 of file rte_mempool.h.

#define RTE_MEMPOOL_TRAILER_COOKIE 0xadd2e55badbadbadULL

Trailer cookie.

Definition at line 86 of file rte_mempool.h.

#define MEMPOOL_PG_NUM_DEFAULT 1

Mempool over one chunk of physically continuous memory

Definition at line 138 of file rte_mempool.h.

#define MEMPOOL_F_NO_SPREAD 0x0001

Do not spread among memory channels.

Definition at line 260 of file rte_mempool.h.

#define MEMPOOL_F_NO_CACHE_ALIGN 0x0002

Do not align objs on cache lines.

Definition at line 261 of file rte_mempool.h.

#define MEMPOOL_F_SP_PUT 0x0004

Default put is "single-producer".

Examples:: examples/ip_reassembly/main.c.

Definition at line 262 of file rte_mempool.h.

#define MEMPOOL_F_SC_GET 0x0008

Default get is "single-consumer".

Examples:: examples/ip_reassembly/main.c.

Definition at line 263 of file rte_mempool.h.

#define MEMPOOL_F_POOL_CREATED 0x0010

Internal: pool is created.

Definition at line 264 of file rte_mempool.h.

#define MEMPOOL_F_NO_PHYS_CONTIG 0x0020

Don't need physically contiguous objs.

Definition at line 265 of file rte_mempool.h.

#define MEMPOOL_HEADER_SIZE	(	mp,
		cs
	)

Value:

(sizeof(*(mp)) + (((cs) == 0) ? 0 : \

(sizeof(struct rte_mempool_cache) * RTE_MAX_LCORE)))

Calculate the size of the mempool header.

Parameters

mp	Pointer to the memory pool.
cs	Size of the per-lcore cache.

Definition at line 297 of file rte_mempool.h.

#define RTE_MEMPOOL_OPS_NAMESIZE 32

Max length of ops struct name.

Definition at line 354 of file rte_mempool.h.

#define RTE_MEMPOOL_MAX_OPS_IDX 16

Max registered ops structs

Definition at line 400 of file rte_mempool.h.

#define MEMPOOL_REGISTER_OPS ( ops )

Value:

void mp_hdlr_init_##ops(void);                                  \
        void __attribute__((constructor, used)) mp_hdlr_init_##ops(void)\
        {                                                               \
                rte_mempool_register_ops(&ops);                 \
        }

Macro to statically register the ops of a mempool handler. Note that the rte_mempool_register_ops fails silently here when more than RTE_MEMPOOL_MAX_OPS_IDX is registered.

Definition at line 556 of file rte_mempool.h.

Typedef Documentation

typedef void( rte_mempool_memchunk_free_cb_t)(struct rte_mempool_memhdr *memhdr, void *opaque)

Callback used to free a memory chunk

Definition at line 191 of file rte_mempool.h.

typedef int(* rte_mempool_alloc_t)(struct rte_mempool *mp)

Prototype for implementation specific data provisioning function.

The function should provide the implementation specific memory for use by the other mempool ops functions in a given mempool ops struct. E.g. the default ops provides an instance of the rte_ring for this purpose. it will most likely point to a different type of data structure, and will be transparent to the application programmer. This function should set mp->pool_data.

Definition at line 366 of file rte_mempool.h.

typedef void(* rte_mempool_free_t)(struct rte_mempool *mp)

Free the opaque private data pointed to by mp->pool_data pointer.

Definition at line 371 of file rte_mempool.h.

typedef int(* rte_mempool_enqueue_t)(struct rte_mempool *mp, void *const *obj_table, unsigned int n)

Enqueue an object into the external pool.

Definition at line 376 of file rte_mempool.h.

typedef int(* rte_mempool_dequeue_t)(struct rte_mempool *mp, void **obj_table, unsigned int n)

Dequeue an object from the external pool.

Definition at line 382 of file rte_mempool.h.

typedef unsigned(* rte_mempool_get_count)(const struct rte_mempool *mp)

Return the number of available objects in the external pool.

Definition at line 388 of file rte_mempool.h.

typedef void( rte_mempool_obj_cb_t)(struct rte_mempool *mp, void *opaque, void *obj, unsigned obj_idx)

An object callback function for mempool.

Used by rte_mempool_create() and rte_mempool_obj_iter().

Definition at line 568 of file rte_mempool.h.

typedef void( rte_mempool_mem_cb_t)(struct rte_mempool *mp, void *opaque, struct rte_mempool_memhdr *memhdr, unsigned mem_idx)

A memory callback function for mempool.

Used by rte_mempool_mem_iter().

Definition at line 577 of file rte_mempool.h.

typedef void( rte_mempool_ctor_t)(struct rte_mempool *, void *)

A mempool constructor callback function.

Arguments are the mempool and the opaque pointer given by the user in rte_mempool_create().

Definition at line 587 of file rte_mempool.h.

Function Documentation

STAILQ_HEAD	(	rte_mempool_objhdr_list	,
		rte_mempool_objhdr
	)

A list of object headers type

STAILQ_HEAD	(	rte_mempool_memhdr_list	,
		rte_mempool_memhdr
	)

A list of memory where objects are stored

static struct rte_mempool* rte_mempool_from_obj ( void * obj )

staticread

Return a pointer to the mempool owning this object.

Parameters

obj	An object that is owned by a pool. If this is not the case, the behavior is undefined.

Returns: A pointer to the mempool structure.

Definition at line 317 of file rte_mempool.h.

int rte_mempool_set_ops_byname	(	struct rte_mempool *	mp,
		const char *	name,
		void *	pool_config
	)

Set the ops of a mempool.

This can only be done on a mempool that is not populated, i.e. just after a call to rte_mempool_create_empty().

Parameters

mp	Pointer to the memory pool.
name	Name of the ops structure to use for this mempool.
pool_config	Opaque data that can be passed by the application to the ops functions.

Returns

0: Success; the mempool is now using the requested ops functions.
-EINVAL - Invalid ops struct name provided.
-EEXIST - mempool already has an ops struct assigned.

int rte_mempool_register_ops ( const struct rte_mempool_ops * ops )

Register mempool operations.

Parameters

ops	Pointer to an ops structure to register.

Returns

>=0: Success; return the index of the ops struct in the table.
-EINVAL - some missing callbacks while registering ops struct.
-ENOSPC - the maximum number of ops structs has been reached.

struct rte_mempool* rte_mempool_create	(	const char *	name,
		unsigned	n,
		unsigned	elt_size,
		unsigned	cache_size,
		unsigned	private_data_size,
		rte_mempool_ctor_t *	mp_init,
		void *	mp_init_arg,
		rte_mempool_obj_cb_t *	obj_init,
		void *	obj_init_arg,
		int	socket_id,
		unsigned	flags
	)

read

Create a new mempool named name in memory.

This function uses rte_memzone_reserve() to allocate memory. The pool contains n elements of elt_size. Its size is set to n.

Parameters

name	The name of the mempool.
n	The number of elements in the mempool. The optimum size (in terms of memory usage) for a mempool is when n is a power of two minus one: n = (2^q - 1).
elt_size	The size of each element.
cache_size	If cache_size is non-zero, the rte_mempool library will try to limit the accesses to the common lockless pool, by maintaining a per-lcore object cache. This argument must be lower or equal to CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE and n / 1.5. It is advised to choose cache_size to have "n modulo cache_size == 0": if this is not the case, some elements will always stay in the pool and will never be used. The access to the per-lcore table is of course faster than the multi-producer/consumer pool. The cache can be disabled if the cache_size argument is set to 0; it can be useful to avoid losing objects in cache.
private_data_size	The size of the private data appended after the mempool structure. This is useful for storing some private data after the mempool structure, as is done for rte_mbuf_pool for example.
mp_init	A function pointer that is called for initialization of the pool, before object initialization. The user can initialize the private data in this function if needed. This parameter can be NULL if not needed.
mp_init_arg	An opaque pointer to data that can be used in the mempool constructor function.
obj_init	A function pointer that is called for each object at initialization of the pool. The user can set some meta data in objects if needed. This parameter can be NULL if not needed. The obj_init() function takes the mempool pointer, the init_arg, the object pointer and the object number as parameters.
obj_init_arg	An opaque pointer to data that can be used as an argument for each call to the object constructor function.
socket_id	The socket_id argument is the socket identifier in the case of NUMA. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.
flags	The flags arguments is an OR of following flags: MEMPOOL_F_NO_SPREAD: By default, objects addresses are spread between channels in RAM: the pool allocator will add padding between objects depending on the hardware configuration. See Memory alignment constraints for details. If this flag is set, the allocator will just align them to a cache line. MEMPOOL_F_NO_CACHE_ALIGN: By default, the returned objects are cache-aligned. This flag removes this constraint, and no padding will be present between objects. This flag implies MEMPOOL_F_NO_SPREAD. MEMPOOL_F_SP_PUT: If this flag is set, the default behavior when using rte_mempool_put() or rte_mempool_put_bulk() is "single-producer". Otherwise, it is "multi-producers". MEMPOOL_F_SC_GET: If this flag is set, the default behavior when using rte_mempool_get() or rte_mempool_get_bulk() is "single-consumer". Otherwise, it is "multi-consumers". MEMPOOL_F_NO_PHYS_CONTIG: If set, allocated objects won't necessarilly be contiguous in physical memory.

Returns

The pointer to the new allocated mempool, on success. NULL on error with rte_errno set appropriately. Possible rte_errno values include:

E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
E_RTE_SECONDARY - function was called from a secondary process instance
EINVAL - cache size provided is too large
ENOSPC - the maximum number of memzones has already been allocated
EEXIST - a memzone with the same name already exists
ENOMEM - no appropriate memory area found in which to create memzone

Examples:: examples/ip_reassembly/main.c, examples/multi_process/simple_mp/main.c, and examples/tep_termination/main.c.

struct rte_mempool* rte_mempool_xmem_create	(	const char *	name,
		unsigned	n,
		unsigned	elt_size,
		unsigned	cache_size,
		unsigned	private_data_size,
		rte_mempool_ctor_t *	mp_init,
		void *	mp_init_arg,
		rte_mempool_obj_cb_t *	obj_init,
		void *	obj_init_arg,
		int	socket_id,
		unsigned	flags,
		void *	vaddr,
		const phys_addr_t	paddr[],
		uint32_t	pg_num,
		uint32_t	pg_shift
	)

read

Create a new mempool named name in memory.

The pool contains n elements of elt_size. Its size is set to n. This function uses memzone_reserve() to allocate the mempool header (and the objects if vaddr is NULL). Depending on the input parameters, mempool elements can be either allocated together with the mempool header, or an externally provided memory buffer could be used to store mempool objects. In later case, that external memory buffer can consist of set of disjoint physical pages.

Parameters

name	The name of the mempool.
n	The number of elements in the mempool. The optimum size (in terms of memory usage) for a mempool is when n is a power of two minus one: n = (2^q - 1).
elt_size	The size of each element.
cache_size	Size of the cache. See rte_mempool_create() for details.
private_data_size	The size of the private data appended after the mempool structure. This is useful for storing some private data after the mempool structure, as is done for rte_mbuf_pool for example.
mp_init	A function pointer that is called for initialization of the pool, before object initialization. The user can initialize the private data in this function if needed. This parameter can be NULL if not needed.
mp_init_arg	An opaque pointer to data that can be used in the mempool constructor function.
obj_init	A function called for each object at initialization of the pool. See rte_mempool_create() for details.
obj_init_arg	An opaque pointer passed to the object constructor function.
socket_id	The socket_id argument is the socket identifier in the case of NUMA. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.
flags	Flags controlling the behavior of the mempool. See rte_mempool_create() for details.
vaddr	Virtual address of the externally allocated memory buffer. Will be used to store mempool objects.
paddr	Array of physical addresses of the pages that comprises given memory buffer.
pg_num	Number of elements in the paddr array.
pg_shift	LOG2 of the physical pages size.

Returns: The pointer to the new allocated mempool, on success. NULL on error with rte_errno set appropriately. See rte_mempool_create() for details.

struct rte_mempool* rte_mempool_create_empty	(	const char *	name,
		unsigned	n,
		unsigned	elt_size,
		unsigned	cache_size,
		unsigned	private_data_size,
		int	socket_id,
		unsigned	flags
	)

read

Create an empty mempool

The mempool is allocated and initialized, but it is not populated: no memory is allocated for the mempool elements. The user has to call rte_mempool_populate_*() to add memory chunks to the pool. Once populated, the user may also want to initialize each object with rte_mempool_obj_iter().

Parameters

name	The name of the mempool.
n	The maximum number of elements that can be added in the mempool. The optimum size (in terms of memory usage) for a mempool is when n is a power of two minus one: n = (2^q - 1).
elt_size	The size of each element.
cache_size	Size of the cache. See rte_mempool_create() for details.
private_data_size	The size of the private data appended after the mempool structure. This is useful for storing some private data after the mempool structure, as is done for rte_mbuf_pool for example.
socket_id	The socket_id argument is the socket identifier in the case of NUMA. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.
flags	Flags controlling the behavior of the mempool. See rte_mempool_create() for details.

Returns: The pointer to the new allocated mempool, on success. NULL on error with rte_errno set appropriately. See rte_mempool_create() for details.

void rte_mempool_free ( struct rte_mempool * mp )

Free a mempool

Unlink the mempool from global list, free the memory chunks, and all memory referenced by the mempool. The objects must not be used by other cores as they will be freed.

Parameters

mp	A pointer to the mempool structure.

int rte_mempool_populate_phys	(	struct rte_mempool *	mp,
		char *	vaddr,
		phys_addr_t	paddr,
		size_t	len,
		rte_mempool_memchunk_free_cb_t *	free_cb,
		void *	opaque
	)

Add physically contiguous memory for objects in the pool at init

Add a virtually and physically contiguous memory chunk in the pool where objects can be instanciated.

If the given physical address is unknown (paddr = RTE_BAD_PHYS_ADDR), the chunk doesn't need to be physically contiguous (only virtually), and allocated objects may span two pages.

Parameters

mp	A pointer to the mempool structure.
vaddr	The virtual address of memory that should be used to store objects.
paddr	The physical address
len	The length of memory in bytes.
free_cb	The callback used to free this chunk when destroying the mempool.
opaque	An opaque argument passed to free_cb.

Returns: The number of objects added on success. On error, the chunk is not added in the memory list of the mempool and a negative errno is returned.

int rte_mempool_populate_phys_tab	(	struct rte_mempool *	mp,
		char *	vaddr,
		const phys_addr_t	paddr[],
		uint32_t	pg_num,
		uint32_t	pg_shift,
		rte_mempool_memchunk_free_cb_t *	free_cb,
		void *	opaque
	)

Add physical memory for objects in the pool at init

Add a virtually contiguous memory chunk in the pool where objects can be instanciated. The physical addresses corresponding to the virtual area are described in paddr[], pg_num, pg_shift.

Parameters

mp	A pointer to the mempool structure.
vaddr	The virtual address of memory that should be used to store objects.
paddr	An array of physical addresses of each page composing the virtual area.
pg_num	Number of elements in the paddr array.
pg_shift	LOG2 of the physical pages size.
free_cb	The callback used to free this chunk when destroying the mempool.
opaque	An opaque argument passed to free_cb.

Returns: The number of objects added on success. On error, the chunks are not added in the memory list of the mempool and a negative errno is returned.

int rte_mempool_populate_virt	(	struct rte_mempool *	mp,
		char *	addr,
		size_t	len,
		size_t	pg_sz,
		rte_mempool_memchunk_free_cb_t *	free_cb,
		void *	opaque
	)

Add virtually contiguous memory for objects in the pool at init

Add a virtually contiguous memory chunk in the pool where objects can be instanciated.

Parameters

mp	A pointer to the mempool structure.
addr	The virtual address of memory that should be used to store objects. Must be page-aligned.
len	The length of memory in bytes. Must be page-aligned.
pg_sz	The size of memory pages in this virtual area.
free_cb	The callback used to free this chunk when destroying the mempool.
opaque	An opaque argument passed to free_cb.

Returns: The number of objects added on success. On error, the chunk is not added in the memory list of the mempool and a negative errno is returned.

int rte_mempool_populate_default ( struct rte_mempool * mp )

Add memory for objects in the pool at init

This is the default function used by rte_mempool_create() to populate the mempool. It adds memory allocated using rte_memzone_reserve().

Parameters

mp	A pointer to the mempool structure.

Returns: The number of objects added on success. On error, the chunk is not added in the memory list of the mempool and a negative errno is returned.

int rte_mempool_populate_anon ( struct rte_mempool * mp )

Add memory from anonymous mapping for objects in the pool at init

This function mmap an anonymous memory zone that is locked in memory to store the objects of the mempool.

Parameters

mp	A pointer to the mempool structure.

Returns: The number of objects added on success. On error, the chunk is not added in the memory list of the mempool and a negative errno is returned.

uint32_t rte_mempool_obj_iter	(	struct rte_mempool *	mp,
		rte_mempool_obj_cb_t *	obj_cb,
		void *	obj_cb_arg
	)

Call a function for each mempool element

Iterate across all objects attached to a rte_mempool and call the callback function on it.

Parameters

mp	A pointer to an initialized mempool.
obj_cb	A function pointer that is called for each object.
obj_cb_arg	An opaque pointer passed to the callback function.

Returns: Number of objects iterated.

uint32_t rte_mempool_mem_iter	(	struct rte_mempool *	mp,
		rte_mempool_mem_cb_t *	mem_cb,
		void *	mem_cb_arg
	)

Call a function for each mempool memory chunk

Iterate across all memory chunks attached to a rte_mempool and call the callback function on it.

Parameters

mp	A pointer to an initialized mempool.
mem_cb	A function pointer that is called for each memory chunk.
mem_cb_arg	An opaque pointer passed to the callback function.

Returns: Number of memory chunks iterated.

void rte_mempool_dump	(	FILE *	f,
		struct rte_mempool *	mp
	)

Dump the status of the mempool to a file.

Parameters

f	A pointer to a file for output
mp	A pointer to the mempool structure.

struct rte_mempool_cache* rte_mempool_cache_create	(	uint32_t	size,
		int	socket_id
	)

read

Create a user-owned mempool cache.

This can be used by non-EAL threads to enable caching when they interact with a mempool.

Parameters

size	The size of the mempool cache. See rte_mempool_create()'s cache_size parameter description for more information. The same limits and considerations apply here too.
socket_id	The socket identifier in the case of NUMA. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.

void rte_mempool_cache_free ( struct rte_mempool_cache * cache )

Free a user-owned mempool cache.

Parameters

cache A pointer to the mempool cache.

static void rte_mempool_cache_flush	(	struct rte_mempool_cache *	cache,
		struct rte_mempool *	mp
	)

inlinestatic

Flush a user-owned mempool cache to the specified mempool.

Parameters

cache	A pointer to the mempool cache.
mp	A pointer to the mempool.

Definition at line 995 of file rte_mempool.h.

static struct rte_mempool_cache* rte_mempool_default_cache	(	struct rte_mempool *	mp,
		unsigned	lcore_id
	)

staticread

Get a pointer to the per-lcore default mempool cache.

Parameters

mp	A pointer to the mempool structure.
lcore_id	The logical core id.

Returns: A pointer to the mempool cache or NULL if disabled or non-EAL thread.

Definition at line 1013 of file rte_mempool.h.

static void rte_mempool_generic_put	(	struct rte_mempool *	mp,
		void const	obj_table,
		unsigned	n,
		struct rte_mempool_cache *	cache,
		__rte_unused int	flags
	)

inlinestatic

Put several objects back in the mempool.

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects).
n	The number of objects to add in the mempool from the obj_table.
cache	A pointer to a mempool cache structure. May be NULL if not needed.
flags	The flags used for the mempool creation. Single-producer (MEMPOOL_F_SP_PUT flag) or multi-producers.

Definition at line 1102 of file rte_mempool.h.

static __rte_deprecated void rte_mempool_mp_put_bulk	(	struct rte_mempool *	mp,
		void const	obj_table,
		unsigned	n
	)

inlinestatic

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects).
n	The number of objects to add in the mempool from the obj_table.

Definition at line 1123 of file rte_mempool.h.

static __rte_deprecated void rte_mempool_sp_put_bulk	(	struct rte_mempool *	mp,
		void const	obj_table,
		unsigned	n
	)

inlinestatic

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects).
n	The number of objects to add in the mempool from obj_table.

Definition at line 1144 of file rte_mempool.h.

static void rte_mempool_put_bulk	(	struct rte_mempool *	mp,
		void const	obj_table,
		unsigned	n
	)

inlinestatic

Put several objects back in the mempool.

This function calls the multi-producer or the single-producer version depending on the default behavior that was specified at mempool creation time (see flags).

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects).
n	The number of objects to add in the mempool from obj_table.

Examples:: examples/distributor/main.c.

Definition at line 1165 of file rte_mempool.h.

static __rte_deprecated void rte_mempool_mp_put	(	struct rte_mempool *	mp,
		void *	obj
	)

inlinestatic

Parameters

mp	A pointer to the mempool structure.
obj	A pointer to the object to be added.

Definition at line 1184 of file rte_mempool.h.

static __rte_deprecated void rte_mempool_sp_put	(	struct rte_mempool *	mp,
		void *	obj
	)

inlinestatic

Parameters

mp	A pointer to the mempool structure.
obj	A pointer to the object to be added.

Definition at line 1202 of file rte_mempool.h.

static void rte_mempool_put	(	struct rte_mempool *	mp,
		void *	obj
	)

inlinestatic

Put one object back in the mempool.

This function calls the multi-producer or the single-producer version depending on the default behavior that was specified at mempool creation time (see flags).

Parameters

mp	A pointer to the mempool structure.
obj	A pointer to the object to be added.

Examples:: examples/multi_process/simple_mp/main.c, and examples/multi_process/simple_mp/mp_commands.c.

Definition at line 1220 of file rte_mempool.h.

static int rte_mempool_generic_get	(	struct rte_mempool *	mp,
		void **	obj_table,
		unsigned	n,
		struct rte_mempool_cache *	cache,
		__rte_unused int	flags
	)

inlinestatic

Get several objects from the mempool.

If cache is enabled, objects will be retrieved first from cache, subsequently from the common pool. Note that it can return -ENOENT when the local cache and common pool are empty, even if cache from other lcores are full.

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects) that will be filled.
n	The number of objects to get from mempool to obj_table.
cache	A pointer to a mempool cache structure. May be NULL if not needed.
flags	The flags used for the mempool creation. Single-consumer (MEMPOOL_F_SC_GET flag) or multi-consumers.

Returns

0: Success; objects taken.
-ENOENT: Not enough entries in the mempool; no object is retrieved.

Definition at line 1324 of file rte_mempool.h.

static __rte_deprecated int rte_mempool_mc_get_bulk	(	struct rte_mempool *	mp,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

If cache is enabled, objects will be retrieved first from cache, subsequently from the common pool. Note that it can return -ENOENT when the local cache and common pool are empty, even if cache from other lcores are full.

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects) that will be filled.
n	The number of objects to get from mempool to obj_table.

Returns

0: Success; objects taken.
-ENOENT: Not enough entries in the mempool; no object is retrieved.

Definition at line 1355 of file rte_mempool.h.

static __rte_deprecated int rte_mempool_sc_get_bulk	(	struct rte_mempool *	mp,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

If cache is enabled, objects will be retrieved first from cache, subsequently from the common pool. Note that it can return -ENOENT when the local cache and common pool are empty, even if cache from other lcores are full.

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects) that will be filled.
n	The number of objects to get from the mempool to obj_table.

Returns

0: Success; objects taken.
-ENOENT: Not enough entries in the mempool; no object is retrieved.

Definition at line 1384 of file rte_mempool.h.

static int rte_mempool_get_bulk	(	struct rte_mempool *	mp,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

Get several objects from the mempool.

This function calls the multi-consumers or the single-consumer version, depending on the default behaviour that was specified at mempool creation time (see flags).

If cache is enabled, objects will be retrieved first from cache, subsequently from the common pool. Note that it can return -ENOENT when the local cache and common pool are empty, even if cache from other lcores are full.

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects) that will be filled.
n	The number of objects to get from the mempool to obj_table.

Returns

0: Success; objects taken
-ENOENT: Not enough entries in the mempool; no object is retrieved.

Examples:: examples/distributor/main.c.

Definition at line 1413 of file rte_mempool.h.

static __rte_deprecated int rte_mempool_mc_get	(	struct rte_mempool *	mp,
		void **	obj_p
	)

inlinestatic

If cache is enabled, objects will be retrieved first from cache, subsequently from the common pool. Note that it can return -ENOENT when the local cache and common pool are empty, even if cache from other lcores are full.

Parameters

mp	A pointer to the mempool structure.
obj_p	A pointer to a void * pointer (object) that will be filled.

Returns

0: Success; objects taken.
-ENOENT: Not enough entries in the mempool; no object is retrieved.

Definition at line 1439 of file rte_mempool.h.

static __rte_deprecated int rte_mempool_sc_get	(	struct rte_mempool *	mp,
		void **	obj_p
	)

inlinestatic

If cache is enabled, objects will be retrieved first from cache, subsequently from the common pool. Note that it can return -ENOENT when the local cache and common pool are empty, even if cache from other lcores are full.

Parameters

mp	A pointer to the mempool structure.
obj_p	A pointer to a void * pointer (object) that will be filled.

Returns

0: Success; objects taken.
-ENOENT: Not enough entries in the mempool; no object is retrieved.

Definition at line 1465 of file rte_mempool.h.

static int rte_mempool_get	(	struct rte_mempool *	mp,
		void **	obj_p
	)

inlinestatic

Get one object from the mempool.

This function calls the multi-consumers or the single-consumer version, depending on the default behavior that was specified at mempool creation (see flags).

If cache is enabled, objects will be retrieved first from cache, subsequently from the common pool. Note that it can return -ENOENT when the local cache and common pool are empty, even if cache from other lcores are full.

Parameters

mp	A pointer to the mempool structure.
obj_p	A pointer to a void * pointer (object) that will be filled.

Returns

0: Success; objects taken.
-ENOENT: Not enough entries in the mempool; no object is retrieved.

Examples:: examples/multi_process/simple_mp/mp_commands.c.

Definition at line 1491 of file rte_mempool.h.

unsigned int rte_mempool_avail_count ( const struct rte_mempool * mp )

Return the number of entries in the mempool.

When cache is enabled, this function has to browse the length of all lcores, so it should not be used in a data path, but only for debug purposes. User-owned mempool caches are not accounted for.

Parameters

mp	A pointer to the mempool structure.

Returns: The number of entries in the mempool.

__rte_deprecated unsigned rte_mempool_count ( const struct rte_mempool * mp )

When cache is enabled, this function has to browse the length of all lcores, so it should not be used in a data path, but only for debug purposes.

Parameters

mp	A pointer to the mempool structure.

Returns: The number of entries in the mempool.

unsigned int rte_mempool_in_use_count ( const struct rte_mempool * mp )

Return the number of elements which have been allocated from the mempool

When cache is enabled, this function has to browse the length of all lcores, so it should not be used in a data path, but only for debug purposes.

Parameters

mp	A pointer to the mempool structure.

Returns: The number of free entries in the mempool.

static __rte_deprecated unsigned rte_mempool_free_count ( const struct rte_mempool * mp )

inlinestatic

NOTE: This corresponds to the number of elements allocated from the memory pool, not the number of elements in the pool itself. To count the number elements currently available in the pool, use "rte_mempool_count"

When cache is enabled, this function has to browse the length of all lcores, so it should not be used in a data path, but only for debug purposes. User-owned mempool caches are not accounted for.

Parameters

mp	A pointer to the mempool structure.

Returns: The number of free entries in the mempool.

Definition at line 1561 of file rte_mempool.h.

static int rte_mempool_full ( const struct rte_mempool * mp )

inlinestatic

Test if the mempool is full.

When cache is enabled, this function has to browse the length of all lcores, so it should not be used in a data path, but only for debug purposes. User-owned mempool caches are not accounted for.

Parameters

mp	A pointer to the mempool structure.

Returns

1: The mempool is full.
0: The mempool is not full.

Definition at line 1580 of file rte_mempool.h.

static int rte_mempool_empty ( const struct rte_mempool * mp )

inlinestatic

Test if the mempool is empty.

When cache is enabled, this function has to browse the length of all lcores, so it should not be used in a data path, but only for debug purposes. User-owned mempool caches are not accounted for.

Parameters

mp	A pointer to the mempool structure.

Returns

1: The mempool is empty.
0: The mempool is not empty.

Definition at line 1599 of file rte_mempool.h.

static phys_addr_t rte_mempool_virt2phy	(	__rte_unused const struct rte_mempool *	mp,
		const void *	elt
	)

inlinestatic

Return the physical address of elt, which is an element of the pool mp.

Parameters

mp	A pointer to the mempool structure.
elt	A pointer (virtual address) to the element of the pool.

Returns: The physical address of the elt element. If the mempool was created with MEMPOOL_F_NO_PHYS_CONTIG, the returned value is RTE_BAD_PHYS_ADDR.

Definition at line 1617 of file rte_mempool.h.

void rte_mempool_audit ( struct rte_mempool * mp )

Check the consistency of mempool objects.

Verify the coherency of fields in the mempool structure. Also check that the cookies of mempool objects (even the ones that are not present in pool) have a correct value. If not, a panic will occur.

Parameters

mp	A pointer to the mempool structure.

static void* rte_mempool_get_priv ( struct rte_mempool * mp )

inlinestatic

Return a pointer to the private data in an mempool structure.

Parameters

mp	A pointer to the mempool structure.

Returns: A pointer to the private data.

Definition at line 1645 of file rte_mempool.h.

void rte_mempool_list_dump ( FILE * f )

Dump the status of all mempools on the console

Parameters

f	A pointer to a file for output

struct rte_mempool* rte_mempool_lookup ( const char * name )

read

Search a mempool from its name

Parameters

name	The name of the mempool.

Returns

The pointer to the mempool matching the name, or NULL if not found. NULL on error with rte_errno set appropriately. Possible rte_errno values include:

ENOENT - required entry not available to return.

Examples:: examples/multi_process/client_server_mp/mp_client/client.c, examples/multi_process/simple_mp/main.c, examples/multi_process/symmetric_mp/main.c, and examples/server_node_efd/node/node.c.

uint32_t rte_mempool_calc_obj_size	(	uint32_t	elt_size,
		uint32_t	flags,
		struct rte_mempool_objsz *	sz
	)

Get the header, trailer and total size of a mempool element.

Given a desired size of the mempool element and mempool flags, calculates header, trailer, body and total sizes of the mempool object.

Parameters

elt_size	The size of each element, without header and trailer.
flags	The flags used for the mempool creation. Consult rte_mempool_create() for more information about possible values. The size of each element.
sz	The calculated detailed size the mempool object. May be NULL.

Returns: Total size of the mempool object.

size_t rte_mempool_xmem_size	(	uint32_t	elt_num,
		size_t	total_elt_sz,
		uint32_t	pg_shift
	)

Get the size of memory required to store mempool elements.

Calculate the maximum amount of memory required to store given number of objects. Assume that the memory buffer will be aligned at page boundary.

Note that if object size is bigger then page size, then it assumes that pages are grouped in subsets of physically continuous pages big enough to store at least one object.

Parameters

elt_num	Number of elements.
total_elt_sz	The size of each element, including header and trailer, as returned by rte_mempool_calc_obj_size().
pg_shift	LOG2 of the physical pages size. If set to 0, ignore page boundaries.

Returns: Required memory size aligned at page boundary.

ssize_t rte_mempool_xmem_usage	(	void *	vaddr,
		uint32_t	elt_num,
		size_t	total_elt_sz,
		const phys_addr_t	paddr[],
		uint32_t	pg_num,
		uint32_t	pg_shift
	)

Get the size of memory required to store mempool elements.

Calculate how much memory would be actually required with the given memory footprint to store required number of objects.

Parameters

vaddr	Virtual address of the externally allocated memory buffer. Will be used to store mempool objects.
elt_num	Number of elements.
total_elt_sz	The size of each element, including header and trailer, as returned by rte_mempool_calc_obj_size().
paddr	Array of physical addresses of the pages that comprises given memory buffer.
pg_num	Number of elements in the paddr array.
pg_shift	LOG2 of the physical pages size.

Returns: On success, the number of bytes needed to store given number of objects, aligned to the given page size. If the provided memory buffer is too small, return a negative value whose absolute value is the actual number of elements that can be stored in that buffer.

void rte_mempool_walk	(	void()(struct rte_mempool , void *arg)	func,
		void *	arg
	)

Walk list of all memory pools

Parameters

func	Iterator function
arg	Argument passed to iterator

Variable Documentation

struct rte_mempool_ops_table rte_mempool_ops_table

Array of registered ops structs.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation