lib/librte_mempool/rte_mempool.h

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