[PATCH v10 14/14] doc: add documentation for port mirroring

[Stephen Hemminger]

Add ethdev port mirror to documentation.

Signed-off-by: Stephen Hemminger <stephen at networkplumber.org>
---
 doc/guides/prog_guide/bpf_lib.rst            |  2 +
 doc/guides/prog_guide/ethdev/index.rst       |  1 +
 doc/guides/prog_guide/ethdev/port_mirror.rst | 68 ++++++++++++++++++++
 doc/guides/rel_notes/deprecation.rst         |  5 ++
 doc/guides/rel_notes/release_25_11.rst       |  5 ++
 5 files changed, 81 insertions(+)
 create mode 100644 doc/guides/prog_guide/ethdev/port_mirror.rst

diff --git a/doc/guides/prog_guide/bpf_lib.rst b/doc/guides/prog_guide/bpf_lib.rst
index 8c820328b9..038da03360 100644
--- a/doc/guides/prog_guide/bpf_lib.rst
+++ b/doc/guides/prog_guide/bpf_lib.rst
@@ -1,6 +1,8 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2018 Intel Corporation.
 
+.. _bpf_library:
+
 Berkeley Packet Filter (BPF) Library
 ====================================
 
diff --git a/doc/guides/prog_guide/ethdev/index.rst b/doc/guides/prog_guide/ethdev/index.rst
index 392ced0a2e..cb905b92f1 100644
--- a/doc/guides/prog_guide/ethdev/index.rst
+++ b/doc/guides/prog_guide/ethdev/index.rst
@@ -12,4 +12,5 @@ Ethernet Device Library
     flow_offload
     traffic_metering_and_policing
     traffic_management
+    port_mirror
     qos_framework
diff --git a/doc/guides/prog_guide/ethdev/port_mirror.rst b/doc/guides/prog_guide/ethdev/port_mirror.rst
new file mode 100644
index 0000000000..f270fb6627
--- /dev/null
+++ b/doc/guides/prog_guide/ethdev/port_mirror.rst
@@ -0,0 +1,68 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2025 Stephen Hemminger
+
+Port Mirroring API
+==================
+
+
+Overview
+--------
+
+The Ethdev port mirror API is a feature usefel for passive network analysis
+and monitoring. `Port mirroring`_ is a common feature of network switches;
+it is known as SPAN (Switch Port Analyzer) on Cisco terminology.
+Mirroring is a feature in the ethdev layer that copies
+some or all of the packets passing through a port.
+
+Port mirroring can be used for analyze and debugging packets or
+traffic analysis.
+
+Mirroring is implemented in the ethdev layer and copies packets
+before they are seen by the network driver (PMD).
+On transmit packets are copied after the transmit callbacks and
+just before passing to the network driver.
+On Receive packets are copied when they are received from
+the network driver before any receive callbacks.
+
+
+Implementation
+--------------
+
+Creating a port mirror is done by the *rte_eth_add_mirror()* function.
+The ``struct rte_eth_mirror_conf`` controls the settings of the new
+mirror.
+
+.. code-block:: c
+
+  struct rte_eth_mirror_conf {
+        struct rte_mempool *mp; /**< Memory pool for copies, If NULL then cloned. */
+        struct rte_bpf_prm *filter; /**< Optional packet filter */
+        uint32_t snaplen;       /**< Upper limit on number of bytes to copy */
+        uint32_t flags;         /**< bitmask of RTE_ETH_MIRROR_XXX_FLAG's */
+        uint16_t target;        /**< Destination port */
+  };
+
+
+The ``target`` field is ethdev port which will be used as the output
+for the copied packets. The ``flags`` field is used to control whether
+packets are mirrored on transmit (egress), receive (ingress) or both.
+The ``filter`` is an optional BPF filter useful for selecting a subset
+of the packets to be mirrored.
+
+Limitations
+-----------
+
+There are some limitations to using port mirroring.
+
+- The port being used for mirroring should not be confused with active ports
+  used for other traffic. The port ownership API can be used to solve this.
+
+- There is some performance impact when using port mirroring. The overhead
+  of copying packets and sending on a the target port can be noticeable.
+
+- Some packets maybe lost if the target port can not keep up with the
+  mirrored traffic. This can be observed with the ``rte_eth_mirror_stats``.
+
+- The API restricts mirroring of target ports to prevent packet loops.
+
+.. _Port Mirroring: https://en.wikipedia.org/wiki/Port_mirroring
diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index c91207cab2..7681ed93f2 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -175,3 +175,8 @@ Deprecation Notices
   without relying on flow API.
   Currently there is no alternative API
   providing the same functionality as with ``repr_matching_en`` set to 0.
+
+* pdump: The packet dump library is deprecated and will be removed
+  in 26.11 release. The pdump library uses callbacks and therefore
+  is unable to capture packets sent or received by a secondary process.
+  It is superseded by the port mirroring API.
diff --git a/doc/guides/rel_notes/release_25_11.rst b/doc/guides/rel_notes/release_25_11.rst
index ccad6d89ff..0348889fe3 100644
--- a/doc/guides/rel_notes/release_25_11.rst
+++ b/doc/guides/rel_notes/release_25_11.rst
@@ -56,6 +56,11 @@ New Features
      =======================================================
 
 
+* **Added port mirroring API.**
+
+  Added new API to ethdev to allow monitoring and collecting packets
+  using port mirroring.
+
 Removed Items
 -------------
 
-- 
2.47.2