summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorGage Eads <gage.eads@intel.com>2019-04-03 18:20:13 -0500
committerThomas Monjalon <thomas@monjalon.net>2019-04-04 22:06:16 +0200
commit05d3b5283cc1a61b2e204ddd6bc30b6f3053f280 (patch)
tree9cacc632a064a0d029d5883362aa21844fa10632 /doc
parent721ac9f9e063f55570c1c3a2f07cf5a7b5e15aab (diff)
downloaddpdk-draft-windows-05d3b5283cc1a61b2e204ddd6bc30b6f3053f280.zip
dpdk-draft-windows-05d3b5283cc1a61b2e204ddd6bc30b6f3053f280.tar.gz
dpdk-draft-windows-05d3b5283cc1a61b2e204ddd6bc30b6f3053f280.tar.xz
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 <gage.eads@intel.com> Reviewed-by: Olivier Matz <olivier.matz@6wind.com> Reviewed-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/api/doxy-api-index.md1
-rw-r--r--doc/api/doxy-api.conf.in1
-rw-r--r--doc/guides/prog_guide/index.rst1
-rw-r--r--doc/guides/prog_guide/stack_lib.rst28
-rw-r--r--doc/guides/rel_notes/release_19_05.rst7
5 files changed, 38 insertions, 0 deletions
diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index aacc66b..de1e215 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -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/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index a365e66..7722fc3 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -55,6 +55,7 @@ INPUT = @TOPDIR@/doc/api/doxy-api-index.md \
@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
env_abstraction_layer
service_cores
ring_lib
+ stack_lib
mempool_lib
mbuf_lib
poll_mode_drv
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.
+
+Implementation
+~~~~~~~~~~~~~~
+
+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.
librte_ring.so.2
librte_sched.so.2
librte_security.so.2
+ + librte_stack.so.1
librte_table.so.3
librte_timer.so.1
librte_vhost.so.4