rte_mempool.h

Go to the documentation of this file.

/*-
 *   BSD LICENSE
 *
 *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
 *   Copyright(c) 2016 6WIND S.A.
 *   All rights reserved.
 *
 *   Redistribution and use in source and binary forms, with or without
 *   modification, are permitted provided that the following conditions
 *   are met:
 *
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in
 *       the documentation and/or other materials provided with the
 *       distribution.
 *     * Neither the name of Intel Corporation nor the names of its
 *       contributors may be used to endorse or promote products derived
 *       from this software without specific prior written permission.
 *
 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _RTE_MEMPOOL_H_
#define _RTE_MEMPOOL_H_

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <errno.h>
#include <inttypes.h>
#include <sys/queue.h>

#include <rte_config.h>
#include <rte_spinlock.h>
#include <rte_log.h>
#include <rte_debug.h>
#include <rte_lcore.h>
#include <rte_memory.h>
#include <rte_branch_prediction.h>
#include <rte_ring.h>
#include <rte_memcpy.h>
#include <rte_common.h>

#ifdef __cplusplus
extern "C" {
#endif

#define RTE_MEMPOOL_HEADER_COOKIE1  0xbadbadbadadd2e55ULL 
#define RTE_MEMPOOL_HEADER_COOKIE2  0xf2eef2eedadd2e55ULL 
#define RTE_MEMPOOL_TRAILER_COOKIE  0xadd2e55badbadbadULL 
#ifdef RTE_LIBRTE_MEMPOOL_DEBUG

struct rte_mempool_debug_stats {
    uint64_t put_bulk;         
    uint64_t put_objs;         
    uint64_t get_success_bulk; 
    uint64_t get_success_objs; 
    uint64_t get_fail_bulk;    
    uint64_t get_fail_objs;    
} __rte_cache_aligned;
#endif

struct rte_mempool_cache {
    uint32_t size;        
    uint32_t flushthresh; 
    uint32_t len;         
    /*
     * Cache is allocated to this size to allow it to overflow in certain
     * cases to avoid needless emptying of cache.
     */
    void *objs[RTE_MEMPOOL_CACHE_MAX_SIZE * 3]; 
} __rte_cache_aligned;

struct rte_mempool_objsz {
    uint32_t elt_size;     
    uint32_t header_size;  
    uint32_t trailer_size; 
    uint32_t total_size;
};

#define RTE_MEMPOOL_NAMESIZE (RTE_RING_NAMESIZE - \
                  sizeof(RTE_MEMPOOL_MZ_PREFIX) + 1)
#define RTE_MEMPOOL_MZ_PREFIX "MP_"

/* "MP_<name>" */
#define RTE_MEMPOOL_MZ_FORMAT   RTE_MEMPOOL_MZ_PREFIX "%s"

#define MEMPOOL_PG_SHIFT_MAX    (sizeof(uintptr_t) * CHAR_BIT - 1)

#define MEMPOOL_PG_NUM_DEFAULT  1

#ifndef RTE_MEMPOOL_ALIGN
#define RTE_MEMPOOL_ALIGN   RTE_CACHE_LINE_SIZE
#endif

#define RTE_MEMPOOL_ALIGN_MASK  (RTE_MEMPOOL_ALIGN - 1)

struct rte_mempool_objhdr {
    STAILQ_ENTRY(rte_mempool_objhdr) next; 
    struct rte_mempool *mp;          
    RTE_STD_C11
    union {
        rte_iova_t iova;         
        phys_addr_t physaddr;    
    };
#ifdef RTE_LIBRTE_MEMPOOL_DEBUG
    uint64_t cookie;                 
#endif
};

STAILQ_HEAD(rte_mempool_objhdr_list, rte_mempool_objhdr);

#ifdef RTE_LIBRTE_MEMPOOL_DEBUG

struct rte_mempool_objtlr {
    uint64_t cookie;                 
};

#endif

STAILQ_HEAD(rte_mempool_memhdr_list, rte_mempool_memhdr);

typedef void (rte_mempool_memchunk_free_cb_t)(struct rte_mempool_memhdr *memhdr,
    void *opaque);

struct rte_mempool_memhdr {
    STAILQ_ENTRY(rte_mempool_memhdr) next; 
    struct rte_mempool *mp;  
    void *addr;              
    RTE_STD_C11
    union {
        rte_iova_t iova;       
        phys_addr_t phys_addr; 
    };
    size_t len;              
    rte_mempool_memchunk_free_cb_t *free_cb; 
    void *opaque;            
};

struct rte_mempool {
    /*
     * Note: this field kept the RTE_MEMZONE_NAMESIZE size due to ABI
     * compatibility requirements, it could be changed to
     * RTE_MEMPOOL_NAMESIZE next time the ABI changes
     */
    char name[RTE_MEMZONE_NAMESIZE]; 
    RTE_STD_C11
    union {
        void *pool_data;         
        uint64_t pool_id;        
    };
    void *pool_config;               
    const struct rte_memzone *mz;    
    unsigned int flags;              
    int socket_id;                   
    uint32_t size;                   
    uint32_t cache_size;
    uint32_t elt_size;               
    uint32_t header_size;            
    uint32_t trailer_size;           
    unsigned private_data_size;      
    int32_t ops_index;

    struct rte_mempool_cache *local_cache; 
    uint32_t populated_size;         
    struct rte_mempool_objhdr_list elt_list; 
    uint32_t nb_mem_chunks;          
    struct rte_mempool_memhdr_list mem_list; 
#ifdef RTE_LIBRTE_MEMPOOL_DEBUG

    struct rte_mempool_debug_stats stats[RTE_MAX_LCORE];
#endif
}  __rte_cache_aligned;

#define MEMPOOL_F_NO_SPREAD      0x0001 
#define MEMPOOL_F_NO_CACHE_ALIGN 0x0002 
#define MEMPOOL_F_SP_PUT         0x0004 
#define MEMPOOL_F_SC_GET         0x0008 
#define MEMPOOL_F_POOL_CREATED   0x0010 
#define MEMPOOL_F_NO_PHYS_CONTIG 0x0020 
#define MEMPOOL_F_CAPA_PHYS_CONTIG 0x0040

#define MEMPOOL_F_CAPA_BLK_ALIGNED_OBJECTS 0x0080

#ifdef RTE_LIBRTE_MEMPOOL_DEBUG
#define __MEMPOOL_STAT_ADD(mp, name, n) do {                    \
        unsigned __lcore_id = rte_lcore_id();           \
        if (__lcore_id < RTE_MAX_LCORE) {               \
            mp->stats[__lcore_id].name##_objs += n; \
            mp->stats[__lcore_id].name##_bulk += 1; \
        }                                               \
    } while(0)
#else
#define __MEMPOOL_STAT_ADD(mp, name, n) do {} while(0)
#endif

#define MEMPOOL_HEADER_SIZE(mp, cs) \
    (sizeof(*(mp)) + (((cs) == 0) ? 0 : \
    (sizeof(struct rte_mempool_cache) * RTE_MAX_LCORE)))

/* return the header of a mempool object (internal) */
static inline struct rte_mempool_objhdr *__mempool_get_header(void *obj)
{
    return (struct rte_mempool_objhdr *)RTE_PTR_SUB(obj,
        sizeof(struct rte_mempool_objhdr));
}

static inline struct rte_mempool *rte_mempool_from_obj(void *obj)
{
    struct rte_mempool_objhdr *hdr = __mempool_get_header(obj);
    return hdr->mp;
}

/* return the trailer of a mempool object (internal) */
static inline struct rte_mempool_objtlr *__mempool_get_trailer(void *obj)
{
    struct rte_mempool *mp = rte_mempool_from_obj(obj);
    return (struct rte_mempool_objtlr *)RTE_PTR_ADD(obj, mp->elt_size);
}

void rte_mempool_check_cookies(const struct rte_mempool *mp,
    void * const *obj_table_const, unsigned n, int free);

#ifdef RTE_LIBRTE_MEMPOOL_DEBUG
#define __mempool_check_cookies(mp, obj_table_const, n, free) \
    rte_mempool_check_cookies(mp, obj_table_const, n, free)
#else
#define __mempool_check_cookies(mp, obj_table_const, n, free) do {} while(0)
#endif /* RTE_LIBRTE_MEMPOOL_DEBUG */

#define RTE_MEMPOOL_OPS_NAMESIZE 32 
typedef int (*rte_mempool_alloc_t)(struct rte_mempool *mp);

typedef void (*rte_mempool_free_t)(struct rte_mempool *mp);

typedef int (*rte_mempool_enqueue_t)(struct rte_mempool *mp,
        void * const *obj_table, unsigned int n);

typedef int (*rte_mempool_dequeue_t)(struct rte_mempool *mp,
        void **obj_table, unsigned int n);

typedef unsigned (*rte_mempool_get_count)(const struct rte_mempool *mp);

typedef int (*rte_mempool_get_capabilities_t)(const struct rte_mempool *mp,
        unsigned int *flags);

typedef int (*rte_mempool_ops_register_memory_area_t)
(const struct rte_mempool *mp, char *vaddr, rte_iova_t iova, size_t len);

struct rte_mempool_ops {
    char name[RTE_MEMPOOL_OPS_NAMESIZE]; 
    rte_mempool_alloc_t alloc;       
    rte_mempool_free_t free;         
    rte_mempool_enqueue_t enqueue;   
    rte_mempool_dequeue_t dequeue;   
    rte_mempool_get_count get_count; 
    rte_mempool_get_capabilities_t get_capabilities;
    rte_mempool_ops_register_memory_area_t register_memory_area;
} __rte_cache_aligned;

#define RTE_MEMPOOL_MAX_OPS_IDX 16  
struct rte_mempool_ops_table {
    rte_spinlock_t sl;     
    uint32_t num_ops;      
    struct rte_mempool_ops ops[RTE_MEMPOOL_MAX_OPS_IDX];
} __rte_cache_aligned;

extern struct rte_mempool_ops_table rte_mempool_ops_table;

static inline struct rte_mempool_ops *
rte_mempool_get_ops(int ops_index)
{
    RTE_VERIFY((ops_index >= 0) && (ops_index < RTE_MEMPOOL_MAX_OPS_IDX));

    return &rte_mempool_ops_table.ops[ops_index];
}

int
rte_mempool_ops_alloc(struct rte_mempool *mp);

static inline int
rte_mempool_ops_dequeue_bulk(struct rte_mempool *mp,
        void **obj_table, unsigned n)
{
    struct rte_mempool_ops *ops;

    ops = rte_mempool_get_ops(mp->ops_index);
    return ops->dequeue(mp, obj_table, n);
}

static inline int
rte_mempool_ops_enqueue_bulk(struct rte_mempool *mp, void * const *obj_table,
        unsigned n)
{
    struct rte_mempool_ops *ops;

    ops = rte_mempool_get_ops(mp->ops_index);
    return ops->enqueue(mp, obj_table, n);
}

unsigned
rte_mempool_ops_get_count(const struct rte_mempool *mp);

int
rte_mempool_ops_get_capabilities(const struct rte_mempool *mp,
                    unsigned int *flags);
int
rte_mempool_ops_register_memory_area(const struct rte_mempool *mp,
                char *vaddr, rte_iova_t iova, size_t len);

void
rte_mempool_ops_free(struct rte_mempool *mp);

int
rte_mempool_set_ops_byname(struct rte_mempool *mp, const char *name,
        void *pool_config);

int rte_mempool_register_ops(const struct rte_mempool_ops *ops);

#define MEMPOOL_REGISTER_OPS(ops)                   \
    void mp_hdlr_init_##ops(void);                  \
    void __attribute__((constructor, used)) mp_hdlr_init_##ops(void)\
    {                               \
        rte_mempool_register_ops(&ops);         \
    }

typedef void (rte_mempool_obj_cb_t)(struct rte_mempool *mp,
        void *opaque, void *obj, unsigned obj_idx);
typedef rte_mempool_obj_cb_t rte_mempool_obj_ctor_t; /* compat */

typedef void (rte_mempool_mem_cb_t)(struct rte_mempool *mp,
        void *opaque, struct rte_mempool_memhdr *memhdr,
        unsigned mem_idx);

typedef void (rte_mempool_ctor_t)(struct rte_mempool *, void *);

struct rte_mempool *
rte_mempool_create(const char *name, unsigned n, unsigned elt_size,
           unsigned cache_size, unsigned private_data_size,
           rte_mempool_ctor_t *mp_init, void *mp_init_arg,
           rte_mempool_obj_cb_t *obj_init, void *obj_init_arg,
           int socket_id, unsigned flags);

struct rte_mempool *
rte_mempool_xmem_create(const char *name, unsigned n, unsigned elt_size,
        unsigned cache_size, unsigned private_data_size,
        rte_mempool_ctor_t *mp_init, void *mp_init_arg,
        rte_mempool_obj_cb_t *obj_init, void *obj_init_arg,
        int socket_id, unsigned flags, void *vaddr,
        const rte_iova_t iova[], uint32_t pg_num, uint32_t pg_shift);

struct rte_mempool *
rte_mempool_create_empty(const char *name, unsigned n, unsigned elt_size,
    unsigned cache_size, unsigned private_data_size,
    int socket_id, unsigned flags);
void
rte_mempool_free(struct rte_mempool *mp);

int rte_mempool_populate_iova(struct rte_mempool *mp, char *vaddr,
    rte_iova_t iova, size_t len, rte_mempool_memchunk_free_cb_t *free_cb,
    void *opaque);

__rte_deprecated
int rte_mempool_populate_phys(struct rte_mempool *mp, char *vaddr,
    phys_addr_t paddr, size_t len, rte_mempool_memchunk_free_cb_t *free_cb,
    void *opaque);

int rte_mempool_populate_iova_tab(struct rte_mempool *mp, char *vaddr,
    const rte_iova_t iova[], uint32_t pg_num, uint32_t pg_shift,
    rte_mempool_memchunk_free_cb_t *free_cb, void *opaque);

__rte_deprecated
int rte_mempool_populate_phys_tab(struct rte_mempool *mp, char *vaddr,
    const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift,
    rte_mempool_memchunk_free_cb_t *free_cb, void *opaque);

int
rte_mempool_populate_virt(struct rte_mempool *mp, char *addr,
    size_t len, size_t pg_sz, rte_mempool_memchunk_free_cb_t *free_cb,
    void *opaque);

int rte_mempool_populate_default(struct rte_mempool *mp);

int rte_mempool_populate_anon(struct rte_mempool *mp);

uint32_t rte_mempool_obj_iter(struct rte_mempool *mp,
    rte_mempool_obj_cb_t *obj_cb, void *obj_cb_arg);

uint32_t rte_mempool_mem_iter(struct rte_mempool *mp,
    rte_mempool_mem_cb_t *mem_cb, void *mem_cb_arg);

void rte_mempool_dump(FILE *f, struct rte_mempool *mp);

struct rte_mempool_cache *
rte_mempool_cache_create(uint32_t size, int socket_id);

void
rte_mempool_cache_free(struct rte_mempool_cache *cache);

static __rte_always_inline void
rte_mempool_cache_flush(struct rte_mempool_cache *cache,
            struct rte_mempool *mp)
{
    rte_mempool_ops_enqueue_bulk(mp, cache->objs, cache->len);
    cache->len = 0;
}

static __rte_always_inline struct rte_mempool_cache *
rte_mempool_default_cache(struct rte_mempool *mp, unsigned lcore_id)
{
    if (mp->cache_size == 0)
        return NULL;

    if (lcore_id >= RTE_MAX_LCORE)
        return NULL;

    return &mp->local_cache[lcore_id];
}

static __rte_always_inline void
__mempool_generic_put(struct rte_mempool *mp, void * const *obj_table,
              unsigned int n, struct rte_mempool_cache *cache)
{
    void **cache_objs;

    /* increment stat now, adding in mempool always success */
    __MEMPOOL_STAT_ADD(mp, put, n);

    /* No cache provided or if put would overflow mem allocated for cache */
    if (unlikely(cache == NULL || n > RTE_MEMPOOL_CACHE_MAX_SIZE))
        goto ring_enqueue;

    cache_objs = &cache->objs[cache->len];

    /*
     * The cache follows the following algorithm
     *   1. Add the objects to the cache
     *   2. Anything greater than the cache min value (if it crosses the
     *   cache flush threshold) is flushed to the ring.
     */

    /* Add elements back into the cache */
    rte_memcpy(&cache_objs[0], obj_table, sizeof(void *) * n);

    cache->len += n;

    if (cache->len >= cache->flushthresh) {
        rte_mempool_ops_enqueue_bulk(mp, &cache->objs[cache->size],
                cache->len - cache->size);
        cache->len = cache->size;
    }

    return;

ring_enqueue:

    /* push remaining objects in ring */
#ifdef RTE_LIBRTE_MEMPOOL_DEBUG
    if (rte_mempool_ops_enqueue_bulk(mp, obj_table, n) < 0)
        rte_panic("cannot put objects in mempool\n");
#else
    rte_mempool_ops_enqueue_bulk(mp, obj_table, n);
#endif
}


static __rte_always_inline void
rte_mempool_generic_put(struct rte_mempool *mp, void * const *obj_table,
            unsigned int n, struct rte_mempool_cache *cache)
{
    __mempool_check_cookies(mp, obj_table, n, 0);
    __mempool_generic_put(mp, obj_table, n, cache);
}

static __rte_always_inline void
rte_mempool_put_bulk(struct rte_mempool *mp, void * const *obj_table,
             unsigned int n)
{
    struct rte_mempool_cache *cache;
    cache = rte_mempool_default_cache(mp, rte_lcore_id());
    rte_mempool_generic_put(mp, obj_table, n, cache);
}

static __rte_always_inline void
rte_mempool_put(struct rte_mempool *mp, void *obj)
{
    rte_mempool_put_bulk(mp, &obj, 1);
}

static __rte_always_inline int
__mempool_generic_get(struct rte_mempool *mp, void **obj_table,
              unsigned int n, struct rte_mempool_cache *cache)
{
    int ret;
    uint32_t index, len;
    void **cache_objs;

    /* No cache provided or cannot be satisfied from cache */
    if (unlikely(cache == NULL || n >= cache->size))
        goto ring_dequeue;

    cache_objs = cache->objs;

    /* Can this be satisfied from the cache? */
    if (cache->len < n) {
        /* No. Backfill the cache first, and then fill from it */
        uint32_t req = n + (cache->size - cache->len);

        /* How many do we require i.e. number to fill the cache + the request */
        ret = rte_mempool_ops_dequeue_bulk(mp,
            &cache->objs[cache->len], req);
        if (unlikely(ret < 0)) {
            /*
             * In the offchance that we are buffer constrained,
             * where we are not able to allocate cache + n, go to
             * the ring directly. If that fails, we are truly out of
             * buffers.
             */
            goto ring_dequeue;
        }

        cache->len += req;
    }

    /* Now fill in the response ... */
    for (index = 0, len = cache->len - 1; index < n; ++index, len--, obj_table++)
        *obj_table = cache_objs[len];

    cache->len -= n;

    __MEMPOOL_STAT_ADD(mp, get_success, n);

    return 0;

ring_dequeue:

    /* get remaining objects from ring */
    ret = rte_mempool_ops_dequeue_bulk(mp, obj_table, n);

    if (ret < 0)
        __MEMPOOL_STAT_ADD(mp, get_fail, n);
    else
        __MEMPOOL_STAT_ADD(mp, get_success, n);

    return ret;
}

static __rte_always_inline int
rte_mempool_generic_get(struct rte_mempool *mp, void **obj_table,
            unsigned int n, struct rte_mempool_cache *cache)
{
    int ret;
    ret = __mempool_generic_get(mp, obj_table, n, cache);
    if (ret == 0)
        __mempool_check_cookies(mp, obj_table, n, 1);
    return ret;
}

static __rte_always_inline int
rte_mempool_get_bulk(struct rte_mempool *mp, void **obj_table, unsigned int n)
{
    struct rte_mempool_cache *cache;
    cache = rte_mempool_default_cache(mp, rte_lcore_id());
    return rte_mempool_generic_get(mp, obj_table, n, cache);
}

static __rte_always_inline int
rte_mempool_get(struct rte_mempool *mp, void **obj_p)
{
    return rte_mempool_get_bulk(mp, obj_p, 1);
}

unsigned int rte_mempool_avail_count(const struct rte_mempool *mp);

unsigned int
rte_mempool_in_use_count(const struct rte_mempool *mp);

static inline int
rte_mempool_full(const struct rte_mempool *mp)
{
    return !!(rte_mempool_avail_count(mp) == mp->size);
}

static inline int
rte_mempool_empty(const struct rte_mempool *mp)
{
    return !!(rte_mempool_avail_count(mp) == 0);
}

static inline rte_iova_t
rte_mempool_virt2iova(const void *elt)
{
    const struct rte_mempool_objhdr *hdr;
    hdr = (const struct rte_mempool_objhdr *)RTE_PTR_SUB(elt,
        sizeof(*hdr));
    return hdr->iova;
}

__rte_deprecated
static inline phys_addr_t
rte_mempool_virt2phy(__rte_unused const struct rte_mempool *mp, const void *elt)
{
    return rte_mempool_virt2iova(elt);
}

void rte_mempool_audit(struct rte_mempool *mp);

static inline void *rte_mempool_get_priv(struct rte_mempool *mp)
{
    return (char *)mp +
        MEMPOOL_HEADER_SIZE(mp, mp->cache_size);
}

void rte_mempool_list_dump(FILE *f);

struct rte_mempool *rte_mempool_lookup(const char *name);

uint32_t rte_mempool_calc_obj_size(uint32_t elt_size, uint32_t flags,
    struct rte_mempool_objsz *sz);

size_t rte_mempool_xmem_size(uint32_t elt_num, size_t total_elt_sz,
    uint32_t pg_shift, unsigned int flags);

ssize_t rte_mempool_xmem_usage(void *vaddr, uint32_t elt_num,
    size_t total_elt_sz, const rte_iova_t iova[], uint32_t pg_num,
    uint32_t pg_shift, unsigned int flags);

void rte_mempool_walk(void (*func)(struct rte_mempool *, void *arg),
              void *arg);

#ifdef __cplusplus
}
#endif

#endif /* _RTE_MEMPOOL_H_ */