rte_stack.h

Go to the documentation of this file.

/* SPDX-License-Identifier: BSD-3-Clause
 * Copyright(c) 2019 Intel Corporation
 * Copyright(c) 2026 SmartShare Systems
 */
 
#ifndef _RTE_STACK_H_
#define _RTE_STACK_H_
 
#include <stdalign.h>
 
#include <rte_debug.h>
#include <rte_errno.h>
#include <rte_memzone.h>
#include <rte_spinlock.h>
 
#define RTE_TAILQ_STACK_NAME "RTE_STACK"
#define RTE_STACK_MZ_PREFIX "STK_"
#define RTE_STACK_NAMESIZE (RTE_MEMZONE_NAMESIZE - \
               sizeof(RTE_STACK_MZ_PREFIX) + 1)
 
static_assert(((sizeof(void *) * RTE_STACK_PILE_BULK_SIZE) & RTE_CACHE_LINE_MASK) == 0,
        "Pile bulk size must be divisible by CPU cache line size");
static_assert(RTE_IS_POWER_OF_2(RTE_STACK_PILE_BULK_SIZE),
        "Pile bulk size must be power of 2");
 
/* Note: Also used as solo (single-object) pile element. */
struct rte_stack_lf_elem {
    void *data;         
    struct rte_stack_lf_elem *next; 
};
 
/*
 * Bulk (multi-object) pile element.
 * Inherited from the rte_stack_lf_elem (single-object) class,
 * and extended with an array for holding a bulk of object pointers.
 */
struct rte_stack_pile_bulk_elem {
    /* The first part must be ABI compatible with the rte_stack_lf_elem parent class. */
    struct rte_stack_lf_elem elem;
    /* The second part differs. */
    alignas(RTE_CACHE_LINE_SIZE)
    void *objs[RTE_STACK_PILE_BULK_SIZE];   
};
 
static_assert(offsetof(struct rte_stack_pile_bulk_elem, elem) == 0,
        "Inherited type mismatch");
 
struct __rte_aligned(16) rte_stack_lf_head {
    struct rte_stack_lf_elem *top; 
    uint64_t cnt; 
};
 
struct rte_stack_lf_list {
    struct rte_stack_lf_head head;
    RTE_ATOMIC(uint64_t) len;
};
 
/* Structure containing two lock-free LIFO lists: the stack itself and a list
 * of free linked-list elements.
 */
struct rte_stack_lf {
    alignas(RTE_CACHE_LINE_SIZE) struct rte_stack_lf_list used;
    RTE_CACHE_GUARD;
    alignas(RTE_CACHE_LINE_SIZE) struct rte_stack_lf_list free;
    RTE_CACHE_GUARD;
    alignas(RTE_CACHE_LINE_SIZE) struct rte_stack_lf_elem elems[];
};
 
/* Pile structure containing three lock-free LIFO-like lists:
 *  - A list of elements, each element holding a bulk of pointers to objects.
 *  - A list of elements, each element holding one pointer to an object.
 *  - A list of free linked-list elements.
 */
struct rte_stack_pile {
    alignas(RTE_CACHE_LINE_SIZE) struct rte_stack_lf_list bulk;
    RTE_CACHE_GUARD;
    alignas(RTE_CACHE_LINE_SIZE) struct rte_stack_lf_list solo;
    RTE_CACHE_GUARD;
    alignas(RTE_CACHE_LINE_SIZE) struct rte_stack_lf_list free_bulk;
    RTE_CACHE_GUARD;
    alignas(RTE_CACHE_LINE_SIZE) struct rte_stack_lf_list free_solo;
    RTE_CACHE_GUARD;
    alignas(RTE_CACHE_LINE_SIZE) void *elems[];
};
 
/* Structure containing the LIFO, its current length, and a lock for mutual
 * exclusion.
 */
struct rte_stack_std {
    rte_spinlock_t lock; 
    uint32_t len; 
    void *objs[]; 
};
 
/* The RTE stack structure contains the LIFO structure itself, plus metadata
 * such as its name and memzone pointer.
 */
struct __rte_cache_aligned rte_stack {
    alignas(RTE_CACHE_LINE_SIZE) char name[RTE_STACK_NAMESIZE];
    const struct rte_memzone *memzone;
    uint32_t capacity; 
    uint32_t flags; 
    union {
        struct rte_stack_lf stack_lf; 
        struct rte_stack_pile stack_pile; 
        struct rte_stack_std stack_std; 
    };
};
 
#define RTE_STACK_F_LF 0x0001
 
#define RTE_STACK_F_PILE 0x0002
 
#include "rte_stack_std.h"
#include "rte_stack_lf.h"
#include "rte_stack_pile.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
static __rte_always_inline unsigned int
rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
{
    RTE_ASSERT(s != NULL);
    RTE_ASSERT(obj_table != NULL);
 
    if (s->flags & RTE_STACK_F_LF)
        return __rte_stack_lf_push(s, obj_table, n);
    else if (s->flags & RTE_STACK_F_PILE)
        return __rte_stack_pile_push(s, obj_table, n);
    else
        return __rte_stack_std_push(s, obj_table, n);
}
 
static __rte_always_inline unsigned int
rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
{
    RTE_ASSERT(s != NULL);
    RTE_ASSERT(obj_table != NULL);
 
    if (s->flags & RTE_STACK_F_LF)
        return __rte_stack_lf_pop(s, obj_table, n);
    else if (s->flags & RTE_STACK_F_PILE)
        return __rte_stack_pile_pop(s, obj_table, n);
    else
        return __rte_stack_std_pop(s, obj_table, n);
}
 
static __rte_always_inline unsigned int
rte_stack_count(struct rte_stack *s)
{
    RTE_ASSERT(s != NULL);
 
    if (s->flags & RTE_STACK_F_LF)
        return __rte_stack_lf_count(s);
    else if (s->flags & RTE_STACK_F_PILE)
        return __rte_stack_pile_count(s);
    else
        return __rte_stack_std_count(s);
}
 
static __rte_always_inline unsigned int
rte_stack_free_count(struct rte_stack *s)
{
    RTE_ASSERT(s != NULL);
 
    return s->capacity - rte_stack_count(s);
}
 
struct rte_stack *
rte_stack_create(const char *name, unsigned int count, int socket_id,
         uint32_t flags);
 
void
rte_stack_free(struct rte_stack *s);
 
struct rte_stack *
rte_stack_lookup(const char *name);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _RTE_STACK_H_ */