lib/librte_mempool/rte_mempool.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   5  *   Copyright(c) 2016 6WIND S.A.
   6  *   All rights reserved.
   7  *
   8  *   Redistribution and use in source and binary forms, with or without
   9  *   modification, are permitted provided that the following conditions
  10  *   are met:
  11  *
  12  *     * Redistributions of source code must retain the above copyright
  13  *       notice, this list of conditions and the following disclaimer.
  14  *     * Redistributions in binary form must reproduce the above copyright
  15  *       notice, this list of conditions and the following disclaimer in
  16  *       the documentation and/or other materials provided with the
  17  *       distribution.
  18  *     * Neither the name of Intel Corporation nor the names of its
  19  *       contributors may be used to endorse or promote products derived
  20  *       from this software without specific prior written permission.
  21  *
  22  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  25  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  26  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 #ifndef _RTE_MEMPOOL_H_
  36 #define _RTE_MEMPOOL_H_
  37
  38 /**
  39  * @file
  40  * RTE Mempool.
  41  *
  42  * A memory pool is an allocator of fixed-size object. It is
  43  * identified by its name, and uses a ring to store free objects. It
  44  * provides some other optional services, like a per-core object
  45  * cache, and an alignment helper to ensure that objects are padded
  46  * to spread them equally on all RAM channels, ranks, and so on.
  47  *
  48  * Objects owned by a mempool should never be added in another
  49  * mempool. When an object is freed using rte_mempool_put() or
  50  * equivalent, the object data is not modified; the user can save some
  51  * meta-data in the object data and retrieve them when allocating a
  52  * new object.
  53  *
  54  * Note: the mempool implementation is not preemptable. A lcore must
  55  * not be interrupted by another task that uses the same mempool
  56  * (because it uses a ring which is not preemptable). Also, mempool
  57  * functions must not be used outside the DPDK environment: for
  58  * example, in linuxapp environment, a thread that is not created by
  59  * the EAL must not use mempools. This is due to the per-lcore cache
  60  * that won't work as rte_lcore_id() will not return a correct value.
  61  */
  62
  63 #include <stdio.h>
  64 #include <stdlib.h>
  65 #include <stdint.h>
  66 #include <errno.h>
  67 #include <inttypes.h>
  68 #include <sys/queue.h>
  69
  70 #include <rte_log.h>
  71 #include <rte_debug.h>
  72 #include <rte_lcore.h>
  73 #include <rte_memory.h>
  74 #include <rte_branch_prediction.h>
  75 #include <rte_ring.h>
  76
  77 #ifdef __cplusplus
  78 extern "C" {
  79 #endif
  80
  81 #define RTE_MEMPOOL_HEADER_COOKIE1  0xbadbadbadadd2e55ULL /**< Header cookie. */
  82 #define RTE_MEMPOOL_HEADER_COOKIE2  0xf2eef2eedadd2e55ULL /**< Header cookie. */
  83 #define RTE_MEMPOOL_TRAILER_COOKIE  0xadd2e55badbadbadULL /**< Trailer cookie.*/
  84
  85 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
  86 /**
  87  * A structure that stores the mempool statistics (per-lcore).
  88  */
  89 struct rte_mempool_debug_stats {
  90         uint64_t put_bulk;         /**< Number of puts. */
  91         uint64_t put_objs;         /**< Number of objects successfully put. */
  92         uint64_t get_success_bulk; /**< Successful allocation number. */
  93         uint64_t get_success_objs; /**< Objects successfully allocated. */
  94         uint64_t get_fail_bulk;    /**< Failed allocation number. */
  95         uint64_t get_fail_objs;    /**< Objects that failed to be allocated. */
  96 } __rte_cache_aligned;
  97 #endif
  98
  99 /**
 100  * A structure that stores a per-core object cache.
 101  */
 102 struct rte_mempool_cache {
 103         unsigned len; /**< Cache len */
 104         /*
 105          * Cache is allocated to this size to allow it to overflow in certain
 106          * cases to avoid needless emptying of cache.
 107          */
 108         void *objs[RTE_MEMPOOL_CACHE_MAX_SIZE * 3]; /**< Cache objects */
 109 } __rte_cache_aligned;
 110
 111 /**
 112  * A structure that stores the size of mempool elements.
 113  */
 114 struct rte_mempool_objsz {
 115         uint32_t elt_size;     /**< Size of an element. */
 116         uint32_t header_size;  /**< Size of header (before elt). */
 117         uint32_t trailer_size; /**< Size of trailer (after elt). */
 118         uint32_t total_size;
 119         /**< Total size of an object (header + elt + trailer). */
 120 };
 121
 122 #define RTE_MEMPOOL_NAMESIZE 32 /**< Maximum length of a memory pool. */
 123 #define RTE_MEMPOOL_MZ_PREFIX "MP_"
 124
 125 /* "MP_<name>" */
 126 #define RTE_MEMPOOL_MZ_FORMAT   RTE_MEMPOOL_MZ_PREFIX "%s"
 127
 128 #define MEMPOOL_PG_SHIFT_MAX    (sizeof(uintptr_t) * CHAR_BIT - 1)
 129
 130 /** Mempool over one chunk of physically continuous memory */
 131 #define MEMPOOL_PG_NUM_DEFAULT  1
 132
 133 #ifndef RTE_MEMPOOL_ALIGN
 134 #define RTE_MEMPOOL_ALIGN       RTE_CACHE_LINE_SIZE
 135 #endif
 136
 137 #define RTE_MEMPOOL_ALIGN_MASK  (RTE_MEMPOOL_ALIGN - 1)
 138
 139 /**
 140  * Mempool object header structure
 141  *
 142  * Each object stored in mempools are prefixed by this header structure,
 143  * it allows to retrieve the mempool pointer from the object and to
 144  * iterate on all objects attached to a mempool. When debug is enabled,
 145  * a cookie is also added in this structure preventing corruptions and
 146  * double-frees.
 147  */
 148 struct rte_mempool_objhdr {
 149         STAILQ_ENTRY(rte_mempool_objhdr) next; /**< Next in list. */
 150         struct rte_mempool *mp;          /**< The mempool owning the object. */
 151         phys_addr_t physaddr;            /**< Physical address of the object. */
 152 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 153         uint64_t cookie;                 /**< Debug cookie. */
 154 #endif
 155 };
 156
 157 /**
 158  * A list of object headers type
 159  */
 160 STAILQ_HEAD(rte_mempool_objhdr_list, rte_mempool_objhdr);
 161
 162 /**
 163  * Mempool object trailer structure
 164  *
 165  * In debug mode, each object stored in mempools are suffixed by this
 166  * trailer structure containing a cookie preventing memory corruptions.
 167  */
 168 struct rte_mempool_objtlr {
 169 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 170         uint64_t cookie;                 /**< Debug cookie. */
 171 #endif
 172 };
 173
 174 /**
 175  * A list of memory where objects are stored
 176  */
 177 STAILQ_HEAD(rte_mempool_memhdr_list, rte_mempool_memhdr);
 178
 179 /**
 180  * Callback used to free a memory chunk
 181  */
 182 typedef void (rte_mempool_memchunk_free_cb_t)(struct rte_mempool_memhdr *memhdr,
 183         void *opaque);
 184
 185 /**
 186  * Mempool objects memory header structure
 187  *
 188  * The memory chunks where objects are stored. Each chunk is virtually
 189  * and physically contiguous.
 190  */
 191 struct rte_mempool_memhdr {
 192         STAILQ_ENTRY(rte_mempool_memhdr) next; /**< Next in list. */
 193         struct rte_mempool *mp;  /**< The mempool owning the chunk */
 194         void *addr;              /**< Virtual address of the chunk */
 195         phys_addr_t phys_addr;   /**< Physical address of the chunk */
 196         size_t len;              /**< length of the chunk */
 197         rte_mempool_memchunk_free_cb_t *free_cb; /**< Free callback */
 198         void *opaque;            /**< Argument passed to the free callback */
 199 };
 200
 201 /**
 202  * The RTE mempool structure.
 203  */
 204 struct rte_mempool {
 205         char name[RTE_MEMPOOL_NAMESIZE]; /**< Name of mempool. */
 206         struct rte_ring *ring;           /**< Ring to store objects. */
 207         phys_addr_t phys_addr;           /**< Phys. addr. of mempool struct. */
 208         int flags;                       /**< Flags of the mempool. */
 209         int socket_id;                   /**< Socket id passed at mempool creation. */
 210         uint32_t size;                   /**< Max size of the mempool. */
 211         uint32_t cache_size;             /**< Size of per-lcore local cache. */
 212         uint32_t cache_flushthresh;
 213         /**< Threshold before we flush excess elements. */
 214
 215         uint32_t elt_size;               /**< Size of an element. */
 216         uint32_t header_size;            /**< Size of header (before elt). */
 217         uint32_t trailer_size;           /**< Size of trailer (after elt). */
 218
 219         unsigned private_data_size;      /**< Size of private data. */
 220
 221         struct rte_mempool_cache *local_cache; /**< Per-lcore local cache */
 222
 223         uint32_t populated_size;         /**< Number of populated objects. */
 224         struct rte_mempool_objhdr_list elt_list; /**< List of objects in pool */
 225         uint32_t nb_mem_chunks;          /**< Number of memory chunks */
 226         struct rte_mempool_memhdr_list mem_list; /**< List of memory chunks */
 227
 228 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 229         /** Per-lcore statistics. */
 230         struct rte_mempool_debug_stats stats[RTE_MAX_LCORE];
 231 #endif
 232 }  __rte_cache_aligned;
 233
 234 #define MEMPOOL_F_NO_SPREAD      0x0001 /**< Do not spread among memory channels. */
 235 #define MEMPOOL_F_NO_CACHE_ALIGN 0x0002 /**< Do not align objs on cache lines.*/
 236 #define MEMPOOL_F_SP_PUT         0x0004 /**< Default put is "single-producer".*/
 237 #define MEMPOOL_F_SC_GET         0x0008 /**< Default get is "single-consumer".*/
 238
 239 /**
 240  * @internal When debug is enabled, store some statistics.
 241  *
 242  * @param mp
 243  *   Pointer to the memory pool.
 244  * @param name
 245  *   Name of the statistics field to increment in the memory pool.
 246  * @param n
 247  *   Number to add to the object-oriented statistics.
 248  */
 249 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 250 #define __MEMPOOL_STAT_ADD(mp, name, n) do {                    \
 251                 unsigned __lcore_id = rte_lcore_id();           \
 252                 if (__lcore_id < RTE_MAX_LCORE) {               \
 253                         mp->stats[__lcore_id].name##_objs += n; \
 254                         mp->stats[__lcore_id].name##_bulk += 1; \
 255                 }                                               \
 256         } while(0)
 257 #else
 258 #define __MEMPOOL_STAT_ADD(mp, name, n) do {} while(0)
 259 #endif
 260
 261 /**
 262  * Calculate the size of the mempool header.
 263  *
 264  * @param mp
 265  *   Pointer to the memory pool.
 266  * @param cs
 267  *   Size of the per-lcore cache.
 268  */
 269 #define MEMPOOL_HEADER_SIZE(mp, cs) \
 270         (sizeof(*(mp)) + (((cs) == 0) ? 0 : \
 271         (sizeof(struct rte_mempool_cache) * RTE_MAX_LCORE)))
 272
 273 /* return the header of a mempool object (internal) */
 274 static inline struct rte_mempool_objhdr *__mempool_get_header(void *obj)
 275 {
 276         return (struct rte_mempool_objhdr *)RTE_PTR_SUB(obj,
 277                 sizeof(struct rte_mempool_objhdr));
 278 }
 279
 280 /**
 281  * Return a pointer to the mempool owning this object.
 282  *
 283  * @param obj
 284  *   An object that is owned by a pool. If this is not the case,
 285  *   the behavior is undefined.
 286  * @return
 287  *   A pointer to the mempool structure.
 288  */
 289 static inline struct rte_mempool *rte_mempool_from_obj(void *obj)
 290 {
 291         struct rte_mempool_objhdr *hdr = __mempool_get_header(obj);
 292         return hdr->mp;
 293 }
 294
 295 /* return the trailer of a mempool object (internal) */
 296 static inline struct rte_mempool_objtlr *__mempool_get_trailer(void *obj)
 297 {
 298         struct rte_mempool *mp = rte_mempool_from_obj(obj);
 299         return (struct rte_mempool_objtlr *)RTE_PTR_ADD(obj, mp->elt_size);
 300 }
 301
 302 /**
 303  * @internal Check and update cookies or panic.
 304  *
 305  * @param mp
 306  *   Pointer to the memory pool.
 307  * @param obj_table_const
 308  *   Pointer to a table of void * pointers (objects).
 309  * @param n
 310  *   Index of object in object table.
 311  * @param free
 312  *   - 0: object is supposed to be allocated, mark it as free
 313  *   - 1: object is supposed to be free, mark it as allocated
 314  *   - 2: just check that cookie is valid (free or allocated)
 315  */
 316 void rte_mempool_check_cookies(const struct rte_mempool *mp,
 317         void * const *obj_table_const, unsigned n, int free);
 318
 319 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 320 #define __mempool_check_cookies(mp, obj_table_const, n, free) \
 321         rte_mempool_check_cookies(mp, obj_table_const, n, free)
 322 #else
 323 #define __mempool_check_cookies(mp, obj_table_const, n, free) do {} while(0)
 324 #endif /* RTE_LIBRTE_MEMPOOL_DEBUG */
 325
 326 /**
 327  * An object callback function for mempool.
 328  *
 329  * Used by rte_mempool_create() and rte_mempool_obj_iter().
 330  */
 331 typedef void (rte_mempool_obj_cb_t)(struct rte_mempool *mp,
 332                 void *opaque, void *obj, unsigned obj_idx);
 333 typedef rte_mempool_obj_cb_t rte_mempool_obj_ctor_t; /* compat */
 334
 335 /**
 336  * A memory callback function for mempool.
 337  *
 338  * Used by rte_mempool_mem_iter().
 339  */
 340 typedef void (rte_mempool_mem_cb_t)(struct rte_mempool *mp,
 341                 void *opaque, struct rte_mempool_memhdr *memhdr,
 342                 unsigned mem_idx);
 343
 344 /**
 345  * A mempool constructor callback function.
 346  *
 347  * Arguments are the mempool and the opaque pointer given by the user in
 348  * rte_mempool_create().
 349  */
 350 typedef void (rte_mempool_ctor_t)(struct rte_mempool *, void *);
 351
 352 /**
 353  * Create a new mempool named *name* in memory.
 354  *
 355  * This function uses ``memzone_reserve()`` to allocate memory. The
 356  * pool contains n elements of elt_size. Its size is set to n.
 357  * All elements of the mempool are allocated together with the mempool header,
 358  * in one physically continuous chunk of memory.
 359  *
 360  * @param name
 361  *   The name of the mempool.
 362  * @param n
 363  *   The number of elements in the mempool. The optimum size (in terms of
 364  *   memory usage) for a mempool is when n is a power of two minus one:
 365  *   n = (2^q - 1).
 366  * @param elt_size
 367  *   The size of each element.
 368  * @param cache_size
 369  *   If cache_size is non-zero, the rte_mempool library will try to
 370  *   limit the accesses to the common lockless pool, by maintaining a
 371  *   per-lcore object cache. This argument must be lower or equal to
 372  *   CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE and n / 1.5. It is advised to choose
 373  *   cache_size to have "n modulo cache_size == 0": if this is
 374  *   not the case, some elements will always stay in the pool and will
 375  *   never be used. The access to the per-lcore table is of course
 376  *   faster than the multi-producer/consumer pool. The cache can be
 377  *   disabled if the cache_size argument is set to 0; it can be useful to
 378  *   avoid losing objects in cache. Note that even if not used, the
 379  *   memory space for cache is always reserved in a mempool structure,
 380  *   except if CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE is set to 0.
 381  * @param private_data_size
 382  *   The size of the private data appended after the mempool
 383  *   structure. This is useful for storing some private data after the
 384  *   mempool structure, as is done for rte_mbuf_pool for example.
 385  * @param mp_init
 386  *   A function pointer that is called for initialization of the pool,
 387  *   before object initialization. The user can initialize the private
 388  *   data in this function if needed. This parameter can be NULL if
 389  *   not needed.
 390  * @param mp_init_arg
 391  *   An opaque pointer to data that can be used in the mempool
 392  *   constructor function.
 393  * @param obj_init
 394  *   A function pointer that is called for each object at
 395  *   initialization of the pool. The user can set some meta data in
 396  *   objects if needed. This parameter can be NULL if not needed.
 397  *   The obj_init() function takes the mempool pointer, the init_arg,
 398  *   the object pointer and the object number as parameters.
 399  * @param obj_init_arg
 400  *   An opaque pointer to data that can be used as an argument for
 401  *   each call to the object constructor function.
 402  * @param socket_id
 403  *   The *socket_id* argument is the socket identifier in the case of
 404  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
 405  *   constraint for the reserved zone.
 406  * @param flags
 407  *   The *flags* arguments is an OR of following flags:
 408  *   - MEMPOOL_F_NO_SPREAD: By default, objects addresses are spread
 409  *     between channels in RAM: the pool allocator will add padding
 410  *     between objects depending on the hardware configuration. See
 411  *     Memory alignment constraints for details. If this flag is set,
 412  *     the allocator will just align them to a cache line.
 413  *   - MEMPOOL_F_NO_CACHE_ALIGN: By default, the returned objects are
 414  *     cache-aligned. This flag removes this constraint, and no
 415  *     padding will be present between objects. This flag implies
 416  *     MEMPOOL_F_NO_SPREAD.
 417  *   - MEMPOOL_F_SP_PUT: If this flag is set, the default behavior
 418  *     when using rte_mempool_put() or rte_mempool_put_bulk() is
 419  *     "single-producer". Otherwise, it is "multi-producers".
 420  *   - MEMPOOL_F_SC_GET: If this flag is set, the default behavior
 421  *     when using rte_mempool_get() or rte_mempool_get_bulk() is
 422  *     "single-consumer". Otherwise, it is "multi-consumers".
 423  * @return
 424  *   The pointer to the new allocated mempool, on success. NULL on error
 425  *   with rte_errno set appropriately. Possible rte_errno values include:
 426  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
 427  *    - E_RTE_SECONDARY - function was called from a secondary process instance
 428  *    - EINVAL - cache size provided is too large
 429  *    - ENOSPC - the maximum number of memzones has already been allocated
 430  *    - EEXIST - a memzone with the same name already exists
 431  *    - ENOMEM - no appropriate memory area found in which to create memzone
 432  */
 433 struct rte_mempool *
 434 rte_mempool_create(const char *name, unsigned n, unsigned elt_size,
 435                    unsigned cache_size, unsigned private_data_size,
 436                    rte_mempool_ctor_t *mp_init, void *mp_init_arg,
 437                    rte_mempool_obj_cb_t *obj_init, void *obj_init_arg,
 438                    int socket_id, unsigned flags);
 439
 440 /**
 441  * Create a new mempool named *name* in memory.
 442  *
 443  * The pool contains n elements of elt_size. Its size is set to n.
 444  * This function uses ``memzone_reserve()`` to allocate the mempool header
 445  * (and the objects if vaddr is NULL).
 446  * Depending on the input parameters, mempool elements can be either allocated
 447  * together with the mempool header, or an externally provided memory buffer
 448  * could be used to store mempool objects. In later case, that external
 449  * memory buffer can consist of set of disjoint physical pages.
 450  *
 451  * @param name
 452  *   The name of the mempool.
 453  * @param n
 454  *   The number of elements in the mempool. The optimum size (in terms of
 455  *   memory usage) for a mempool is when n is a power of two minus one:
 456  *   n = (2^q - 1).
 457  * @param elt_size
 458  *   The size of each element.
 459  * @param cache_size
 460  *   Size of the cache. See rte_mempool_create() for details.
 461  * @param private_data_size
 462  *   The size of the private data appended after the mempool
 463  *   structure. This is useful for storing some private data after the
 464  *   mempool structure, as is done for rte_mbuf_pool for example.
 465  * @param mp_init
 466  *   A function pointer that is called for initialization of the pool,
 467  *   before object initialization. The user can initialize the private
 468  *   data in this function if needed. This parameter can be NULL if
 469  *   not needed.
 470  * @param mp_init_arg
 471  *   An opaque pointer to data that can be used in the mempool
 472  *   constructor function.
 473  * @param obj_init
 474  *   A function called for each object at initialization of the pool.
 475  *   See rte_mempool_create() for details.
 476  * @param obj_init_arg
 477  *   An opaque pointer passed to the object constructor function.
 478  * @param socket_id
 479  *   The *socket_id* argument is the socket identifier in the case of
 480  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
 481  *   constraint for the reserved zone.
 482  * @param flags
 483  *   Flags controlling the behavior of the mempool. See
 484  *   rte_mempool_create() for details.
 485  * @param vaddr
 486  *   Virtual address of the externally allocated memory buffer.
 487  *   Will be used to store mempool objects.
 488  * @param paddr
 489  *   Array of physical addresses of the pages that comprises given memory
 490  *   buffer.
 491  * @param pg_num
 492  *   Number of elements in the paddr array.
 493  * @param pg_shift
 494  *   LOG2 of the physical pages size.
 495  * @return
 496  *   The pointer to the new allocated mempool, on success. NULL on error
 497  *   with rte_errno set appropriately. See rte_mempool_create() for details.
 498  */
 499 struct rte_mempool *
 500 rte_mempool_xmem_create(const char *name, unsigned n, unsigned elt_size,
 501                 unsigned cache_size, unsigned private_data_size,
 502                 rte_mempool_ctor_t *mp_init, void *mp_init_arg,
 503                 rte_mempool_obj_cb_t *obj_init, void *obj_init_arg,
 504                 int socket_id, unsigned flags, void *vaddr,
 505                 const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift);
 506
 507 /**
 508  * Create a new mempool named *name* in memory on Xen Dom0.
 509  *
 510  * This function uses ``rte_mempool_xmem_create()`` to allocate memory. The
 511  * pool contains n elements of elt_size. Its size is set to n.
 512  * All elements of the mempool are allocated together with the mempool header,
 513  * and memory buffer can consist of set of disjoint physical pages.
 514  *
 515  * @param name
 516  *   The name of the mempool.
 517  * @param n
 518  *   The number of elements in the mempool. The optimum size (in terms of
 519  *   memory usage) for a mempool is when n is a power of two minus one:
 520  *   n = (2^q - 1).
 521  * @param elt_size
 522  *   The size of each element.
 523  * @param cache_size
 524  *   If cache_size is non-zero, the rte_mempool library will try to
 525  *   limit the accesses to the common lockless pool, by maintaining a
 526  *   per-lcore object cache. This argument must be lower or equal to
 527  *   CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE. It is advised to choose
 528  *   cache_size to have "n modulo cache_size == 0": if this is
 529  *   not the case, some elements will always stay in the pool and will
 530  *   never be used. The access to the per-lcore table is of course
 531  *   faster than the multi-producer/consumer pool. The cache can be
 532  *   disabled if the cache_size argument is set to 0; it can be useful to
 533  *   avoid losing objects in cache. Note that even if not used, the
 534  *   memory space for cache is always reserved in a mempool structure,
 535  *   except if CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE is set to 0.
 536  * @param private_data_size
 537  *   The size of the private data appended after the mempool
 538  *   structure. This is useful for storing some private data after the
 539  *   mempool structure, as is done for rte_mbuf_pool for example.
 540  * @param mp_init
 541  *   A function pointer that is called for initialization of the pool,
 542  *   before object initialization. The user can initialize the private
 543  *   data in this function if needed. This parameter can be NULL if
 544  *   not needed.
 545  * @param mp_init_arg
 546  *   An opaque pointer to data that can be used in the mempool
 547  *   constructor function.
 548  * @param obj_init
 549  *   A function pointer that is called for each object at
 550  *   initialization of the pool. The user can set some meta data in
 551  *   objects if needed. This parameter can be NULL if not needed.
 552  *   The obj_init() function takes the mempool pointer, the init_arg,
 553  *   the object pointer and the object number as parameters.
 554  * @param obj_init_arg
 555  *   An opaque pointer to data that can be used as an argument for
 556  *   each call to the object constructor function.
 557  * @param socket_id
 558  *   The *socket_id* argument is the socket identifier in the case of
 559  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
 560  *   constraint for the reserved zone.
 561  * @param flags
 562  *   The *flags* arguments is an OR of following flags:
 563  *   - MEMPOOL_F_NO_SPREAD: By default, objects addresses are spread
 564  *     between channels in RAM: the pool allocator will add padding
 565  *     between objects depending on the hardware configuration. See
 566  *     Memory alignment constraints for details. If this flag is set,
 567  *     the allocator will just align them to a cache line.
 568  *   - MEMPOOL_F_NO_CACHE_ALIGN: By default, the returned objects are
 569  *     cache-aligned. This flag removes this constraint, and no
 570  *     padding will be present between objects. This flag implies
 571  *     MEMPOOL_F_NO_SPREAD.
 572  *   - MEMPOOL_F_SP_PUT: If this flag is set, the default behavior
 573  *     when using rte_mempool_put() or rte_mempool_put_bulk() is
 574  *     "single-producer". Otherwise, it is "multi-producers".
 575  *   - MEMPOOL_F_SC_GET: If this flag is set, the default behavior
 576  *     when using rte_mempool_get() or rte_mempool_get_bulk() is
 577  *     "single-consumer". Otherwise, it is "multi-consumers".
 578  * @return
 579  *   The pointer to the new allocated mempool, on success. NULL on error
 580  *   with rte_errno set appropriately. Possible rte_errno values include:
 581  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
 582  *    - E_RTE_SECONDARY - function was called from a secondary process instance
 583  *    - EINVAL - cache size provided is too large
 584  *    - ENOSPC - the maximum number of memzones has already been allocated
 585  *    - EEXIST - a memzone with the same name already exists
 586  *    - ENOMEM - no appropriate memory area found in which to create memzone
 587  */
 588 struct rte_mempool *
 589 rte_dom0_mempool_create(const char *name, unsigned n, unsigned elt_size,
 590                 unsigned cache_size, unsigned private_data_size,
 591                 rte_mempool_ctor_t *mp_init, void *mp_init_arg,
 592                 rte_mempool_obj_cb_t *obj_init, void *obj_init_arg,
 593                 int socket_id, unsigned flags);
 594
 595
 596 /**
 597  * Call a function for each mempool element
 598  *
 599  * Iterate across all objects attached to a rte_mempool and call the
 600  * callback function on it.
 601  *
 602  * @param mp
 603  *   A pointer to an initialized mempool.
 604  * @param obj_cb
 605  *   A function pointer that is called for each object.
 606  * @param obj_cb_arg
 607  *   An opaque pointer passed to the callback function.
 608  * @return
 609  *   Number of objects iterated.
 610  */
 611 uint32_t rte_mempool_obj_iter(struct rte_mempool *mp,
 612         rte_mempool_obj_cb_t *obj_cb, void *obj_cb_arg);
 613
 614 /**
 615  * Call a function for each mempool memory chunk
 616  *
 617  * Iterate across all memory chunks attached to a rte_mempool and call
 618  * the callback function on it.
 619  *
 620  * @param mp
 621  *   A pointer to an initialized mempool.
 622  * @param mem_cb
 623  *   A function pointer that is called for each memory chunk.
 624  * @param mem_cb_arg
 625  *   An opaque pointer passed to the callback function.
 626  * @return
 627  *   Number of memory chunks iterated.
 628  */
 629 uint32_t rte_mempool_mem_iter(struct rte_mempool *mp,
 630         rte_mempool_mem_cb_t *mem_cb, void *mem_cb_arg);
 631
 632 /**
 633  * Dump the status of the mempool to the console.
 634  *
 635  * @param f
 636  *   A pointer to a file for output
 637  * @param mp
 638  *   A pointer to the mempool structure.
 639  */
 640 void rte_mempool_dump(FILE *f, struct rte_mempool *mp);
 641
 642 /**
 643  * @internal Put several objects back in the mempool; used internally.
 644  * @param mp
 645  *   A pointer to the mempool structure.
 646  * @param obj_table
 647  *   A pointer to a table of void * pointers (objects).
 648  * @param n
 649  *   The number of objects to store back in the mempool, must be strictly
 650  *   positive.
 651  * @param is_mp
 652  *   Mono-producer (0) or multi-producers (1).
 653  */
 654 static inline void __attribute__((always_inline))
 655 __mempool_put_bulk(struct rte_mempool *mp, void * const *obj_table,
 656                     unsigned n, int is_mp)
 657 {
 658         struct rte_mempool_cache *cache;
 659         uint32_t index;
 660         void **cache_objs;
 661         unsigned lcore_id = rte_lcore_id();
 662         uint32_t cache_size = mp->cache_size;
 663         uint32_t flushthresh = mp->cache_flushthresh;
 664
 665         /* increment stat now, adding in mempool always success */
 666         __MEMPOOL_STAT_ADD(mp, put, n);
 667
 668         /* cache is not enabled or single producer or non-EAL thread */
 669         if (unlikely(cache_size == 0 || is_mp == 0 ||
 670                      lcore_id >= RTE_MAX_LCORE))
 671                 goto ring_enqueue;
 672
 673         /* Go straight to ring if put would overflow mem allocated for cache */
 674         if (unlikely(n > RTE_MEMPOOL_CACHE_MAX_SIZE))
 675                 goto ring_enqueue;
 676
 677         cache = &mp->local_cache[lcore_id];
 678         cache_objs = &cache->objs[cache->len];
 679
 680         /*
 681          * The cache follows the following algorithm
 682          *   1. Add the objects to the cache
 683          *   2. Anything greater than the cache min value (if it crosses the
 684          *   cache flush threshold) is flushed to the ring.
 685          */
 686
 687         /* Add elements back into the cache */
 688         for (index = 0; index < n; ++index, obj_table++)
 689                 cache_objs[index] = *obj_table;
 690
 691         cache->len += n;
 692
 693         if (cache->len >= flushthresh) {
 694                 rte_ring_mp_enqueue_bulk(mp->ring, &cache->objs[cache_size],
 695                                 cache->len - cache_size);
 696                 cache->len = cache_size;
 697         }
 698
 699         return;
 700
 701 ring_enqueue:
 702
 703         /* push remaining objects in ring */
 704 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 705         if (is_mp) {
 706                 if (rte_ring_mp_enqueue_bulk(mp->ring, obj_table, n) < 0)
 707                         rte_panic("cannot put objects in mempool\n");
 708         }
 709         else {
 710                 if (rte_ring_sp_enqueue_bulk(mp->ring, obj_table, n) < 0)
 711                         rte_panic("cannot put objects in mempool\n");
 712         }
 713 #else
 714         if (is_mp)
 715                 rte_ring_mp_enqueue_bulk(mp->ring, obj_table, n);
 716         else
 717                 rte_ring_sp_enqueue_bulk(mp->ring, obj_table, n);
 718 #endif
 719 }
 720
 721
 722 /**
 723  * Put several objects back in the mempool (multi-producers safe).
 724  *
 725  * @param mp
 726  *   A pointer to the mempool structure.
 727  * @param obj_table
 728  *   A pointer to a table of void * pointers (objects).
 729  * @param n
 730  *   The number of objects to add in the mempool from the obj_table.
 731  */
 732 static inline void __attribute__((always_inline))
 733 rte_mempool_mp_put_bulk(struct rte_mempool *mp, void * const *obj_table,
 734                         unsigned n)
 735 {
 736         __mempool_check_cookies(mp, obj_table, n, 0);
 737         __mempool_put_bulk(mp, obj_table, n, 1);
 738 }
 739
 740 /**
 741  * Put several objects back in the mempool (NOT multi-producers safe).
 742  *
 743  * @param mp
 744  *   A pointer to the mempool structure.
 745  * @param obj_table
 746  *   A pointer to a table of void * pointers (objects).
 747  * @param n
 748  *   The number of objects to add in the mempool from obj_table.
 749  */
 750 static inline void
 751 rte_mempool_sp_put_bulk(struct rte_mempool *mp, void * const *obj_table,
 752                         unsigned n)
 753 {
 754         __mempool_check_cookies(mp, obj_table, n, 0);
 755         __mempool_put_bulk(mp, obj_table, n, 0);
 756 }
 757
 758 /**
 759  * Put several objects back in the mempool.
 760  *
 761  * This function calls the multi-producer or the single-producer
 762  * version depending on the default behavior that was specified at
 763  * mempool creation time (see flags).
 764  *
 765  * @param mp
 766  *   A pointer to the mempool structure.
 767  * @param obj_table
 768  *   A pointer to a table of void * pointers (objects).
 769  * @param n
 770  *   The number of objects to add in the mempool from obj_table.
 771  */
 772 static inline void __attribute__((always_inline))
 773 rte_mempool_put_bulk(struct rte_mempool *mp, void * const *obj_table,
 774                      unsigned n)
 775 {
 776         __mempool_check_cookies(mp, obj_table, n, 0);
 777         __mempool_put_bulk(mp, obj_table, n, !(mp->flags & MEMPOOL_F_SP_PUT));
 778 }
 779
 780 /**
 781  * Put one object in the mempool (multi-producers safe).
 782  *
 783  * @param mp
 784  *   A pointer to the mempool structure.
 785  * @param obj
 786  *   A pointer to the object to be added.
 787  */
 788 static inline void __attribute__((always_inline))
 789 rte_mempool_mp_put(struct rte_mempool *mp, void *obj)
 790 {
 791         rte_mempool_mp_put_bulk(mp, &obj, 1);
 792 }
 793
 794 /**
 795  * Put one object back in the mempool (NOT multi-producers safe).
 796  *
 797  * @param mp
 798  *   A pointer to the mempool structure.
 799  * @param obj
 800  *   A pointer to the object to be added.
 801  */
 802 static inline void __attribute__((always_inline))
 803 rte_mempool_sp_put(struct rte_mempool *mp, void *obj)
 804 {
 805         rte_mempool_sp_put_bulk(mp, &obj, 1);
 806 }
 807
 808 /**
 809  * Put one object back in the mempool.
 810  *
 811  * This function calls the multi-producer or the single-producer
 812  * version depending on the default behavior that was specified at
 813  * mempool creation time (see flags).
 814  *
 815  * @param mp
 816  *   A pointer to the mempool structure.
 817  * @param obj
 818  *   A pointer to the object to be added.
 819  */
 820 static inline void __attribute__((always_inline))
 821 rte_mempool_put(struct rte_mempool *mp, void *obj)
 822 {
 823         rte_mempool_put_bulk(mp, &obj, 1);
 824 }
 825
 826 /**
 827  * @internal Get several objects from the mempool; used internally.
 828  * @param mp
 829  *   A pointer to the mempool structure.
 830  * @param obj_table
 831  *   A pointer to a table of void * pointers (objects).
 832  * @param n
 833  *   The number of objects to get, must be strictly positive.
 834  * @param is_mc
 835  *   Mono-consumer (0) or multi-consumers (1).
 836  * @return
 837  *   - >=0: Success; number of objects supplied.
 838  *   - <0: Error; code of ring dequeue function.
 839  */
 840 static inline int __attribute__((always_inline))
 841 __mempool_get_bulk(struct rte_mempool *mp, void **obj_table,
 842                    unsigned n, int is_mc)
 843 {
 844         int ret;
 845         struct rte_mempool_cache *cache;
 846         uint32_t index, len;
 847         void **cache_objs;
 848         unsigned lcore_id = rte_lcore_id();
 849         uint32_t cache_size = mp->cache_size;
 850
 851         /* cache is not enabled or single consumer */
 852         if (unlikely(cache_size == 0 || is_mc == 0 ||
 853                      n >= cache_size || lcore_id >= RTE_MAX_LCORE))
 854                 goto ring_dequeue;
 855
 856         cache = &mp->local_cache[lcore_id];
 857         cache_objs = cache->objs;
 858
 859         /* Can this be satisfied from the cache? */
 860         if (cache->len < n) {
 861                 /* No. Backfill the cache first, and then fill from it */
 862                 uint32_t req = n + (cache_size - cache->len);
 863
 864                 /* How many do we require i.e. number to fill the cache + the request */
 865                 ret = rte_ring_mc_dequeue_bulk(mp->ring, &cache->objs[cache->len], req);
 866                 if (unlikely(ret < 0)) {
 867                         /*
 868                          * In the offchance that we are buffer constrained,
 869                          * where we are not able to allocate cache + n, go to
 870                          * the ring directly. If that fails, we are truly out of
 871                          * buffers.
 872                          */
 873                         goto ring_dequeue;
 874                 }
 875
 876                 cache->len += req;
 877         }
 878
 879         /* Now fill in the response ... */
 880         for (index = 0, len = cache->len - 1; index < n; ++index, len--, obj_table++)
 881                 *obj_table = cache_objs[len];
 882
 883         cache->len -= n;
 884
 885         __MEMPOOL_STAT_ADD(mp, get_success, n);
 886
 887         return 0;
 888
 889 ring_dequeue:
 890
 891         /* get remaining objects from ring */
 892         if (is_mc)
 893                 ret = rte_ring_mc_dequeue_bulk(mp->ring, obj_table, n);
 894         else
 895                 ret = rte_ring_sc_dequeue_bulk(mp->ring, obj_table, n);
 896
 897         if (ret < 0)
 898                 __MEMPOOL_STAT_ADD(mp, get_fail, n);
 899         else
 900                 __MEMPOOL_STAT_ADD(mp, get_success, n);
 901
 902         return ret;
 903 }
 904
 905 /**
 906  * Get several objects from the mempool (multi-consumers safe).
 907  *
 908  * If cache is enabled, objects will be retrieved first from cache,
 909  * subsequently from the common pool. Note that it can return -ENOENT when
 910  * the local cache and common pool are empty, even if cache from other
 911  * lcores are full.
 912  *
 913  * @param mp
 914  *   A pointer to the mempool structure.
 915  * @param obj_table
 916  *   A pointer to a table of void * pointers (objects) that will be filled.
 917  * @param n
 918  *   The number of objects to get from mempool to obj_table.
 919  * @return
 920  *   - 0: Success; objects taken.
 921  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
 922  */
 923 static inline int __attribute__((always_inline))
 924 rte_mempool_mc_get_bulk(struct rte_mempool *mp, void **obj_table, unsigned n)
 925 {
 926         int ret;
 927         ret = __mempool_get_bulk(mp, obj_table, n, 1);
 928         if (ret == 0)
 929                 __mempool_check_cookies(mp, obj_table, n, 1);
 930         return ret;
 931 }
 932
 933 /**
 934  * Get several objects from the mempool (NOT multi-consumers safe).
 935  *
 936  * If cache is enabled, objects will be retrieved first from cache,
 937  * subsequently from the common pool. Note that it can return -ENOENT when
 938  * the local cache and common pool are empty, even if cache from other
 939  * lcores are full.
 940  *
 941  * @param mp
 942  *   A pointer to the mempool structure.
 943  * @param obj_table
 944  *   A pointer to a table of void * pointers (objects) that will be filled.
 945  * @param n
 946  *   The number of objects to get from the mempool to obj_table.
 947  * @return
 948  *   - 0: Success; objects taken.
 949  *   - -ENOENT: Not enough entries in the mempool; no object is
 950  *     retrieved.
 951  */
 952 static inline int __attribute__((always_inline))
 953 rte_mempool_sc_get_bulk(struct rte_mempool *mp, void **obj_table, unsigned n)
 954 {
 955         int ret;
 956         ret = __mempool_get_bulk(mp, obj_table, n, 0);
 957         if (ret == 0)
 958                 __mempool_check_cookies(mp, obj_table, n, 1);
 959         return ret;
 960 }
 961
 962 /**
 963  * Get several objects from the mempool.
 964  *
 965  * This function calls the multi-consumers or the single-consumer
 966  * version, depending on the default behaviour that was specified at
 967  * mempool creation time (see flags).
 968  *
 969  * If cache is enabled, objects will be retrieved first from cache,
 970  * subsequently from the common pool. Note that it can return -ENOENT when
 971  * the local cache and common pool are empty, even if cache from other
 972  * lcores are full.
 973  *
 974  * @param mp
 975  *   A pointer to the mempool structure.
 976  * @param obj_table
 977  *   A pointer to a table of void * pointers (objects) that will be filled.
 978  * @param n
 979  *   The number of objects to get from the mempool to obj_table.
 980  * @return
 981  *   - 0: Success; objects taken
 982  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
 983  */
 984 static inline int __attribute__((always_inline))
 985 rte_mempool_get_bulk(struct rte_mempool *mp, void **obj_table, unsigned n)
 986 {
 987         int ret;
 988         ret = __mempool_get_bulk(mp, obj_table, n,
 989                                  !(mp->flags & MEMPOOL_F_SC_GET));
 990         if (ret == 0)
 991                 __mempool_check_cookies(mp, obj_table, n, 1);
 992         return ret;
 993 }
 994
 995 /**
 996  * Get one object from the mempool (multi-consumers safe).
 997  *
 998  * If cache is enabled, objects will be retrieved first from cache,
 999  * subsequently from the common pool. Note that it can return -ENOENT when
1000  * the local cache and common pool are empty, even if cache from other
1001  * lcores are full.
1002  *
1003  * @param mp
1004  *   A pointer to the mempool structure.
1005  * @param obj_p
1006  *   A pointer to a void * pointer (object) that will be filled.
1007  * @return
1008  *   - 0: Success; objects taken.
1009  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
1010  */
1011 static inline int __attribute__((always_inline))
1012 rte_mempool_mc_get(struct rte_mempool *mp, void **obj_p)
1013 {
1014         return rte_mempool_mc_get_bulk(mp, obj_p, 1);
1015 }
1016
1017 /**
1018  * Get one object from the mempool (NOT multi-consumers safe).
1019  *
1020  * If cache is enabled, objects will be retrieved first from cache,
1021  * subsequently from the common pool. Note that it can return -ENOENT when
1022  * the local cache and common pool are empty, even if cache from other
1023  * lcores are full.
1024  *
1025  * @param mp
1026  *   A pointer to the mempool structure.
1027  * @param obj_p
1028  *   A pointer to a void * pointer (object) that will be filled.
1029  * @return
1030  *   - 0: Success; objects taken.
1031  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
1032  */
1033 static inline int __attribute__((always_inline))
1034 rte_mempool_sc_get(struct rte_mempool *mp, void **obj_p)
1035 {
1036         return rte_mempool_sc_get_bulk(mp, obj_p, 1);
1037 }
1038
1039 /**
1040  * Get one object from the mempool.
1041  *
1042  * This function calls the multi-consumers or the single-consumer
1043  * version, depending on the default behavior that was specified at
1044  * mempool creation (see flags).
1045  *
1046  * If cache is enabled, objects will be retrieved first from cache,
1047  * subsequently from the common pool. Note that it can return -ENOENT when
1048  * the local cache and common pool are empty, even if cache from other
1049  * lcores are full.
1050  *
1051  * @param mp
1052  *   A pointer to the mempool structure.
1053  * @param obj_p
1054  *   A pointer to a void * pointer (object) that will be filled.
1055  * @return
1056  *   - 0: Success; objects taken.
1057  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
1058  */
1059 static inline int __attribute__((always_inline))
1060 rte_mempool_get(struct rte_mempool *mp, void **obj_p)
1061 {
1062         return rte_mempool_get_bulk(mp, obj_p, 1);
1063 }
1064
1065 /**
1066  * Return the number of entries in the mempool.
1067  *
1068  * When cache is enabled, this function has to browse the length of
1069  * all lcores, so it should not be used in a data path, but only for
1070  * debug purposes.
1071  *
1072  * @param mp
1073  *   A pointer to the mempool structure.
1074  * @return
1075  *   The number of entries in the mempool.
1076  */
1077 unsigned rte_mempool_count(const struct rte_mempool *mp);
1078
1079 /**
1080  * Return the number of free entries in the mempool ring.
1081  * i.e. how many entries can be freed back to the mempool.
1082  *
1083  * NOTE: This corresponds to the number of elements *allocated* from the
1084  * memory pool, not the number of elements in the pool itself. To count
1085  * the number elements currently available in the pool, use "rte_mempool_count"
1086  *
1087  * When cache is enabled, this function has to browse the length of
1088  * all lcores, so it should not be used in a data path, but only for
1089  * debug purposes.
1090  *
1091  * @param mp
1092  *   A pointer to the mempool structure.
1093  * @return
1094  *   The number of free entries in the mempool.
1095  */
1096 static inline unsigned
1097 rte_mempool_free_count(const struct rte_mempool *mp)
1098 {
1099         return mp->size - rte_mempool_count(mp);
1100 }
1101
1102 /**
1103  * Test if the mempool is full.
1104  *
1105  * When cache is enabled, this function has to browse the length of all
1106  * lcores, so it should not be used in a data path, but only for debug
1107  * purposes.
1108  *
1109  * @param mp
1110  *   A pointer to the mempool structure.
1111  * @return
1112  *   - 1: The mempool is full.
1113  *   - 0: The mempool is not full.
1114  */
1115 static inline int
1116 rte_mempool_full(const struct rte_mempool *mp)
1117 {
1118         return !!(rte_mempool_count(mp) == mp->size);
1119 }
1120
1121 /**
1122  * Test if the mempool is empty.
1123  *
1124  * When cache is enabled, this function has to browse the length of all
1125  * lcores, so it should not be used in a data path, but only for debug
1126  * purposes.
1127  *
1128  * @param mp
1129  *   A pointer to the mempool structure.
1130  * @return
1131  *   - 1: The mempool is empty.
1132  *   - 0: The mempool is not empty.
1133  */
1134 static inline int
1135 rte_mempool_empty(const struct rte_mempool *mp)
1136 {
1137         return !!(rte_mempool_count(mp) == 0);
1138 }
1139
1140 /**
1141  * Return the physical address of elt, which is an element of the pool mp.
1142  *
1143  * @param mp
1144  *   A pointer to the mempool structure.
1145  * @param elt
1146  *   A pointer (virtual address) to the element of the pool.
1147  * @return
1148  *   The physical address of the elt element.
1149  */
1150 static inline phys_addr_t
1151 rte_mempool_virt2phy(__rte_unused const struct rte_mempool *mp, const void *elt)
1152 {
1153         if (rte_eal_has_hugepages()) {
1154                 const struct rte_mempool_objhdr *hdr;
1155                 hdr = (const struct rte_mempool_objhdr *)RTE_PTR_SUB(elt,
1156                         sizeof(*hdr));
1157                 return hdr->physaddr;
1158         } else {
1159                 /*
1160                  * If huge pages are disabled, we cannot assume the
1161                  * memory region to be physically contiguous.
1162                  * Lookup for each element.
1163                  */
1164                 return rte_mem_virt2phy(elt);
1165         }
1166 }
1167
1168 /**
1169  * Check the consistency of mempool objects.
1170  *
1171  * Verify the coherency of fields in the mempool structure. Also check
1172  * that the cookies of mempool objects (even the ones that are not
1173  * present in pool) have a correct value. If not, a panic will occur.
1174  *
1175  * @param mp
1176  *   A pointer to the mempool structure.
1177  */
1178 void rte_mempool_audit(struct rte_mempool *mp);
1179
1180 /**
1181  * Return a pointer to the private data in an mempool structure.
1182  *
1183  * @param mp
1184  *   A pointer to the mempool structure.
1185  * @return
1186  *   A pointer to the private data.
1187  */
1188 static inline void *rte_mempool_get_priv(struct rte_mempool *mp)
1189 {
1190         return (char *)mp +
1191                 MEMPOOL_HEADER_SIZE(mp, mp->cache_size);
1192 }
1193
1194 /**
1195  * Dump the status of all mempools on the console
1196  *
1197  * @param f
1198  *   A pointer to a file for output
1199  */
1200 void rte_mempool_list_dump(FILE *f);
1201
1202 /**
1203  * Search a mempool from its name
1204  *
1205  * @param name
1206  *   The name of the mempool.
1207  * @return
1208  *   The pointer to the mempool matching the name, or NULL if not found.
1209  *   NULL on error
1210  *   with rte_errno set appropriately. Possible rte_errno values include:
1211  *    - ENOENT - required entry not available to return.
1212  *
1213  */
1214 struct rte_mempool *rte_mempool_lookup(const char *name);
1215
1216 /**
1217  * Get the header, trailer and total size of a mempool element.
1218  *
1219  * Given a desired size of the mempool element and mempool flags,
1220  * calculates header, trailer, body and total sizes of the mempool object.
1221  *
1222  * @param elt_size
1223  *   The size of each element, without header and trailer.
1224  * @param flags
1225  *   The flags used for the mempool creation.
1226  *   Consult rte_mempool_create() for more information about possible values.
1227  *   The size of each element.
1228  * @param sz
1229  *   The calculated detailed size the mempool object. May be NULL.
1230  * @return
1231  *   Total size of the mempool object.
1232  */
1233 uint32_t rte_mempool_calc_obj_size(uint32_t elt_size, uint32_t flags,
1234         struct rte_mempool_objsz *sz);
1235
1236 /**
1237  * Get the size of memory required to store mempool elements.
1238  *
1239  * Calculate the maximum amount of memory required to store given number
1240  * of objects. Assume that the memory buffer will be aligned at page
1241  * boundary.
1242  *
1243  * Note that if object size is bigger then page size, then it assumes
1244  * that pages are grouped in subsets of physically continuous pages big
1245  * enough to store at least one object.
1246  *
1247  * @param elt_num
1248  *   Number of elements.
1249  * @param total_elt_sz
1250  *   The size of each element, including header and trailer, as returned
1251  *   by rte_mempool_calc_obj_size().
1252  * @param pg_shift
1253  *   LOG2 of the physical pages size. If set to 0, ignore page boundaries.
1254  * @return
1255  *   Required memory size aligned at page boundary.
1256  */
1257 size_t rte_mempool_xmem_size(uint32_t elt_num, size_t total_elt_sz,
1258         uint32_t pg_shift);
1259
1260 /**
1261  * Get the size of memory required to store mempool elements.
1262  *
1263  * Calculate how much memory would be actually required with the given
1264  * memory footprint to store required number of objects.
1265  *
1266  * @param vaddr
1267  *   Virtual address of the externally allocated memory buffer.
1268  *   Will be used to store mempool objects.
1269  * @param elt_num
1270  *   Number of elements.
1271  * @param total_elt_sz
1272  *   The size of each element, including header and trailer, as returned
1273  *   by rte_mempool_calc_obj_size().
1274  * @param paddr
1275  *   Array of physical addresses of the pages that comprises given memory
1276  *   buffer.
1277  * @param pg_num
1278  *   Number of elements in the paddr array.
1279  * @param pg_shift
1280  *   LOG2 of the physical pages size.
1281  * @return
1282  *   On success, the number of bytes needed to store given number of
1283  *   objects, aligned to the given page size. If the provided memory
1284  *   buffer is too small, return a negative value whose absolute value
1285  *   is the actual number of elements that can be stored in that buffer.
1286  */
1287 ssize_t rte_mempool_xmem_usage(void *vaddr, uint32_t elt_num,
1288         size_t total_elt_sz, const phys_addr_t paddr[], uint32_t pg_num,
1289         uint32_t pg_shift);
1290
1291 /**
1292  * Walk list of all memory pools
1293  *
1294  * @param func
1295  *   Iterator function
1296  * @param arg
1297  *   Argument passed to iterator
1298  */
1299 void rte_mempool_walk(void (*func)(struct rte_mempool *, void *arg),
1300                       void *arg);
1301
1302 #ifdef __cplusplus
1303 }
1304 #endif
1305
1306 #endif /* _RTE_MEMPOOL_H_ */