Signed-off-by: Gage Eads <gage.e...@intel.com>
---
doc/guides/mempool/index.rst | 1 +
doc/guides/mempool/stack.rst | 38 +++++++++++++++++++++++++++++++++++
doc/guides/prog_guide/mempool_lib.rst | 2 ++
doc/guides/prog_guide/stack_lib.rst | 4 ++++
4 files changed, 45 insertions(+)
create mode 100644 doc/guides/mempool/stack.rst
diff --git a/doc/guides/mempool/index.rst b/doc/guides/mempool/index.rst
index bbd02fd81..a0e55467e 100644
--- a/doc/guides/mempool/index.rst
+++ b/doc/guides/mempool/index.rst
@@ -14,3 +14,4 @@ application through the mempool API.
octeontx
octeontx2
ring
+ stack
diff --git a/doc/guides/mempool/stack.rst b/doc/guides/mempool/stack.rst
new file mode 100644
index 000000000..3baa774f3
--- /dev/null
+++ b/doc/guides/mempool/stack.rst
@@ -0,0 +1,38 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2020 Intel Corporation.
+
+Stack Mempool Driver
+===================
+
+**rte_mempool_stack** is a pure software mempool driver based on the
+``rte_stack`` DPDK library. A stack-based mempool is often better suited to
+packet-processing workloads than a ring-based mempool, since its LIFO behavior
+results in better temporal locality and a minimal memory footprint even if the
+mempool is over-provisioned.
+
+The following modes of operation are available for the stack mempool driver and
+can be selected as described in :ref:`Mempool_Handlers`:
+
+- ``stack``
+
+ The underlying **rte_stack** operates in standard (lock-based) mode.
+ For more information please refer to :ref:`Stack_Library_Std_Stack`.
+
+- ``lf_stack``
+
+ The underlying **rte_stack** operates in lock-free mode. For more
+ information please refer to :ref:`Stack_Library_LF_Stack`.
+
+The standard stack outperforms the lock-free stack on average, however the
+standard stack is non-preemptive: if a mempool user is preempted while holding
+the stack lock, that thread will block all other mempool accesses until it
+returns and releases the lock. As a result, an application using the standard
+stack whose threads can be preempted can suffer from brief, infrequent
+performance hiccups.
+
+The lock-free stack, by design, is not susceptible to this problem; one thread
can
+be preempted at any point during a push or pop operation and will not impede
+the progress of any other thread.
+
+For a more detailed description of the stack implementations, please refer to
+:doc:`../prog_guide/stack_lib`.
diff --git a/doc/guides/prog_guide/mempool_lib.rst
b/doc/guides/prog_guide/mempool_lib.rst
index e3e1f940b..6f3c0067f 100644
--- a/doc/guides/prog_guide/mempool_lib.rst
+++ b/doc/guides/prog_guide/mempool_lib.rst
@@ -105,6 +105,8 @@ These user-owned caches can be explicitly passed to
``rte_mempool_generic_put()`
The ``rte_mempool_default_cache()`` call returns the default internal cache if
any.
In contrast to the default caches, user-owned caches can be used by
unregistered non-EAL threads too.
+.. _Mempool_Handlers:
+
Mempool Handlers
------------------------
diff --git a/doc/guides/prog_guide/stack_lib.rst
b/doc/guides/prog_guide/stack_lib.rst
index 8fe8804e3..3097cab0c 100644
--- a/doc/guides/prog_guide/stack_lib.rst
+++ b/doc/guides/prog_guide/stack_lib.rst
@@ -28,6 +28,8 @@ Implementation
The library supports two types of stacks: standard (lock-based) and lock-free.
Both types use the same set of interfaces, but their implementations differ.
+.. _Stack_Library_Std_Stack:
+
Lock-based Stack
----------------
@@ -35,6 +37,8 @@ The lock-based 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.
+.. _Stack_Library_LF_Stack:
+
Lock-free Stack
------------------
--
2.13.6
