DPDK  2.2.0
Data Structures | Macros | Typedefs | Functions
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_log.h>
#include <rte_debug.h>
#include <rte_lcore.h>
#include <rte_memory.h>
#include <rte_branch_prediction.h>
#include <rte_ring.h>

Go to the source code of this file.

Data Structures

struct  rte_mempool_objsz
struct  rte_mempool_objhdr
struct  rte_mempool_objtlr
struct  rte_mempool

Macros

#define RTE_MEMPOOL_HEADER_COOKIE1   0xbadbadbadadd2e55ULL
#define RTE_MEMPOOL_HEADER_COOKIE2   0xf2eef2eedadd2e55ULL
#define RTE_MEMPOOL_TRAILER_COOKIE   0xadd2e55badbadbadULL
#define RTE_MEMPOOL_NAMESIZE   32
#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_HEADER_SIZE(mp, pgn)
#define MEMPOOL_IS_CONTIG(mp)

Typedefs

typedef void(* rte_mempool_obj_iter_t )(void *, void *, void *, uint32_t)
typedef void( rte_mempool_obj_ctor_t )(struct rte_mempool *, void *, void *, unsigned)
typedef void( rte_mempool_ctor_t )(struct rte_mempool *, void *)

Functions

static struct rte_mempoolrte_mempool_from_obj (void *obj)
uint32_t rte_mempool_obj_iter (void *vaddr, uint32_t elt_num, size_t elt_sz, size_t align, const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift, rte_mempool_obj_iter_t obj_iter, void *obj_iter_arg)
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_ctor_t *obj_init, void *obj_init_arg, int socket_id, unsigned flags)
struct rte_mempoolrte_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_ctor_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_mempoolrte_dom0_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_ctor_t *obj_init, void *obj_init_arg, int socket_id, unsigned flags)
void rte_mempool_dump (FILE *f, const struct rte_mempool *mp)
static void rte_mempool_mp_put_bulk (struct rte_mempool *mp, void *const *obj_table, unsigned n)
static 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 void rte_mempool_mp_put (struct rte_mempool *mp, void *obj)
static 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_mc_get_bulk (struct rte_mempool *mp, void **obj_table, unsigned n)
static 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 int rte_mempool_mc_get (struct rte_mempool *mp, void **obj_p)
static 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 rte_mempool_count (const struct rte_mempool *mp)
static 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 (const struct rte_mempool *mp, const void *elt)
void rte_mempool_audit (const 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)
size_t rte_mempool_xmem_size (uint32_t elt_num, size_t elt_sz, uint32_t pg_shift)
ssize_t rte_mempool_xmem_usage (void *vaddr, uint32_t elt_num, size_t elt_sz, const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift)
void rte_mempool_walk (void(*func)(const struct rte_mempool *, void *arg), void *arg)

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

#define RTE_MEMPOOL_HEADER_COOKIE2   0xf2eef2eedadd2e55ULL

Header cookie.

Definition at line 81 of file rte_mempool.h.

#define RTE_MEMPOOL_TRAILER_COOKIE   0xadd2e55badbadbadULL

Trailer cookie.

Definition at line 82 of file rte_mempool.h.

#define RTE_MEMPOOL_NAMESIZE   32

Maximum length of a memory pool.

Examples:
ip_reassembly/main.c, multi_process/l2fwd_fork/main.c, and vhost/main.c.

Definition at line 123 of file rte_mempool.h.

#define MEMPOOL_PG_NUM_DEFAULT   1

Mempool over one chunk of physically continuous memory

Definition at line 143 of file rte_mempool.h.

#define MEMPOOL_F_NO_SPREAD   0x0001

Do not spread in memory.

Definition at line 222 of file rte_mempool.h.

#define MEMPOOL_F_NO_CACHE_ALIGN   0x0002

Do not align objs on cache lines.

Definition at line 223 of file rte_mempool.h.

#define MEMPOOL_F_SP_PUT   0x0004

Default put is "single-producer".

Examples:
ip_reassembly/main.c, and multi_process/l2fwd_fork/main.c.

Definition at line 224 of file rte_mempool.h.

#define MEMPOOL_F_SC_GET   0x0008

Default get is "single-consumer".

Examples:
ip_reassembly/main.c, and multi_process/l2fwd_fork/main.c.

Definition at line 225 of file rte_mempool.h.

#define MEMPOOL_HEADER_SIZE (   mp,
  pgn 
)
Value:
(sizeof(*(mp)) + \
RTE_ALIGN_CEIL(((pgn) - RTE_DIM((mp)->elt_pa)) * \
sizeof ((mp)->elt_pa[0]), RTE_CACHE_LINE_SIZE))

Calculate the size of the mempool header.

Parameters
mpPointer to the memory pool.
pgnNumber of pages used to store mempool objects.

Definition at line 257 of file rte_mempool.h.

#define MEMPOOL_IS_CONTIG (   mp)
Value:
((mp)->pg_num == MEMPOOL_PG_NUM_DEFAULT && \
(mp)->phys_addr == (mp)->elt_pa[0])

Return true if the whole mempool is in contiguous memory.

Definition at line 264 of file rte_mempool.h.

Typedef Documentation

typedef void(* rte_mempool_obj_iter_t)(void *, void *, void *, uint32_t)

A mempool object iterator callback function.

Definition at line 391 of file rte_mempool.h.

typedef void( rte_mempool_obj_ctor_t)(struct rte_mempool *, void *, void *, unsigned)

An object constructor callback function for mempool.

Arguments are the mempool, the opaque pointer given by the user in rte_mempool_create(), the pointer to the element and the index of the element in the pool.

Definition at line 443 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 452 of file rte_mempool.h.

Function Documentation

static struct rte_mempool* rte_mempool_from_obj ( void *  obj)
staticread

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

uint32_t rte_mempool_obj_iter ( void *  vaddr,
uint32_t  elt_num,
size_t  elt_sz,
size_t  align,
const phys_addr_t  paddr[],
uint32_t  pg_num,
uint32_t  pg_shift,
rte_mempool_obj_iter_t  obj_iter,
void *  obj_iter_arg 
)

Call a function for each mempool object in a memory chunk

Iterate across objects of the given size and alignment in the provided chunk of memory. The given memory buffer can consist of disjointed physical pages.

For each object, call the provided callback (if any). This function is used to populate a mempool, or walk through all the elements of a mempool, or estimate how many elements of the given size could be created in the given memory buffer.

Parameters
vaddrVirtual address of the memory buffer.
elt_numMaximum number of objects to iterate through.
elt_szSize of each object.
alignAlignment of each object.
paddrArray of physical addresses of the pages that comprises given memory buffer.
pg_numNumber of elements in the paddr array.
pg_shiftLOG2 of the physical pages size.
obj_iterObject iterator callback function (could be NULL).
obj_iter_argUser defined parameter for the object iterator callback function.
Returns
Number of objects iterated through.
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_ctor_t obj_init,
void *  obj_init_arg,
int  socket_id,
unsigned  flags 
)
read

Create a new mempool named name in memory.

This function uses memzone_reserve() to allocate memory. The pool contains n elements of elt_size. Its size is set to n. All elements of the mempool are allocated together with the mempool header, in one physically continuous chunk of memory.

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 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. Note that even if not used, the memory space for cache is always reserved in a mempool structure, except if CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE is set to 0.
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".
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:
ip_pipeline/init.c, ip_reassembly/main.c, multi_process/l2fwd_fork/main.c, multi_process/simple_mp/main.c, and 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_ctor_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.

This function uses memzone_reserve() to allocate memory. The pool contains n elements of elt_size. Its size is set to n. 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
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 CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE. 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. Note that even if not used, the memory space for cache is always reserved in a mempool structure, except if CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE is set to 0.
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".
vaddrVirtual address of the externally allocated memory buffer. Will be used to store mempool objects.
paddrArray of physical addresses of the pages that comprises given memory buffer.
pg_numNumber of elements in the paddr array.
pg_shiftLOG2 of the physical pages size.
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
struct rte_mempool* rte_dom0_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_ctor_t obj_init,
void *  obj_init_arg,
int  socket_id,
unsigned  flags 
)
read

Create a new mempool named name in memory on Xen Dom0.

This function uses rte_mempool_xmem_create() to allocate memory. The pool contains n elements of elt_size. Its size is set to n. All elements of the mempool are allocated together with the mempool header, and memory buffer can consist of set of disjoint physical pages.

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 CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE. 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. Note that even if not used, the memory space for cache is always reserved in a mempool structure, except if CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE is set to 0.
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".
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
void rte_mempool_dump ( FILE *  f,
const struct rte_mempool mp 
)

Dump the status of the mempool to the console.

Parameters
fA pointer to a file for output
mpA pointer to the mempool structure.
static void rte_mempool_mp_put_bulk ( struct rte_mempool mp,
void *const *  obj_table,
unsigned  n 
)
inlinestatic

Put several objects back in the mempool (multi-producers safe).

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.

Definition at line 837 of file rte_mempool.h.

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

Put several objects back in the mempool (NOT multi-producers safe).

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.

Definition at line 855 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
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:
distributor/main.c.

Definition at line 877 of file rte_mempool.h.

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

Put one object in the mempool (multi-producers safe).

Parameters
mpA pointer to the mempool structure.
objA pointer to the object to be added.

Definition at line 893 of file rte_mempool.h.

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

Put one object back in the mempool (NOT multi-producers safe).

Parameters
mpA pointer to the mempool structure.
objA pointer to the object to be added.

Definition at line 907 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
mpA pointer to the mempool structure.
objA pointer to the object to be added.
Examples:
multi_process/l2fwd_fork/main.c, multi_process/simple_mp/main.c, and multi_process/simple_mp/mp_commands.c.

Definition at line 925 of file rte_mempool.h.

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

Get several objects from the mempool (multi-consumers safe).

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.
Returns
  • 0: Success; objects taken.
  • -ENOENT: Not enough entries in the mempool; no object is retrieved.

Definition at line 1030 of file rte_mempool.h.

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

Get several objects from the mempool (NOT multi-consumers safe).

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.

Definition at line 1059 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
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:
distributor/main.c.

Definition at line 1091 of file rte_mempool.h.

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

Get one object from the mempool (multi-consumers safe).

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.

Definition at line 1118 of file rte_mempool.h.

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

Get one object from the mempool (NOT multi-consumers safe).

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.

Definition at line 1140 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
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:
multi_process/l2fwd_fork/main.c, and multi_process/simple_mp/mp_commands.c.

Definition at line 1166 of file rte_mempool.h.

unsigned rte_mempool_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.

Parameters
mpA pointer to the mempool structure.
Returns
The number of entries in the mempool.
Examples:
multi_process/l2fwd_fork/main.c, and vhost/main.c.
static unsigned rte_mempool_free_count ( const struct rte_mempool mp)
inlinestatic

Return the number of free entries in the mempool ring. i.e. how many entries can be freed back to the mempool.

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.

Parameters
mpA pointer to the mempool structure.
Returns
The number of free entries in the mempool.

Definition at line 1203 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.

Parameters
mpA pointer to the mempool structure.
Returns
  • 1: The mempool is full.
  • 0: The mempool is not full.

Definition at line 1222 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.

Parameters
mpA pointer to the mempool structure.
Returns
  • 1: The mempool is empty.
  • 0: The mempool is not empty.

Definition at line 1241 of file rte_mempool.h.

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

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

Parameters
mpA pointer to the mempool structure.
eltA pointer (virtual address) to the element of the pool.
Returns
The physical address of the elt element.
Examples:
vhost/main.c.

Definition at line 1257 of file rte_mempool.h.

void rte_mempool_audit ( const 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.
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 1294 of file rte_mempool.h.

void rte_mempool_list_dump ( FILE *  f)

Dump the status of all mempools on the console

Parameters
fA pointer to a file for output
struct rte_mempool* rte_mempool_lookup ( const char *  name)
read

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:
multi_process/client_server_mp/mp_client/client.c, multi_process/l2fwd_fork/main.c, multi_process/simple_mp/main.c, and multi_process/symmetric_mp/main.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_sizeThe size of each element.
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.
size_t rte_mempool_xmem_size ( uint32_t  elt_num,
size_t  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_numNumber of elements.
elt_szThe size of each element.
pg_shiftLOG2 of the physical pages size.
Returns
Required memory size aligned at page boundary.
ssize_t rte_mempool_xmem_usage ( void *  vaddr,
uint32_t  elt_num,
size_t  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
vaddrVirtual address of the externally allocated memory buffer. Will be used to store mempool objects.
elt_numNumber of elements.
elt_szThe size of each element.
paddrArray of physical addresses of the pages that comprises given memory buffer.
pg_numNumber of elements in the paddr array.
pg_shiftLOG2 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(*)(const struct rte_mempool *, void *arg)  func,
void *  arg 
)

Walk list of all memory pools

Parameters
funcIterator function
argArgument passed to iterator