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