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