DPDK  20.11.10
Data Structures | Macros | Typedefs | Functions | Variables
rte_mempool.h File Reference
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <errno.h>
#include <inttypes.h>
#include <sys/queue.h>
#include <rte_config.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>
#include "rte_mempool_trace_fp.h"

Go to the source code of this file.

Data Structures

struct  rte_mempool_cache
 
struct  rte_mempool_objsz
 
struct  rte_mempool_objhdr
 
struct  rte_mempool_memhdr
 
struct  rte_mempool_info
 
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   RTE_DEPRECATED(MEMPOOL_PG_NUM_DEFAULT) 1
 
#define RTE_MEMPOOL_ALIGN   RTE_CACHE_LINE_SIZE
 
#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_IOVA_CONTIG   0x0020
 
#define MEMPOOL_HEADER_SIZE(mp, cs)
 
#define RTE_MEMPOOL_OPS_NAMESIZE   32
 
#define RTE_MEMPOOL_POPULATE_F_ALIGN_OBJ   0x0001
 
#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 int(* rte_mempool_dequeue_contig_blocks_t) (struct rte_mempool *mp, void **first_obj_table, unsigned int n)
 
typedef unsigned(* rte_mempool_get_count) (const struct rte_mempool *mp)
 
typedef ssize_t(* rte_mempool_calc_mem_size_t) (const struct rte_mempool *mp, uint32_t obj_num, uint32_t pg_shift, size_t *min_chunk_size, size_t *align)
 
typedef void() rte_mempool_populate_obj_cb_t(struct rte_mempool *mp, void *opaque, void *vaddr, rte_iova_t iova)
 
typedef int(* rte_mempool_populate_t) (struct rte_mempool *mp, unsigned int max_objs, void *vaddr, rte_iova_t iova, size_t len, rte_mempool_populate_obj_cb_t *obj_cb, void *obj_cb_arg)
 
typedef int(* rte_mempool_get_info_t) (const struct rte_mempool *mp, struct rte_mempool_info *info)
 
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_mempoolrte_mempool_from_obj (void *obj)
 
ssize_t rte_mempool_op_calc_mem_size_default (const struct rte_mempool *mp, uint32_t obj_num, uint32_t pg_shift, size_t *min_chunk_size, size_t *align)
 
int rte_mempool_op_populate_default (struct rte_mempool *mp, unsigned int max_objs, void *vaddr, rte_iova_t iova, size_t len, rte_mempool_populate_obj_cb_t *obj_cb, void *obj_cb_arg)
 
int rte_mempool_ops_get_info (const struct rte_mempool *mp, struct rte_mempool_info *info)
 
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_mempoolrte_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_mempoolrte_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_iova (struct rte_mempool *mp, char *vaddr, rte_iova_t iova, size_t len, 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_cacherte_mempool_cache_create (uint32_t size, int socket_id)
 
void rte_mempool_cache_free (struct rte_mempool_cache *cache)
 
static __rte_always_inline struct rte_mempool_cacherte_mempool_default_cache (struct rte_mempool *mp, unsigned lcore_id)
 
static __rte_always_inline void rte_mempool_cache_flush (struct rte_mempool_cache *cache, struct rte_mempool *mp)
 
static __rte_always_inline void rte_mempool_generic_put (struct rte_mempool *mp, void *const *obj_table, unsigned int n, struct rte_mempool_cache *cache)
 
static __rte_always_inline void rte_mempool_put_bulk (struct rte_mempool *mp, void *const *obj_table, unsigned int n)
 
static __rte_always_inline void rte_mempool_put (struct rte_mempool *mp, void *obj)
 
static __rte_always_inline int rte_mempool_generic_get (struct rte_mempool *mp, void **obj_table, unsigned int n, struct rte_mempool_cache *cache)
 
static __rte_always_inline int rte_mempool_get_bulk (struct rte_mempool *mp, void **obj_table, unsigned int n)
 
static __rte_always_inline int rte_mempool_get (struct rte_mempool *mp, void **obj_p)
 
static __rte_always_inline int rte_mempool_get_contig_blocks (struct rte_mempool *mp, void **first_obj_table, unsigned int n)
 
unsigned int rte_mempool_avail_count (const struct rte_mempool *mp)
 
unsigned int rte_mempool_in_use_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 rte_iova_t rte_mempool_virt2iova (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_mempoolrte_mempool_lookup (const char *name)
 
uint32_t rte_mempool_calc_obj_size (uint32_t elt_size, uint32_t flags, struct rte_mempool_objsz *sz)
 
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 preemptible. An lcore must not be interrupted by another task that uses the same mempool (because it uses a ring which is not preemptible). Also, usual mempool functions like rte_mempool_get() or rte_mempool_put() are designed to be called from an EAL thread due to the internal per-lcore cache. Due to the lack of caching, rte_mempool_get() or rte_mempool_put() performance will suffer when called by unregistered non-EAL threads. Instead, unregistered non-EAL threads should call rte_mempool_generic_get() or rte_mempool_generic_put() with a user cache created with rte_mempool_cache_create().

Definition in file rte_mempool.h.

Macro Definition Documentation

◆ RTE_MEMPOOL_HEADER_COOKIE1

#define RTE_MEMPOOL_HEADER_COOKIE1   0xbadbadbadadd2e55ULL

Header cookie.

Definition at line 60 of file rte_mempool.h.

◆ RTE_MEMPOOL_HEADER_COOKIE2

#define RTE_MEMPOOL_HEADER_COOKIE2   0xf2eef2eedadd2e55ULL

Header cookie.

Definition at line 61 of file rte_mempool.h.

◆ RTE_MEMPOOL_TRAILER_COOKIE

#define RTE_MEMPOOL_TRAILER_COOKIE   0xadd2e55badbadbadULL

Trailer cookie.

Definition at line 62 of file rte_mempool.h.

◆ MEMPOOL_PG_NUM_DEFAULT

#define MEMPOOL_PG_NUM_DEFAULT   RTE_DEPRECATED(MEMPOOL_PG_NUM_DEFAULT) 1

Deprecated. Mempool over one chunk of physically continuous memory

Definition at line 119 of file rte_mempool.h.

◆ RTE_MEMPOOL_ALIGN

#define RTE_MEMPOOL_ALIGN   RTE_CACHE_LINE_SIZE

Alignment of elements inside mempool.

Definition at line 125 of file rte_mempool.h.

◆ MEMPOOL_F_NO_SPREAD

#define MEMPOOL_F_NO_SPREAD   0x0001

Spreading among memory channels not required.

Definition at line 255 of file rte_mempool.h.

◆ MEMPOOL_F_NO_CACHE_ALIGN

#define MEMPOOL_F_NO_CACHE_ALIGN   0x0002

Do not align objs on cache lines.

Definition at line 257 of file rte_mempool.h.

◆ MEMPOOL_F_SP_PUT

#define MEMPOOL_F_SP_PUT   0x0004

Default put is "single-producer".

Definition at line 258 of file rte_mempool.h.

◆ MEMPOOL_F_SC_GET

#define MEMPOOL_F_SC_GET   0x0008

Default get is "single-consumer".

Definition at line 259 of file rte_mempool.h.

◆ MEMPOOL_F_POOL_CREATED

#define MEMPOOL_F_POOL_CREATED   0x0010

Internal: pool is created.

Definition at line 260 of file rte_mempool.h.

◆ MEMPOOL_F_NO_IOVA_CONTIG

#define MEMPOOL_F_NO_IOVA_CONTIG   0x0020

Don't need IOVA contiguous objs.

Definition at line 261 of file rte_mempool.h.

◆ MEMPOOL_HEADER_SIZE

#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
mpPointer to the memory pool.
csSize of the per-lcore cache.

Definition at line 301 of file rte_mempool.h.

◆ RTE_MEMPOOL_OPS_NAMESIZE

#define RTE_MEMPOOL_OPS_NAMESIZE   32

Max length of ops struct name.

Definition at line 387 of file rte_mempool.h.

◆ RTE_MEMPOOL_POPULATE_F_ALIGN_OBJ

#define RTE_MEMPOOL_POPULATE_F_ALIGN_OBJ   0x0001

Align objects on addresses multiple of total_elt_sz.

Definition at line 563 of file rte_mempool.h.

◆ RTE_MEMPOOL_MAX_OPS_IDX

#define RTE_MEMPOOL_MAX_OPS_IDX   16

Max registered ops structs

Definition at line 648 of file rte_mempool.h.

◆ MEMPOOL_REGISTER_OPS

#define MEMPOOL_REGISTER_OPS (   ops)
Value:
RTE_INIT(mp_hdlr_init_##ops) \
{ \
rte_mempool_register_ops(&ops); \
}
#define RTE_INIT(func)
Definition: rte_common.h:195

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 897 of file rte_mempool.h.

Typedef Documentation

◆ rte_mempool_memchunk_free_cb_t

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 175 of file rte_mempool.h.

◆ rte_mempool_alloc_t

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 399 of file rte_mempool.h.

◆ rte_mempool_free_t

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 404 of file rte_mempool.h.

◆ rte_mempool_enqueue_t

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

Enqueue 'n' objects into the external pool.

Returns
  • 0: Success
  • <0: Error

Definition at line 412 of file rte_mempool.h.

◆ rte_mempool_dequeue_t

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

Dequeue 'n' objects from the external pool.

Returns
  • 0: Success
  • <0: Error

Definition at line 421 of file rte_mempool.h.

◆ rte_mempool_dequeue_contig_blocks_t

typedef int(* rte_mempool_dequeue_contig_blocks_t) (struct rte_mempool *mp, void **first_obj_table, unsigned int n)

Dequeue a number of contiguous object blocks from the external pool.

Definition at line 427 of file rte_mempool.h.

◆ rte_mempool_get_count

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

Return the number of available objects in the external pool.

Definition at line 433 of file rte_mempool.h.

◆ rte_mempool_calc_mem_size_t

typedef ssize_t(* rte_mempool_calc_mem_size_t) (const struct rte_mempool *mp, uint32_t obj_num, uint32_t pg_shift, size_t *min_chunk_size, size_t *align)

Calculate memory size required to store given number of objects.

If mempool objects are not required to be IOVA-contiguous (the flag MEMPOOL_F_NO_IOVA_CONTIG is set), min_chunk_size defines virtually contiguous chunk size. Otherwise, if mempool objects must be IOVA-contiguous (the flag MEMPOOL_F_NO_IOVA_CONTIG is clear), min_chunk_size defines IOVA-contiguous chunk size.

Parameters
[in]mpPointer to the memory pool.
[in]obj_numNumber of objects.
[in]pg_shiftLOG2 of the physical pages size. If set to 0, ignore page boundaries.
[out]min_chunk_sizeLocation for minimum size of the memory chunk which may be used to store memory pool objects.
[out]alignLocation for required memory chunk alignment.
Returns
Required memory size.

Definition at line 458 of file rte_mempool.h.

◆ rte_mempool_populate_obj_cb_t

typedef void() rte_mempool_populate_obj_cb_t(struct rte_mempool *mp, void *opaque, void *vaddr, rte_iova_t iova)

Function to be called for each populated object.

Parameters
[in]mpA pointer to the mempool structure.
[in]opaqueAn opaque pointer passed to iterator.
[in]vaddrObject virtual address.
[in]iovaInput/output virtual address of the object or RTE_BAD_IOVA.

Definition at line 524 of file rte_mempool.h.

◆ rte_mempool_populate_t

typedef int(* rte_mempool_populate_t) (struct rte_mempool *mp, unsigned int max_objs, void *vaddr, rte_iova_t iova, size_t len, rte_mempool_populate_obj_cb_t *obj_cb, void *obj_cb_arg)

Populate memory pool objects using provided memory chunk.

Populated objects should be enqueued to the pool, e.g. using rte_mempool_ops_enqueue_bulk().

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

Parameters
[in]mpA pointer to the mempool structure.
[in]max_objsMaximum number of objects to be populated.
[in]vaddrThe virtual address of memory that should be used to store objects.
[in]iovaThe IO address
[in]lenThe length of memory in bytes.
[in]obj_cbCallback function to be executed for each populated object.
[in]obj_cb_argAn opaque pointer passed to the callback function.
Returns
The number of objects added on success. On error, no objects are populated and a negative errno is returned.

Definition at line 555 of file rte_mempool.h.

◆ rte_mempool_get_info_t

typedef int(* rte_mempool_get_info_t) (const struct rte_mempool *mp, struct rte_mempool_info *info)

Get some additional information about a mempool.

Definition at line 616 of file rte_mempool.h.

◆ rte_mempool_obj_cb_t

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 908 of file rte_mempool.h.

◆ rte_mempool_mem_cb_t

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 917 of file rte_mempool.h.

◆ rte_mempool_ctor_t

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 927 of file rte_mempool.h.

Function Documentation

◆ STAILQ_HEAD() [1/2]

STAILQ_HEAD ( rte_mempool_objhdr_list  ,
rte_mempool_objhdr   
)

A list of object headers type

◆ STAILQ_HEAD() [2/2]

STAILQ_HEAD ( rte_mempool_memhdr_list  ,
rte_mempool_memhdr   
)

A list of memory where objects are stored

◆ rte_mempool_from_obj()

static struct rte_mempool* rte_mempool_from_obj ( void *  obj)
static

Return a pointer to the mempool owning this object.

Parameters
objAn 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 321 of file rte_mempool.h.

◆ rte_mempool_op_calc_mem_size_default()

ssize_t rte_mempool_op_calc_mem_size_default ( const struct rte_mempool mp,
uint32_t  obj_num,
uint32_t  pg_shift,
size_t *  min_chunk_size,
size_t *  align 
)

Default way to calculate memory size required to store given number of objects.

Equivalent to rte_mempool_op_calc_mem_size_helper(mp, obj_num, pg_shift, 0, min_chunk_size, align).

◆ rte_mempool_op_populate_default()

int rte_mempool_op_populate_default ( struct rte_mempool mp,
unsigned int  max_objs,
void *  vaddr,
rte_iova_t  iova,
size_t  len,
rte_mempool_populate_obj_cb_t obj_cb,
void *  obj_cb_arg 
)

Default way to populate memory pool object using provided memory chunk.

Equivalent to rte_mempool_op_populate_helper(mp, 0, max_objs, vaddr, iova, len, obj_cb, obj_cb_arg).

◆ rte_mempool_ops_get_info()

int rte_mempool_ops_get_info ( const struct rte_mempool mp,
struct rte_mempool_info info 
)

Wrapper for mempool_ops get_info callback.

Parameters
[in]mpPointer to the memory pool.
[out]infoPointer to the rte_mempool_info structure
Returns
  • 0: Success; The mempool driver supports retrieving supplementary mempool information
  • -ENOTSUP - doesn't support get_info ops (valid case).

◆ rte_mempool_set_ops_byname()

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
mpPointer to the memory pool.
nameName of the ops structure to use for this mempool.
pool_configOpaque 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.
Examples:
examples/ntb/ntb_fwd.c.

◆ rte_mempool_register_ops()

int rte_mempool_register_ops ( const struct rte_mempool_ops ops)

Register mempool operations.

Parameters
opsPointer 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.

◆ rte_mempool_create()

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 
)

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
nameThe name of the mempool.
nThe 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_sizeThe size of each element.
cache_sizeIf 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 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_sizeThe 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_initA 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_argAn opaque pointer to data that can be used in the mempool constructor function.
obj_initA 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_argAn opaque pointer to data that can be used as an argument for each call to the object constructor function.
socket_idThe 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.
flagsThe 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_IOVA_CONTIG: If set, allocated objects won't necessarily be contiguous in IO 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
  • 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/fips_validation/fips_dev_self_test.c, examples/fips_validation/main.c, examples/ip_pipeline/cryptodev.c, examples/ipsec-secgw/ipsec-secgw.c, examples/l2fwd-crypto/main.c, examples/multi_process/simple_mp/main.c, and examples/vhost_crypto/main.c.

◆ rte_mempool_create_empty()

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 
)

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
nameThe name of the mempool.
nThe 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_sizeThe size of each element.
cache_sizeSize of the cache. See rte_mempool_create() for details.
private_data_sizeThe 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_idThe 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.
flagsFlags 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.
Examples:
examples/ntb/ntb_fwd.c.

◆ rte_mempool_free()

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
mpA pointer to the mempool structure.
Examples:
examples/fips_validation/fips_dev_self_test.c, examples/fips_validation/main.c, examples/ip_pipeline/cryptodev.c, examples/ip_pipeline/mempool.c, examples/ntb/ntb_fwd.c, examples/pipeline/obj.c, and examples/vhost_crypto/main.c.

◆ rte_mempool_populate_iova()

int rte_mempool_populate_iova ( struct rte_mempool mp,
char *  vaddr,
rte_iova_t  iova,
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 instantiated.

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

Parameters
mpA pointer to the mempool structure.
vaddrThe virtual address of memory that should be used to store objects.
iovaThe IO address
lenThe length of memory in bytes.
free_cbThe callback used to free this chunk when destroying the mempool.
opaqueAn opaque argument passed to free_cb.
Returns
The number of objects added on success (strictly positive). On error, the chunk is not added in the memory list of the mempool the following code is returned: (0): not enough room in chunk for one object. (-ENOSPC): mempool is already populated. (-ENOMEM): allocation failure.
Examples:
examples/ntb/ntb_fwd.c.

◆ rte_mempool_populate_virt()

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

Parameters
mpA pointer to the mempool structure.
addrThe virtual address of memory that should be used to store objects.
lenThe length of memory in bytes.
pg_szThe size of memory pages in this virtual area.
free_cbThe callback used to free this chunk when destroying the mempool.
opaqueAn opaque argument passed to free_cb.
Returns
The number of objects added on success (strictly positive). On error, the chunk is not added in the memory list of the mempool the following code is returned: (0): not enough room in chunk for one object. (-ENOSPC): mempool is already populated. (-ENOMEM): allocation failure.

◆ rte_mempool_populate_default()

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

◆ rte_mempool_populate_anon()

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
mpA pointer to the mempool structure.
Returns
The number of objects added on success. On error, 0 is returned, rte_errno is set, and the chunk is not added in the memory list of the mempool.

◆ rte_mempool_obj_iter()

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
mpA pointer to an initialized mempool.
obj_cbA function pointer that is called for each object.
obj_cb_argAn opaque pointer passed to the callback function.
Returns
Number of objects iterated.
Examples:
examples/ntb/ntb_fwd.c.

◆ rte_mempool_mem_iter()

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
mpA pointer to an initialized mempool.
mem_cbA function pointer that is called for each memory chunk.
mem_cb_argAn opaque pointer passed to the callback function.
Returns
Number of memory chunks iterated.

◆ rte_mempool_dump()

void rte_mempool_dump ( FILE *  f,
struct rte_mempool mp 
)

Dump the status of the mempool to a file.

Parameters
fA pointer to a file for output
mpA pointer to the mempool structure.

◆ rte_mempool_cache_create()

struct rte_mempool_cache* rte_mempool_cache_create ( uint32_t  size,
int  socket_id 
)

Create a user-owned mempool cache.

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

Parameters
sizeThe 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_idThe socket identifier in the case of NUMA. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.

◆ rte_mempool_cache_free()

void rte_mempool_cache_free ( struct rte_mempool_cache cache)

Free a user-owned mempool cache.

Parameters
cacheA pointer to the mempool cache.

◆ rte_mempool_default_cache()

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

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

Parameters
mpA pointer to the mempool structure.
lcore_idThe logical core id.
Returns
A pointer to the mempool cache or NULL if disabled or unregistered non-EAL thread.

Definition at line 1244 of file rte_mempool.h.

◆ rte_mempool_cache_flush()

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

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

Parameters
cacheA pointer to the mempool cache.
mpA pointer to the mempool.

Definition at line 1266 of file rte_mempool.h.

◆ rte_mempool_generic_put()

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

Put several objects back in the mempool.

Parameters
mpA pointer to the mempool structure.
obj_tableA pointer to a table of void * pointers (objects).
nThe number of objects to add in the mempool from the obj_table.
cacheA pointer to a mempool cache structure. May be NULL if not needed.

Definition at line 1350 of file rte_mempool.h.

◆ rte_mempool_put_bulk()

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

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
mpA pointer to the mempool structure.
obj_tableA pointer to a table of void * pointers (objects).
nThe number of objects to add in the mempool from obj_table.
Examples:
examples/ioat/ioatfwd.c, and examples/vhost_crypto/main.c.

Definition at line 1373 of file rte_mempool.h.

◆ rte_mempool_put()

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

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
mpA pointer to the mempool structure.
objA 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 1395 of file rte_mempool.h.

◆ rte_mempool_generic_get()

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

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
mpA pointer to the mempool structure.
obj_tableA pointer to a table of void * pointers (objects) that will be filled.
nThe number of objects to get from mempool to obj_table.
cacheA pointer to a mempool cache structure. May be NULL if not needed.
Returns
  • 0: Success; objects taken.
  • -ENOENT: Not enough entries in the mempool; no object is retrieved.

Definition at line 1514 of file rte_mempool.h.

◆ rte_mempool_get_bulk()

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

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
mpA pointer to the mempool structure.
obj_tableA pointer to a table of void * pointers (objects) that will be filled.
nThe 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/bbdev_app/main.c, examples/ioat/ioatfwd.c, and examples/ntb/ntb_fwd.c.

Definition at line 1548 of file rte_mempool.h.

◆ rte_mempool_get()

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

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
mpA pointer to the mempool structure.
obj_pA 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 1577 of file rte_mempool.h.

◆ rte_mempool_get_contig_blocks()

static __rte_always_inline int rte_mempool_get_contig_blocks ( struct rte_mempool mp,
void **  first_obj_table,
unsigned int  n 
)
static

Get a contiguous blocks of objects from the mempool.

If cache is enabled, consider to flush it first, to reuse objects as soon as possible.

The application should check that the driver supports the operation by calling rte_mempool_ops_get_info() and checking that contig_block_size is not zero.

Parameters
mpA pointer to the mempool structure.
first_obj_tableA pointer to a pointer to the first object in each block.
nThe number of blocks to get from mempool.
Returns
  • 0: Success; blocks taken.
  • -ENOBUFS: Not enough entries in the mempool; no object is retrieved.
  • -EOPNOTSUPP: The mempool driver does not support block dequeue

Definition at line 1604 of file rte_mempool.h.

◆ rte_mempool_avail_count()

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
mpA pointer to the mempool structure.
Returns
The number of entries in the mempool.

◆ rte_mempool_in_use_count()

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
mpA pointer to the mempool structure.
Returns
The number of free entries in the mempool.

◆ rte_mempool_full()

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
mpA pointer to the mempool structure.
Returns
  • 1: The mempool is full.
  • 0: The mempool is not full.

Definition at line 1665 of file rte_mempool.h.

◆ rte_mempool_empty()

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
mpA pointer to the mempool structure.
Returns
  • 1: The mempool is empty.
  • 0: The mempool is not empty.

Definition at line 1684 of file rte_mempool.h.

◆ rte_mempool_virt2iova()

static rte_iova_t rte_mempool_virt2iova ( const void *  elt)
inlinestatic

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

Parameters
eltA pointer (virtual address) to the element of the pool.
Returns
The IO address of the elt element. If the mempool was created with MEMPOOL_F_NO_IOVA_CONTIG, the returned value is RTE_BAD_IOVA.

Definition at line 1700 of file rte_mempool.h.

◆ rte_mempool_audit()

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
mpA pointer to the mempool structure.

◆ rte_mempool_get_priv()

static void* rte_mempool_get_priv ( struct rte_mempool mp)
inlinestatic

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

Parameters
mpA pointer to the mempool structure.
Returns
A pointer to the private data.

Definition at line 1728 of file rte_mempool.h.

◆ rte_mempool_list_dump()

void rte_mempool_list_dump ( FILE *  f)

Dump the status of all mempools on the console

Parameters
fA pointer to a file for output

◆ rte_mempool_lookup()

struct rte_mempool* rte_mempool_lookup ( const char *  name)

Search a mempool from its name

Parameters
nameThe 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.

◆ rte_mempool_calc_obj_size()

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_sizeThe size of each element, without header and trailer.
flagsThe flags used for the mempool creation. Consult rte_mempool_create() for more information about possible values. The size of each element.
szThe calculated detailed size the mempool object. May be NULL.
Returns
Total size of the mempool object.

◆ rte_mempool_walk()

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

Walk list of all memory pools

Parameters
funcIterator function
argArgument passed to iterator

Variable Documentation

◆ rte_mempool_ops_table

Array of registered ops structs.