path: root/doc
diff options
authorGage Eads <>2019-04-03 18:20:13 -0500
committerThomas Monjalon <>2019-04-04 22:06:16 +0200
commit05d3b5283cc1a61b2e204ddd6bc30b6f3053f280 (patch)
tree9cacc632a064a0d029d5883362aa21844fa10632 /doc
parent721ac9f9e063f55570c1c3a2f07cf5a7b5e15aab (diff)
stack: introduce stack library
The rte_stack library provides an API for configuration and use of a bounded stack of pointers. Push and pop operations are MT-safe, allowing concurrent access, and the interface supports pushing and popping multiple pointers at a time. The library's interface is modeled after another DPDK data structure, rte_ring, and its lock-based implementation is derived from the stack mempool handler. An upcoming commit will migrate the stack mempool handler to rte_stack. Signed-off-by: Gage Eads <> Reviewed-by: Olivier Matz <> Reviewed-by: Honnappa Nagarahalli <>
Diffstat (limited to 'doc')
5 files changed, 38 insertions, 0 deletions
diff --git a/doc/api/ b/doc/api/
index aacc66b..de1e215 100644
--- a/doc/api/
+++ b/doc/api/
@@ -125,6 +125,7 @@ The public API headers are grouped by topics:
[mbuf] (@ref rte_mbuf.h),
[mbuf pool ops] (@ref rte_mbuf_pool_ops.h),
[ring] (@ref rte_ring.h),
+ [stack] (@ref rte_stack.h),
[tailq] (@ref rte_tailq.h),
[bitmap] (@ref rte_bitmap.h)
diff --git a/doc/api/ b/doc/api/
index a365e66..7722fc3 100644
--- a/doc/api/
+++ b/doc/api/
@@ -55,6 +55,7 @@ INPUT = @TOPDIR@/doc/api/ \
@TOPDIR@/lib/librte_ring \
@TOPDIR@/lib/librte_sched \
@TOPDIR@/lib/librte_security \
+ @TOPDIR@/lib/librte_stack \
@TOPDIR@/lib/librte_table \
@TOPDIR@/lib/librte_telemetry \
@TOPDIR@/lib/librte_timer \
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index 6726b1e..95f5e79 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -13,6 +13,7 @@ Programmer's Guide
+ stack_lib
diff --git a/doc/guides/prog_guide/stack_lib.rst b/doc/guides/prog_guide/stack_lib.rst
new file mode 100644
index 0000000..25a8cc3
--- /dev/null
+++ b/doc/guides/prog_guide/stack_lib.rst
@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2019 Intel Corporation.
+Stack Library
+DPDK's stack library provides an API for configuration and use of a bounded
+stack of pointers.
+The stack library provides the following basic operations:
+* Create a uniquely named stack of a user-specified size and using a
+ user-specified socket.
+* Push and pop a burst of one or more stack objects (pointers). These function
+ are multi-threading safe.
+* Free a previously created stack.
+* Lookup a pointer to a stack by its name.
+* Query a stack's current depth and number of free entries.
+The stack consists of a contiguous array of pointers, a current index, and a
+spinlock. Accesses to the stack are made multi-thread safe by the spinlock.
diff --git a/doc/guides/rel_notes/release_19_05.rst b/doc/guides/rel_notes/release_19_05.rst
index 321a8b4..4d59397 100644
--- a/doc/guides/rel_notes/release_19_05.rst
+++ b/doc/guides/rel_notes/release_19_05.rst
@@ -54,6 +54,12 @@ New Features
Also, make sure to start the actual text at the margin.
+* **Added Stack API.**
+ Added a new stack API for configuration and use of a bounded stack of
+ pointers. The API provides MT-safe push and pop operations that can operate
+ on one or more pointers per operation.
* **Updated KNI module and PMD.**
Updated the KNI kernel module to set the max_mtu according to the given
@@ -264,6 +270,7 @@ The libraries prepended with a plus sign were incremented in this version.
+ +