lib/librte_mempool/rte_mempool.h

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