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 <stdlib.h>
  63 #include <stdint.h>
  64 #include <errno.h>
  65 #include <inttypes.h>
  66 #include <sys/queue.h>
  67
  68 #include <rte_log.h>
  69 #include <rte_debug.h>
  70 #include <rte_lcore.h>
  71 #include <rte_memory.h>
  72 #include <rte_branch_prediction.h>
  73 #include <rte_ring.h>
  74
  75 #ifdef __cplusplus
  76 extern "C" {
  77 #endif
  78
  79 #define RTE_MEMPOOL_HEADER_COOKIE1  0xbadbadbadadd2e55ULL /**< Header cookie. */
  80 #define RTE_MEMPOOL_HEADER_COOKIE2  0xf2eef2eedadd2e55ULL /**< Header cookie. */
  81 #define RTE_MEMPOOL_TRAILER_COOKIE  0xadd2e55badbadbadULL /**< Trailer cookie.*/
  82
  83 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
  84 /**
  85  * A structure that stores the mempool statistics (per-lcore).
  86  */
  87 struct rte_mempool_debug_stats {
  88         uint64_t put_bulk;         /**< Number of puts. */
  89         uint64_t put_objs;         /**< Number of objects successfully put. */
  90         uint64_t get_success_bulk; /**< Successful allocation number. */
  91         uint64_t get_success_objs; /**< Objects successfully allocated. */
  92         uint64_t get_fail_bulk;    /**< Failed allocation number. */
  93         uint64_t get_fail_objs;    /**< Objects that failed to be allocated. */
  94 } __rte_cache_aligned;
  95 #endif
  96
  97 #if RTE_MEMPOOL_CACHE_MAX_SIZE > 0
  98 /**
  99  * A structure that stores a per-core object cache.
 100  */
 101 struct rte_mempool_cache {
 102         unsigned len; /**< Cache len */
 103         /*
 104          * Cache is allocated to this size to allow it to overflow in certain
 105          * cases to avoid needless emptying of cache.
 106          */
 107         void *objs[RTE_MEMPOOL_CACHE_MAX_SIZE * 3]; /**< Cache objects */
 108 } __rte_cache_aligned;
 109 #endif /* RTE_MEMPOOL_CACHE_MAX_SIZE > 0 */
 110
 111 #define RTE_MEMPOOL_NAMESIZE 32 /**< Maximum length of a memory pool. */
 112 #define RTE_MEMPOOL_MZ_PREFIX "MP_"
 113
 114 /* "MP_<name>" */
 115 #define RTE_MEMPOOL_MZ_FORMAT   RTE_MEMPOOL_MZ_PREFIX "%s"
 116
 117 #define RTE_MEMPOOL_OBJ_NAME    RTE_MEMPOOL_MZ_FORMAT
 118
 119 /**
 120  * The RTE mempool structure.
 121  */
 122 struct rte_mempool {
 123         TAILQ_ENTRY(rte_mempool) next;   /**< Next in list. */
 124
 125         char name[RTE_MEMPOOL_NAMESIZE]; /**< Name of mempool. */
 126         struct rte_ring *ring;           /**< Ring to store objects. */
 127         phys_addr_t phys_addr;           /**< Phys. addr. of mempool struct. */
 128         int flags;                       /**< Flags of the mempool. */
 129         uint32_t size;                   /**< Size of the mempool. */
 130         uint32_t cache_size;             /**< Size of per-lcore local cache. */
 131         uint32_t cache_flushthresh;      /**< Threshold before we flush excess elements. */
 132
 133         uint32_t elt_size;               /**< Size of an element. */
 134         uint32_t header_size;            /**< Size of header (before elt). */
 135         uint32_t trailer_size;           /**< Size of trailer (after elt). */
 136
 137         unsigned private_data_size;      /**< Size of private data. */
 138
 139 #if RTE_MEMPOOL_CACHE_MAX_SIZE > 0
 140         /** Per-lcore local cache. */
 141         struct rte_mempool_cache local_cache[RTE_MAX_LCORE];
 142 #endif
 143
 144 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 145         /** Per-lcore statistics. */
 146         struct rte_mempool_debug_stats stats[RTE_MAX_LCORE];
 147 #endif
 148 }  __rte_cache_aligned;
 149
 150 #define MEMPOOL_F_NO_SPREAD      0x0001 /**< Do not spread in memory. */
 151 #define MEMPOOL_F_NO_CACHE_ALIGN 0x0002 /**< Do not align objs on cache lines.*/
 152 #define MEMPOOL_F_SP_PUT         0x0004 /**< Default put is "single-producer".*/
 153 #define MEMPOOL_F_SC_GET         0x0008 /**< Default get is "single-consumer".*/
 154
 155 /**
 156  * @internal When debug is enabled, store some statistics.
 157  * @param mp
 158  *   Pointer to the memory pool.
 159  * @param name
 160  *   Name of the statistics field to increment in the memory pool.
 161  * @param n
 162  *   Number to add to the object-oriented statistics.
 163  */
 164 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 165 #define __MEMPOOL_STAT_ADD(mp, name, n) do {                    \
 166                 unsigned __lcore_id = rte_lcore_id();           \
 167                 mp->stats[__lcore_id].name##_objs += n;         \
 168                 mp->stats[__lcore_id].name##_bulk += 1;         \
 169         } while(0)
 170 #else
 171 #define __MEMPOOL_STAT_ADD(mp, name, n) do {} while(0)
 172 #endif
 173
 174 /**
 175  * @internal Get a pointer to a mempool pointer in the object header.
 176  * @param obj
 177  *   Pointer to object.
 178  * @return
 179  *   The pointer to the mempool from which the object was allocated.
 180  */
 181 static inline struct rte_mempool **__mempool_from_obj(void *obj)
 182 {
 183         struct rte_mempool **mpp;
 184         unsigned off;
 185
 186         off = sizeof(struct rte_mempool *);
 187 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 188         off += sizeof(uint64_t);
 189 #endif
 190         mpp = (struct rte_mempool **)((char *)obj - off);
 191         return mpp;
 192 }
 193
 194 /**
 195  * Return a pointer to the mempool owning this object.
 196  *
 197  * @param obj
 198  *   An object that is owned by a pool. If this is not the case,
 199  *   the behavior is undefined.
 200  * @return
 201  *   A pointer to the mempool structure.
 202  */
 203 static inline const struct rte_mempool *rte_mempool_from_obj(void *obj)
 204 {
 205         struct rte_mempool * const *mpp;
 206         mpp = __mempool_from_obj(obj);
 207         return *mpp;
 208 }
 209
 210 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 211 /* get header cookie value */
 212 static inline uint64_t __mempool_read_header_cookie(const void *obj)
 213 {
 214         return *(const uint64_t *)((const char *)obj - sizeof(uint64_t));
 215 }
 216
 217 /* get trailer cookie value */
 218 static inline uint64_t __mempool_read_trailer_cookie(void *obj)
 219 {
 220         struct rte_mempool **mpp = __mempool_from_obj(obj);
 221         return *(uint64_t *)((char *)obj + (*mpp)->elt_size);
 222 }
 223
 224 /* write header cookie value */
 225 static inline void __mempool_write_header_cookie(void *obj, int free)
 226 {
 227         uint64_t *cookie_p;
 228         cookie_p = (uint64_t *)((char *)obj - sizeof(uint64_t));
 229         if (free == 0)
 230                 *cookie_p = RTE_MEMPOOL_HEADER_COOKIE1;
 231         else
 232                 *cookie_p = RTE_MEMPOOL_HEADER_COOKIE2;
 233
 234 }
 235
 236 /* write trailer cookie value */
 237 static inline void __mempool_write_trailer_cookie(void *obj)
 238 {
 239         uint64_t *cookie_p;
 240         struct rte_mempool **mpp = __mempool_from_obj(obj);
 241         cookie_p = (uint64_t *)((char *)obj + (*mpp)->elt_size);
 242         *cookie_p = RTE_MEMPOOL_TRAILER_COOKIE;
 243 }
 244 #endif /* RTE_LIBRTE_MEMPOOL_DEBUG */
 245
 246 /**
 247  * @internal Check and update cookies or panic.
 248  *
 249  * @param mp
 250  *   Pointer to the memory pool.
 251  * @param obj_table_const
 252  *   Pointer to a table of void * pointers (objects).
 253  * @param n
 254  *   Index of object in object table.
 255  * @param free
 256  *   - 0: object is supposed to be allocated, mark it as free
 257  *   - 1: object is supposed to be free, mark it as allocated
 258  *   - 2: just check that cookie is valid (free or allocated)
 259  */
 260 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 261 #ifndef __INTEL_COMPILER
 262 #pragma GCC diagnostic ignored "-Wcast-qual"
 263 #endif
 264 static inline void __mempool_check_cookies(const struct rte_mempool *mp,
 265                                            void * const *obj_table_const,
 266                                            unsigned n, int free)
 267 {
 268         uint64_t cookie;
 269         void *tmp;
 270         void *obj;
 271         void **obj_table;
 272
 273         /* Force to drop the "const" attribute. This is done only when
 274          * DEBUG is enabled */
 275         tmp = (void *) obj_table_const;
 276         obj_table = (void **) tmp;
 277
 278         while (n--) {
 279                 obj = obj_table[n];
 280
 281                 if (rte_mempool_from_obj(obj) != mp)
 282                         rte_panic("MEMPOOL: object is owned by another "
 283                                   "mempool\n");
 284
 285                 cookie = __mempool_read_header_cookie(obj);
 286
 287                 if (free == 0) {
 288                         if (cookie != RTE_MEMPOOL_HEADER_COOKIE1) {
 289                                 rte_log_set_history(0);
 290                                 RTE_LOG(CRIT, MEMPOOL,
 291                                         "obj=%p, mempool=%p, cookie=%"PRIx64"\n",
 292                                         obj, mp, cookie);
 293                                 rte_panic("MEMPOOL: bad header cookie (put)\n");
 294                         }
 295                         __mempool_write_header_cookie(obj, 1);
 296                 }
 297                 else if (free == 1) {
 298                         if (cookie != RTE_MEMPOOL_HEADER_COOKIE2) {
 299                                 rte_log_set_history(0);
 300                                 RTE_LOG(CRIT, MEMPOOL,
 301                                         "obj=%p, mempool=%p, cookie=%"PRIx64"\n",
 302                                         obj, mp, cookie);
 303                                 rte_panic("MEMPOOL: bad header cookie (get)\n");
 304                         }
 305                         __mempool_write_header_cookie(obj, 0);
 306                 }
 307                 else if (free == 2) {
 308                         if (cookie != RTE_MEMPOOL_HEADER_COOKIE1 &&
 309                             cookie != RTE_MEMPOOL_HEADER_COOKIE2) {
 310                                 rte_log_set_history(0);
 311                                 RTE_LOG(CRIT, MEMPOOL,
 312                                         "obj=%p, mempool=%p, cookie=%"PRIx64"\n",
 313                                         obj, mp, cookie);
 314                                 rte_panic("MEMPOOL: bad header cookie (audit)\n");
 315                         }
 316                 }
 317                 cookie = __mempool_read_trailer_cookie(obj);
 318                 if (cookie != RTE_MEMPOOL_TRAILER_COOKIE) {
 319                         rte_log_set_history(0);
 320                         RTE_LOG(CRIT, MEMPOOL,
 321                                 "obj=%p, mempool=%p, cookie=%"PRIx64"\n",
 322                                 obj, mp, cookie);
 323                         rte_panic("MEMPOOL: bad trailer cookie\n");
 324                 }
 325         }
 326 }
 327 #ifndef __INTEL_COMPILER
 328 #pragma GCC diagnostic error "-Wcast-qual"
 329 #endif
 330 #else
 331 #define __mempool_check_cookies(mp, obj_table_const, n, free) do {} while(0)
 332 #endif /* RTE_LIBRTE_MEMPOOL_DEBUG */
 333
 334 /**
 335  * An object constructor callback function for mempool.
 336  *
 337  * Arguments are the mempool, the opaque pointer given by the user in
 338  * rte_mempool_create(), the pointer to the element and the index of
 339  * the element in the pool.
 340  */
 341 typedef void (rte_mempool_obj_ctor_t)(struct rte_mempool *, void *,
 342                                       void *, unsigned);
 343
 344 /**
 345  * A mempool constructor callback function.
 346  *
 347  * Arguments are the mempool and the opaque pointer given by the user in
 348  * rte_mempool_create().
 349  */
 350 typedef void (rte_mempool_ctor_t)(struct rte_mempool *, void *);
 351
 352 /**
 353  * Creates a new mempool named *name* in memory.
 354  *
 355  * This function uses ``memzone_reserve()`` to allocate memory. The
 356  * pool contains n elements of elt_size. Its size is set to n.
 357  *
 358  * @param name
 359  *   The name of the mempool.
 360  * @param n
 361  *   The number of elements in the mempool. The optimum size (in terms of
 362  *   memory usage) for a mempool is when n is a power of two minus one:
 363  *   n = (2^q - 1).
 364  * @param elt_size
 365  *   The size of each element.
 366  * @param cache_size
 367  *   If cache_size is non-zero, the rte_mempool library will try to
 368  *   limit the accesses to the common lockless pool, by maintaining a
 369  *   per-lcore object cache. This argument must be lower or equal to
 370  *   CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE. It is advised to choose
 371  *   cache_size to have "n modulo cache_size == 0": if this is
 372  *   not the case, some elements will always stay in the pool and will
 373  *   never be used. The access to the per-lcore table is of course
 374  *   faster than the multi-producer/consumer pool. The cache can be
 375  *   disabled if the cache_size argument is set to 0; it can be useful to
 376  *   avoid loosing objects in cache. Note that even if not used, the
 377  *   memory space for cache is always reserved in a mempool structure,
 378  *   except if CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE is set to 0.
 379  * @param private_data_size
 380  *   The size of the private data appended after the mempool
 381  *   structure. This is useful for storing some private data after the
 382  *   mempool structure, as is done for rte_mbuf_pool for example.
 383  * @param mp_init
 384  *   A function pointer that is called for initialization of the pool,
 385  *   before object initialization. The user can initialize the private
 386  *   data in this function if needed. This parameter can be NULL if
 387  *   not needed.
 388  * @param mp_init_arg
 389  *   An opaque pointer to data that can be used in the mempool
 390  *   constructor function.
 391  * @param obj_init
 392  *   A function pointer that is called for each object at
 393  *   initialization of the pool. The user can set some meta data in
 394  *   objects if needed. This parameter can be NULL if not needed.
 395  *   The obj_init() function takes the mempool pointer, the init_arg,
 396  *   the object pointer and the object number as parameters.
 397  * @param obj_init_arg
 398  *   An opaque pointer to data that can be used as an argument for
 399  *   each call to the object constructor function.
 400  * @param socket_id
 401  *   The *socket_id* argument is the socket identifier in the case of
 402  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
 403  *   constraint for the reserved zone.
 404  * @param flags
 405  *   The *flags* arguments is an OR of following flags:
 406  *   - MEMPOOL_F_NO_SPREAD: By default, objects addresses are spread
 407  *     between channels in RAM: the pool allocator will add padding
 408  *     between objects depending on the hardware configuration. See
 409  *     Memory alignment constraints for details. If this flag is set,
 410  *     the allocator will just align them to a cache line.
 411  *   - MEMPOOL_F_NO_CACHE_ALIGN: By default, the returned objects are
 412  *     cache-aligned. This flag removes this constraint, and no
 413  *     padding will be present between objects. This flag implies
 414  *     MEMPOOL_F_NO_SPREAD.
 415  *   - MEMPOOL_F_SP_PUT: If this flag is set, the default behavior
 416  *     when using rte_mempool_put() or rte_mempool_put_bulk() is
 417  *     "single-producer". Otherwise, it is "multi-producers".
 418  *   - MEMPOOL_F_SC_GET: If this flag is set, the default behavior
 419  *     when using rte_mempool_get() or rte_mempool_get_bulk() is
 420  *     "single-consumer". Otherwise, it is "multi-consumers".
 421  * @return
 422  *   The pointer to the new allocated mempool, on success. NULL on error
 423  *   with rte_errno set appropriately. Possible rte_errno values include:
 424  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
 425  *    - E_RTE_SECONDARY - function was called from a secondary process instance
 426  *    - E_RTE_NO_TAILQ - no tailq list could be got for the ring or mempool list
 427  *    - EINVAL - cache size provided is too large
 428  *    - ENOSPC - the maximum number of memzones has already been allocated
 429  *    - EEXIST - a memzone with the same name already exists
 430  *    - ENOMEM - no appropriate memory area found in which to create memzone
 431  */
 432 struct rte_mempool *
 433 rte_mempool_create(const char *name, unsigned n, unsigned elt_size,
 434                    unsigned cache_size, unsigned private_data_size,
 435                    rte_mempool_ctor_t *mp_init, void *mp_init_arg,
 436                    rte_mempool_obj_ctor_t *obj_init, void *obj_init_arg,
 437                    int socket_id, unsigned flags);
 438
 439 /**
 440  * Dump the status of the mempool to the console.
 441  *
 442  * @param mp
 443  *   A pointer to the mempool structure.
 444  */
 445 void rte_mempool_dump(const struct rte_mempool *mp);
 446
 447 /**
 448  * @internal Put several objects back in the mempool; used internally.
 449  * @param mp
 450  *   A pointer to the mempool structure.
 451  * @param obj_table
 452  *   A pointer to a table of void * pointers (objects).
 453  * @param n
 454  *   The number of objects to store back in the mempool, must be strictly
 455  *   positive.
 456  * @param is_mp
 457  *   Mono-producer (0) or multi-producers (1).
 458  */
 459 static inline void __attribute__((always_inline))
 460 __mempool_put_bulk(struct rte_mempool *mp, void * const *obj_table,
 461                     unsigned n, int is_mp)
 462 {
 463 #if RTE_MEMPOOL_CACHE_MAX_SIZE > 0
 464         struct rte_mempool_cache *cache;
 465         uint32_t index;
 466         void **cache_objs;
 467         unsigned lcore_id = rte_lcore_id();
 468         uint32_t cache_size = mp->cache_size;
 469         uint32_t flushthresh = mp->cache_flushthresh;
 470 #endif /* RTE_MEMPOOL_CACHE_MAX_SIZE > 0 */
 471
 472         /* increment stat now, adding in mempool always success */
 473         __MEMPOOL_STAT_ADD(mp, put, n);
 474
 475 #if RTE_MEMPOOL_CACHE_MAX_SIZE > 0
 476         /* cache is not enabled or single producer */
 477         if (unlikely(cache_size == 0 || is_mp == 0))
 478                 goto ring_enqueue;
 479
 480         /* Go straight to ring if put would overflow mem allocated for cache */
 481         if (unlikely(n > RTE_MEMPOOL_CACHE_MAX_SIZE))
 482                 goto ring_enqueue;
 483
 484         cache = &mp->local_cache[lcore_id];
 485         cache_objs = &cache->objs[cache->len];
 486
 487         /*
 488          * The cache follows the following algorithm
 489          *   1. Add the objects to the cache
 490          *   2. Anything greater than the cache min value (if it crosses the
 491          *   cache flush threshold) is flushed to the ring.
 492          */
 493
 494         /* Add elements back into the cache */
 495         for (index = 0; index < n; ++index, obj_table++)
 496                 cache_objs[index] = *obj_table;
 497
 498         cache->len += n;
 499
 500         if (cache->len >= flushthresh) {
 501                 rte_ring_mp_enqueue_bulk(mp->ring, &cache->objs[cache_size],
 502                                 cache->len - cache_size);
 503                 cache->len = cache_size;
 504         }
 505
 506         return;
 507
 508 ring_enqueue:
 509 #endif /* RTE_MEMPOOL_CACHE_MAX_SIZE > 0 */
 510
 511         /* push remaining objects in ring */
 512 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 513         if (is_mp) {
 514                 if (rte_ring_mp_enqueue_bulk(mp->ring, obj_table, n) < 0)
 515                         rte_panic("cannot put objects in mempool\n");
 516         }
 517         else {
 518                 if (rte_ring_sp_enqueue_bulk(mp->ring, obj_table, n) < 0)
 519                         rte_panic("cannot put objects in mempool\n");
 520         }
 521 #else
 522         if (is_mp)
 523                 rte_ring_mp_enqueue_bulk(mp->ring, obj_table, n);
 524         else
 525                 rte_ring_sp_enqueue_bulk(mp->ring, obj_table, n);
 526 #endif
 527 }
 528
 529
 530 /**
 531  * Put several objects back in the mempool (multi-producers safe).
 532  *
 533  * @param mp
 534  *   A pointer to the mempool structure.
 535  * @param obj_table
 536  *   A pointer to a table of void * pointers (objects).
 537  * @param n
 538  *   The number of objects to add in the mempool from the obj_table.
 539  */
 540 static inline void __attribute__((always_inline))
 541 rte_mempool_mp_put_bulk(struct rte_mempool *mp, void * const *obj_table,
 542                         unsigned n)
 543 {
 544         __mempool_check_cookies(mp, obj_table, n, 0);
 545         __mempool_put_bulk(mp, obj_table, n, 1);
 546 }
 547
 548 /**
 549  * Put several objects back in the mempool (NOT multi-producers safe).
 550  *
 551  * @param mp
 552  *   A pointer to the mempool structure.
 553  * @param obj_table
 554  *   A pointer to a table of void * pointers (objects).
 555  * @param n
 556  *   The number of objects to add in the mempool from obj_table.
 557  */
 558 static inline void
 559 rte_mempool_sp_put_bulk(struct rte_mempool *mp, void * const *obj_table,
 560                         unsigned n)
 561 {
 562         __mempool_check_cookies(mp, obj_table, n, 0);
 563         __mempool_put_bulk(mp, obj_table, n, 0);
 564 }
 565
 566 /**
 567  * Put several objects back in the mempool.
 568  *
 569  * This function calls the multi-producer or the single-producer
 570  * version depending on the default behavior that was specified at
 571  * mempool creation time (see flags).
 572  *
 573  * @param mp
 574  *   A pointer to the mempool structure.
 575  * @param obj_table
 576  *   A pointer to a table of void * pointers (objects).
 577  * @param n
 578  *   The number of objects to add in the mempool from obj_table.
 579  */
 580 static inline void __attribute__((always_inline))
 581 rte_mempool_put_bulk(struct rte_mempool *mp, void * const *obj_table,
 582                      unsigned n)
 583 {
 584         __mempool_check_cookies(mp, obj_table, n, 0);
 585         __mempool_put_bulk(mp, obj_table, n, !(mp->flags & MEMPOOL_F_SP_PUT));
 586 }
 587
 588 /**
 589  * Put one object in the mempool (multi-producers safe).
 590  *
 591  * @param mp
 592  *   A pointer to the mempool structure.
 593  * @param obj
 594  *   A pointer to the object to be added.
 595  */
 596 static inline void __attribute__((always_inline))
 597 rte_mempool_mp_put(struct rte_mempool *mp, void *obj)
 598 {
 599         rte_mempool_mp_put_bulk(mp, &obj, 1);
 600 }
 601
 602 /**
 603  * Put one object back in the mempool (NOT multi-producers safe).
 604  *
 605  * @param mp
 606  *   A pointer to the mempool structure.
 607  * @param obj
 608  *   A pointer to the object to be added.
 609  */
 610 static inline void __attribute__((always_inline))
 611 rte_mempool_sp_put(struct rte_mempool *mp, void *obj)
 612 {
 613         rte_mempool_sp_put_bulk(mp, &obj, 1);
 614 }
 615
 616 /**
 617  * Put one object back in the mempool.
 618  *
 619  * This function calls the multi-producer or the single-producer
 620  * version depending on the default behavior that was specified at
 621  * mempool creation time (see flags).
 622  *
 623  * @param mp
 624  *   A pointer to the mempool structure.
 625  * @param obj
 626  *   A pointer to the object to be added.
 627  */
 628 static inline void __attribute__((always_inline))
 629 rte_mempool_put(struct rte_mempool *mp, void *obj)
 630 {
 631         rte_mempool_put_bulk(mp, &obj, 1);
 632 }
 633
 634 /**
 635  * @internal Get several objects from the mempool; used internally.
 636  * @param mp
 637  *   A pointer to the mempool structure.
 638  * @param obj_table
 639  *   A pointer to a table of void * pointers (objects).
 640  * @param n
 641  *   The number of objects to get, must be strictly positive.
 642  * @param is_mc
 643  *   Mono-consumer (0) or multi-consumers (1).
 644  * @return
 645  *   - >=0: Success; number of objects supplied.
 646  *   - <0: Error; code of ring dequeue function.
 647  */
 648 static inline int __attribute__((always_inline))
 649 __mempool_get_bulk(struct rte_mempool *mp, void **obj_table,
 650                    unsigned n, int is_mc)
 651 {
 652         int ret;
 653 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
 654         unsigned n_orig = n;
 655 #endif
 656 #if RTE_MEMPOOL_CACHE_MAX_SIZE > 0
 657         struct rte_mempool_cache *cache;
 658         uint32_t index, len;
 659         void **cache_objs;
 660         unsigned lcore_id = rte_lcore_id();
 661         uint32_t cache_size = mp->cache_size;
 662
 663         /* cache is not enabled or single consumer */
 664         if (unlikely(cache_size == 0 || is_mc == 0 || n >= cache_size))
 665                 goto ring_dequeue;
 666
 667         cache = &mp->local_cache[lcore_id];
 668         cache_objs = cache->objs;
 669
 670         /* Can this be satisfied from the cache? */
 671         if (cache->len < n) {
 672                 /* No. Backfill the cache first, and then fill from it */
 673                 uint32_t req = n + (cache_size - cache->len);
 674
 675                 /* How many do we require i.e. number to fill the cache + the request */
 676                 ret = rte_ring_mc_dequeue_bulk(mp->ring, &cache->objs[cache->len], req);
 677                 if (unlikely(ret < 0)) {
 678                         /*
 679                          * In the offchance that we are buffer constrained,
 680                          * where we are not able to allocate cache + n, go to
 681                          * the ring directly. If that fails, we are truly out of
 682                          * buffers.
 683                          */
 684                         goto ring_dequeue;
 685                 }
 686
 687                 cache->len += req;
 688         }
 689
 690         /* Now fill in the response ... */
 691         for (index = 0, len = cache->len - 1; index < n; ++index, len--, obj_table++)
 692                 *obj_table = cache_objs[len];
 693
 694         cache->len -= n;
 695
 696         __MEMPOOL_STAT_ADD(mp, get_success, n_orig);
 697
 698         return 0;
 699
 700 ring_dequeue:
 701 #endif /* RTE_MEMPOOL_CACHE_MAX_SIZE > 0 */
 702
 703         /* get remaining objects from ring */
 704         if (is_mc)
 705                 ret = rte_ring_mc_dequeue_bulk(mp->ring, obj_table, n);
 706         else
 707                 ret = rte_ring_sc_dequeue_bulk(mp->ring, obj_table, n);
 708
 709         if (ret < 0)
 710                 __MEMPOOL_STAT_ADD(mp, get_fail, n_orig);
 711         else
 712                 __MEMPOOL_STAT_ADD(mp, get_success, n_orig);
 713
 714         return ret;
 715 }
 716
 717 /**
 718  * Get several objects from the mempool (multi-consumers safe).
 719  *
 720  * If cache is enabled, objects will be retrieved first from cache,
 721  * subsequently from the common pool. Note that it can return -ENOENT when
 722  * the local cache and common pool are empty, even if cache from other
 723  * lcores are full.
 724  *
 725  * @param mp
 726  *   A pointer to the mempool structure.
 727  * @param obj_table
 728  *   A pointer to a table of void * pointers (objects) that will be filled.
 729  * @param n
 730  *   The number of objects to get from mempool to obj_table.
 731  * @return
 732  *   - 0: Success; objects taken.
 733  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
 734  */
 735 static inline int __attribute__((always_inline))
 736 rte_mempool_mc_get_bulk(struct rte_mempool *mp, void **obj_table, unsigned n)
 737 {
 738         int ret;
 739         ret = __mempool_get_bulk(mp, obj_table, n, 1);
 740         if (ret == 0)
 741                 __mempool_check_cookies(mp, obj_table, n, 1);
 742         return ret;
 743 }
 744
 745 /**
 746  * Get several objects from the mempool (NOT multi-consumers safe).
 747  *
 748  * If cache is enabled, objects will be retrieved first from cache,
 749  * subsequently from the common pool. Note that it can return -ENOENT when
 750  * the local cache and common pool are empty, even if cache from other
 751  * lcores are full.
 752  *
 753  * @param mp
 754  *   A pointer to the mempool structure.
 755  * @param obj_table
 756  *   A pointer to a table of void * pointers (objects) that will be filled.
 757  * @param n
 758  *   The number of objects to get from the mempool to obj_table.
 759  * @return
 760  *   - 0: Success; objects taken.
 761  *   - -ENOENT: Not enough entries in the mempool; no object is
 762  *     retrieved.
 763  */
 764 static inline int __attribute__((always_inline))
 765 rte_mempool_sc_get_bulk(struct rte_mempool *mp, void **obj_table, unsigned n)
 766 {
 767         int ret;
 768         ret = __mempool_get_bulk(mp, obj_table, n, 0);
 769         if (ret == 0)
 770                 __mempool_check_cookies(mp, obj_table, n, 1);
 771         return ret;
 772 }
 773
 774 /**
 775  * Get several objects from the mempool.
 776  *
 777  * This function calls the multi-consumers or the single-consumer
 778  * version, depending on the default behaviour that was specified at
 779  * mempool creation time (see flags).
 780  *
 781  * If cache is enabled, objects will be retrieved first from cache,
 782  * subsequently from the common pool. Note that it can return -ENOENT when
 783  * the local cache and common pool are empty, even if cache from other
 784  * lcores are full.
 785  *
 786  * @param mp
 787  *   A pointer to the mempool structure.
 788  * @param obj_table
 789  *   A pointer to a table of void * pointers (objects) that will be filled.
 790  * @param n
 791  *   The number of objects to get from the mempool to obj_table.
 792  * @return
 793  *   - 0: Success; objects taken
 794  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
 795  */
 796 static inline int __attribute__((always_inline))
 797 rte_mempool_get_bulk(struct rte_mempool *mp, void **obj_table, unsigned n)
 798 {
 799         int ret;
 800         ret = __mempool_get_bulk(mp, obj_table, n,
 801                                  !(mp->flags & MEMPOOL_F_SC_GET));
 802         if (ret == 0)
 803                 __mempool_check_cookies(mp, obj_table, n, 1);
 804         return ret;
 805 }
 806
 807 /**
 808  * Get one object from the mempool (multi-consumers safe).
 809  *
 810  * If cache is enabled, objects will be retrieved first from cache,
 811  * subsequently from the common pool. Note that it can return -ENOENT when
 812  * the local cache and common pool are empty, even if cache from other
 813  * lcores are full.
 814  *
 815  * @param mp
 816  *   A pointer to the mempool structure.
 817  * @param obj_p
 818  *   A pointer to a void * pointer (object) that will be filled.
 819  * @return
 820  *   - 0: Success; objects taken.
 821  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
 822  */
 823 static inline int __attribute__((always_inline))
 824 rte_mempool_mc_get(struct rte_mempool *mp, void **obj_p)
 825 {
 826         return rte_mempool_mc_get_bulk(mp, obj_p, 1);
 827 }
 828
 829 /**
 830  * Get one object from the mempool (NOT multi-consumers safe).
 831  *
 832  * If cache is enabled, objects will be retrieved first from cache,
 833  * subsequently from the common pool. Note that it can return -ENOENT when
 834  * the local cache and common pool are empty, even if cache from other
 835  * lcores are full.
 836  *
 837  * @param mp
 838  *   A pointer to the mempool structure.
 839  * @param obj_p
 840  *   A pointer to a void * pointer (object) that will be filled.
 841  * @return
 842  *   - 0: Success; objects taken.
 843  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
 844  */
 845 static inline int __attribute__((always_inline))
 846 rte_mempool_sc_get(struct rte_mempool *mp, void **obj_p)
 847 {
 848         return rte_mempool_sc_get_bulk(mp, obj_p, 1);
 849 }
 850
 851 /**
 852  * Get one object from the mempool.
 853  *
 854  * This function calls the multi-consumers or the single-consumer
 855  * version, depending on the default behavior that was specified at
 856  * mempool creation (see flags).
 857  *
 858  * If cache is enabled, objects will be retrieved first from cache,
 859  * subsequently from the common pool. Note that it can return -ENOENT when
 860  * the local cache and common pool are empty, even if cache from other
 861  * lcores are full.
 862  *
 863  * @param mp
 864  *   A pointer to the mempool structure.
 865  * @param obj_p
 866  *   A pointer to a void * pointer (object) that will be filled.
 867  * @return
 868  *   - 0: Success; objects taken.
 869  *   - -ENOENT: Not enough entries in the mempool; no object is retrieved.
 870  */
 871 static inline int __attribute__((always_inline))
 872 rte_mempool_get(struct rte_mempool *mp, void **obj_p)
 873 {
 874         return rte_mempool_get_bulk(mp, obj_p, 1);
 875 }
 876
 877 /**
 878  * Return the number of entries in the mempool.
 879  *
 880  * When cache is enabled, this function has to browse the length of
 881  * all lcores, so it should not be used in a data path, but only for
 882  * debug purposes.
 883  *
 884  * @param mp
 885  *   A pointer to the mempool structure.
 886  * @return
 887  *   The number of entries in the mempool.
 888  */
 889 unsigned rte_mempool_count(const struct rte_mempool *mp);
 890
 891 /**
 892  * Return the number of free entries in the mempool ring.
 893  * i.e. how many entries can be freed back to the mempool.
 894  *
 895  * NOTE: This corresponds to the number of elements *allocated* from the
 896  * memory pool, not the number of elements in the pool itself. To count
 897  * the number elements currently available in the pool, use "rte_mempool_count"
 898  *
 899  * When cache is enabled, this function has to browse the length of
 900  * all lcores, so it should not be used in a data path, but only for
 901  * debug purposes.
 902  *
 903  * @param mp
 904  *   A pointer to the mempool structure.
 905  * @return
 906  *   The number of free entries in the mempool.
 907  */
 908 static inline unsigned
 909 rte_mempool_free_count(const struct rte_mempool *mp)
 910 {
 911         return mp->size - rte_mempool_count(mp);
 912 }
 913
 914 /**
 915  * Test if the mempool is full.
 916  *
 917  * When cache is enabled, this function has to browse the length of all
 918  * lcores, so it should not be used in a data path, but only for debug
 919  * purposes.
 920  *
 921  * @param mp
 922  *   A pointer to the mempool structure.
 923  * @return
 924  *   - 1: The mempool is full.
 925  *   - 0: The mempool is not full.
 926  */
 927 static inline int
 928 rte_mempool_full(const struct rte_mempool *mp)
 929 {
 930         return !!(rte_mempool_count(mp) == mp->size);
 931 }
 932
 933 /**
 934  * Test if the mempool is empty.
 935  *
 936  * When cache is enabled, this function has to browse the length of all
 937  * lcores, so it should not be used in a data path, but only for debug
 938  * purposes.
 939  *
 940  * @param mp
 941  *   A pointer to the mempool structure.
 942  * @return
 943  *   - 1: The mempool is empty.
 944  *   - 0: The mempool is not empty.
 945  */
 946 static inline int
 947 rte_mempool_empty(const struct rte_mempool *mp)
 948 {
 949         return !!(rte_mempool_count(mp) == 0);
 950 }
 951
 952 /**
 953  * Return the physical address of elt, which is an element of the pool mp.
 954  *
 955  * @param mp
 956  *   A pointer to the mempool structure.
 957  * @param elt
 958  *   A pointer (virtual address) to the element of the pool.
 959  * @return
 960  *   The physical address of the elt element.
 961  */
 962 static inline phys_addr_t rte_mempool_virt2phy(const struct rte_mempool *mp,
 963         const void *elt)
 964 {
 965         uintptr_t off;
 966
 967         off = (const char *)elt - (const char *)mp;
 968         return mp->phys_addr + off;
 969 }
 970
 971
 972 /**
 973  * Check the consistency of mempool objects.
 974  *
 975  * Verify the coherency of fields in the mempool structure. Also check
 976  * that the cookies of mempool objects (even the ones that are not
 977  * present in pool) have a correct value. If not, a panic will occur.
 978  *
 979  * @param mp
 980  *   A pointer to the mempool structure.
 981  */
 982 void rte_mempool_audit(const struct rte_mempool *mp);
 983
 984 /**
 985  * Return a pointer to the private data in an mempool structure.
 986  *
 987  * @param mp
 988  *   A pointer to the mempool structure.
 989  * @return
 990  *   A pointer to the private data.
 991  */
 992 static inline void *rte_mempool_get_priv(struct rte_mempool *mp)
 993 {
 994         return (char *)mp + sizeof(struct rte_mempool);
 995 }
 996
 997 /**
 998  * Dump the status of all mempools on the console
 999  */
1000 void rte_mempool_list_dump(void);
1001
1002 /**
1003  * Search a mempool from its name
1004  *
1005  * @param name
1006  *   The name of the mempool.
1007  * @return
1008  *   The pointer to the mempool matching the name, or NULL if not found.NULL on error
1009  *   with rte_errno set appropriately. Possible rte_errno values include:
1010  *    - ENOENT - required entry not available to return.
1011  *
1012  */
1013 struct rte_mempool *rte_mempool_lookup(const char *name);
1014
1015 #ifdef __cplusplus
1016 }
1017 #endif
1018
1019 #endif /* _RTE_MEMPOOL_H_ */