Add ethdev port mirror to documentation.
Signed-off-by: Stephen Hemminger <step...@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
