[PATCH] doc/guides/nics: split pcap_ring into separate documentation files

[Stephen Hemminger <stephen@networkplumber.org>]

The documentation had combined to unrelated drivers together.
Use AI to split into two separate files:
pcap.rst for the pcap PMD and ring.rst for the ring PMD.

Changes to pcap.rst:
- Use "pcap" consistently instead of mixed "libpcap/pcap/PCAP" naming
- Remove Linux-specific references; document support for Linux, FreeBSD,
  and Windows
- Add reference to upstream libpcap documentation
- Add multi-queue support section explaining queue count determination
  and file handle limitations
- Use ``--vdev=net_pcap0`` format consistently
- Remove deprecated rte_eth_from_pcaps() API section
- Improve technical documentation style throughout

Changes to ring.rst:
- Use ``--vdev=net_ring0`` format consistently
- Fix inconsistent "Rings-based/Ring-based" naming
- Retain rte_eth_from_rings() API section with usage examples
- Improve technical documentation style throughout

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/nics/index.rst     |   3 +-
 doc/guides/nics/pcap.rst      | 220 +++++++++++++++++++++++
 doc/guides/nics/pcap_ring.rst | 318 ----------------------------------
 doc/guides/nics/ring.rst      | 116 +++++++++++++
 4 files changed, 338 insertions(+), 319 deletions(-)
 create mode 100644 doc/guides/nics/pcap.rst
 delete mode 100644 doc/guides/nics/pcap_ring.rst
 create mode 100644 doc/guides/nics/ring.rst

diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index b00ed998c5..cb818284fe 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -60,10 +60,11 @@ Network Interface Controller Drivers
     null
     octeon_ep
     octeontx
-    pcap_ring
+    pcap
     pfe
     qede
     r8169
+    ring
     rnp
     sfc_efx
     softnic
diff --git a/doc/guides/nics/pcap.rst b/doc/guides/nics/pcap.rst
new file mode 100644
index 0000000000..7d8bc4f05a
--- /dev/null
+++ b/doc/guides/nics/pcap.rst
@@ -0,0 +1,220 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2015 Intel Corporation.
+
+Pcap Poll Mode Driver
+=====================
+
+The pcap-based PMD (**librte_net_pcap**) reads and writes packets using the pcap library,
+both from files on disk and from physical NIC devices using standard kernel drivers.
+
+For more information about the pcap library, see the
+`libpcap documentation <https://www.tcpdump.org/manpages/pcap.3pcap.html>`_.
+
+.. note::
+
+    The pcap-based PMD requires the libpcap development files to be installed.
+    This applies to all supported operating systems: Linux, FreeBSD, and Windows.
+
+Using the Driver from the EAL Command Line
+------------------------------------------
+
+The DPDK EAL has been extended to allow pseudo-Ethernet devices,
+using the pcap driver, to be created at application startup time during EAL initialization.
+
+To do so, pass the ``--vdev=net_pcap0`` parameter to the EAL.
+This parameter accepts options to allocate and use pcap-based Ethernet transparently by the application.
+This can be used, for example, for testing on a virtual machine where there are no Ethernet ports.
+
+Pcap-based PMD
+~~~~~~~~~~~~~~
+
+Pcap-based devices can be created using the virtual device ``--vdev=net_pcap0`` option.
+The device name must start with the net_pcap prefix followed by numbers or letters.
+The name must be unique for each device. Each device can have multiple stream options and multiple devices can be used.
+Multiple device definitions can be specified using multiple ``--vdev`` arguments.
+Device name and stream options must be separated by commas as shown below:
+
+.. code-block:: console
+
+   ./<build_dir>/app/dpdk-testpmd -l 0-3 \
+       --vdev 'net_pcap0,stream_opt0=..,stream_opt1=..' \
+       --vdev='net_pcap1,stream_opt0=..'
+
+Device Streams
+^^^^^^^^^^^^^^
+
+Stream definitions can be combined as long as one of the following two rules is met:
+
+*   A device is provided with two different streams - reception and transmission.
+
+*   A device is provided with one network interface name used for reading and writing packets.
+
+The stream types are:
+
+*   rx_pcap: Defines a reception stream based on a pcap file.
+    The driver reads each packet within the given pcap file as if it was receiving it from the wire.
+    The value is a path to a valid pcap file.
+
+        rx_pcap=/path/to/file.pcap
+
+*   tx_pcap: Defines a transmission stream based on a pcap file.
+    The driver writes each received packet to the given pcap file.
+    The value is a path to a pcap file.
+    The file is overwritten if it already exists and it is created if it does not.
+
+        tx_pcap=/path/to/file.pcap
+
+*   rx_iface: Defines a reception stream based on a network interface name.
+    The driver reads packets from the given interface using the kernel driver for that interface.
+    The driver captures both the incoming and outgoing packets on that interface.
+    The value is an interface name.
+
+        rx_iface=eth0
+
+*   rx_iface_in: Defines a reception stream based on a network interface name.
+    The driver reads packets from the given interface using the kernel driver for that interface.
+    The driver captures only the incoming packets on that interface.
+    The value is an interface name.
+
+        rx_iface_in=eth0
+
+*   tx_iface: Defines a transmission stream based on a network interface name.
+    The driver sends packets to the given interface using the kernel driver for that interface.
+    The value is an interface name.
+
+        tx_iface=eth0
+
+*   iface: Defines a device mapping a network interface.
+    The driver both reads and writes packets from and to the given interface.
+    The value is an interface name.
+
+        iface=eth0
+
+Multi-queue Support
+^^^^^^^^^^^^^^^^^^^
+
+The pcap PMD supports multiple receive and transmit queues.
+The number of receive queues is determined by the number of rx_pcap or rx_iface arguments provided.
+Similarly, the number of transmit queues is determined by the number of tx_pcap or tx_iface arguments.
+
+Using the same file for multiple queues is not supported because the underlying
+pcap library does not support concurrent access to a single file handle.
+
+Runtime Config Options
+^^^^^^^^^^^^^^^^^^^^^^
+
+- Use pcap interface physical MAC
+
+ When the ``iface=`` configuration is set, the selected interface's physical MAC
+ address can be used. This can be done with the ``phy_mac`` devarg, for example::
+
+   --vdev 'net_pcap0,iface=eth0,phy_mac=1'
+
+- Use the RX pcap file to infinitely receive packets
+
+ When the ``rx_pcap=`` configuration is set, the selected pcap file can be used for basic
+ performance testing. This can be done with the ``infinite_rx`` devarg, for example::
+
+   --vdev 'net_pcap0,rx_pcap=file_rx.pcap,infinite_rx=1'
+
+ When this mode is used, it is recommended to drop all packets on transmit by not providing a tx_pcap or tx_iface.
+
+ This option is device-wide, so all queues on a device will either have this enabled or disabled.
+ This option should only be provided once per device.
+
+- Drop all packets on transmit
+
+ To drop all packets on transmit for a device, do not provide a tx_pcap or tx_iface, for example::
+
+   --vdev 'net_pcap0,rx_pcap=file_rx.pcap'
+
+ In this case, one tx drop queue is created for each rxq on that device.
+
+- Receive no packets on Rx
+
+ To run without receiving any packets on Rx, do not provide a rx_pcap or rx_iface, for example::
+
+   --vdev 'net_pcap0,tx_pcap=file_tx.pcap'
+
+ In this case, one dummy rx queue is created for each tx queue argument passed.
+
+Examples of Usage
+^^^^^^^^^^^^^^^^^
+
+Read packets from one pcap file and write them to another:
+
+.. code-block:: console
+
+    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
+        --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_pcap=file_tx.pcap' \
+        -- --port-topology=chained
+
+Read packets from a network interface and write them to a pcap file:
+
+.. code-block:: console
+
+    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
+        --vdev 'net_pcap0,rx_iface=eth0,tx_pcap=file_tx.pcap' \
+        -- --port-topology=chained
+
+Read packets from a pcap file and write them to a network interface:
+
+.. code-block:: console
+
+    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
+        --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_iface=eth1' \
+        -- --port-topology=chained
+
+Forward packets through two network interfaces:
+
+.. code-block:: console
+
+    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
+        --vdev 'net_pcap0,iface=eth0' --vdev='net_pcap1,iface=eth1'
+
+Enable 2 tx queues on a network interface:
+
+.. code-block:: console
+
+    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
+        --vdev 'net_pcap0,rx_iface=eth1,tx_iface=eth1,tx_iface=eth1' \
+        -- --txq 2
+
+Read only incoming packets from a network interface and write them back to the same network interface:
+
+.. code-block:: console
+
+    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
+        --vdev 'net_pcap0,rx_iface_in=eth1,tx_iface=eth1'
+
+Using Pcap-based PMD with the testpmd Application
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One of the first things that testpmd does before starting to forward packets is to flush the RX streams
+by reading the first 512 packets on every RX stream and discarding them.
+When using a pcap-based PMD, this behavior can be turned off using the ``--no-flush-rx`` option:
+
+.. code-block:: console
+
+    --no-flush-rx
+
+This option is also available in the runtime command line:
+
+.. code-block:: console
+
+    set flush_rx on/off
+
+It is useful for the case where the rx_pcap is being used and no packets are meant to be discarded.
+Otherwise, the first 512 packets from the input pcap file will be discarded by the RX flushing operation.
+
+.. code-block:: console
+
+    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
+        --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_pcap=file_tx.pcap' \
+        -- --port-topology=chained --no-flush-rx
+
+.. note::
+
+   The network interface provided to the PMD should be up. The PMD will return
+   an error if interface is down, and the PMD itself won't change the status
+   of the external network interface.
diff --git a/doc/guides/nics/pcap_ring.rst b/doc/guides/nics/pcap_ring.rst
deleted file mode 100644
index 6955e91130..0000000000
--- a/doc/guides/nics/pcap_ring.rst
+++ /dev/null
@@ -1,318 +0,0 @@
-..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2010-2015 Intel Corporation.
-
-Libpcap and Ring Based Poll Mode Drivers
-========================================
-
-In addition to Poll Mode Drivers (PMDs) for physical and virtual hardware,
-the DPDK also includes pure-software PMDs, two of these drivers are:
-
-*   A libpcap -based PMD (**librte_net_pcap**) that reads and writes packets using libpcap,
-    - both from files on disk, as well as from physical NIC devices using standard Linux kernel drivers.
-
-*   A ring-based PMD (**librte_net_ring**) that allows a set of software FIFOs (that is, rte_ring)
-    to be accessed using the PMD APIs, as though they were physical NICs.
-
-.. note::
-
-    The libpcap -based PMD has an external dependency on the libpcap development files which must
-    be installed on the board.
-
-Using the Drivers from the EAL Command Line
--------------------------------------------
-
-For ease of use, the DPDK EAL also has been extended to allow pseudo-Ethernet devices,
-using one or more of these drivers,
-to be created at application startup time during EAL initialization.
-
-To do so, the --vdev= parameter must be passed to the EAL.
-This takes take options to allow ring and pcap-based Ethernet to be allocated and used transparently by the application.
-This can be used, for example, for testing on a virtual machine where there are no Ethernet ports.
-
-Libpcap-based PMD
-~~~~~~~~~~~~~~~~~
-
-Pcap-based devices can be created using the virtual device --vdev option.
-The device name must start with the net_pcap prefix followed by numbers or letters.
-The name is unique for each device. Each device can have multiple stream options and multiple devices can be used.
-Multiple device definitions can be arranged using multiple --vdev.
-Device name and stream options must be separated by commas as shown below:
-
-.. code-block:: console
-
-   ./<build_dir>/app/dpdk-testpmd -l 0-3 \
-       --vdev 'net_pcap0,stream_opt0=..,stream_opt1=..' \
-       --vdev='net_pcap1,stream_opt0=..'
-
-Device Streams
-^^^^^^^^^^^^^^
-
-Multiple ways of stream definitions can be assessed and combined as long as the following two rules are respected:
-
-*   A device is provided with two different streams - reception and transmission.
-
-*   A device is provided with one network interface name used for reading and writing packets.
-
-The different stream types are:
-
-*   rx_pcap: Defines a reception stream based on a pcap file.
-    The driver reads each packet within the given pcap file as if it was receiving it from the wire.
-    The value is a path to a valid pcap file.
-
-        rx_pcap=/path/to/file.pcap
-
-*   tx_pcap: Defines a transmission stream based on a pcap file.
-    The driver writes each received packet to the given pcap file.
-    The value is a path to a pcap file.
-    The file is overwritten if it already exists and it is created if it does not.
-
-        tx_pcap=/path/to/file.pcap
-
-*   rx_iface: Defines a reception stream based on a network interface name.
-    The driver reads packets from the given interface using the Linux kernel driver for that interface.
-    The driver captures both the incoming and outgoing packets on that interface.
-    The value is an interface name.
-
-        rx_iface=eth0
-
-*   rx_iface_in: Defines a reception stream based on a network interface name.
-    The driver reads packets from the given interface using the Linux kernel driver for that interface.
-    The driver captures only the incoming packets on that interface.
-    The value is an interface name.
-
-        rx_iface_in=eth0
-
-*   tx_iface: Defines a transmission stream based on a network interface name.
-    The driver sends packets to the given interface using the Linux kernel driver for that interface.
-    The value is an interface name.
-
-        tx_iface=eth0
-
-*   iface: Defines a device mapping a network interface.
-    The driver both reads and writes packets from and to the given interface.
-    The value is an interface name.
-
-        iface=eth0
-
-Runtime Config Options
-^^^^^^^^^^^^^^^^^^^^^^
-
-- Use PCAP interface physical MAC
-
- In case ``iface=`` configuration is set, user may want to use the selected interface's physical MAC
- address. This can be done with a ``devarg`` ``phy_mac``, for example::
-
-   --vdev 'net_pcap0,iface=eth0,phy_mac=1'
-
-- Use the RX PCAP file to infinitely receive packets
-
- In case ``rx_pcap=`` configuration is set, user may want to use the selected PCAP file for rudimental
- performance testing. This can be done with a ``devarg`` ``infinite_rx``, for example::
-
-   --vdev 'net_pcap0,rx_pcap=file_rx.pcap,infinite_rx=1'
-
- When this mode is used, it is recommended to drop all packets on transmit by not providing a tx_pcap or tx_iface.
-
- This option is device wide, so all queues on a device will either have this enabled or disabled.
- This option should only be provided once per device.
-
-- Drop all packets on transmit
-
- The user may want to drop all packets on tx for a device. This can be done by not providing a tx_pcap or tx_iface, for example::
-
-   --vdev 'net_pcap0,rx_pcap=file_rx.pcap'
-
- In this case, one tx drop queue is created for each rxq on that device.
-
- - Receive no packets on Rx
-
- The user may want to run without receiving any packets on Rx. This can be done by not providing a rx_pcap or rx_iface, for example::
-
-   --vdev 'net_pcap0,tx_pcap=file_tx.pcap'
-
-In this case, one dummy rx queue is created for each tx queue argument passed
-
-Examples of Usage
-^^^^^^^^^^^^^^^^^
-
-Read packets from one pcap file and write them to another:
-
-.. code-block:: console
-
-    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
-        --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_pcap=file_tx.pcap' \
-        -- --port-topology=chained
-
-Read packets from a network interface and write them to a pcap file:
-
-.. code-block:: console
-
-    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
-        --vdev 'net_pcap0,rx_iface=eth0,tx_pcap=file_tx.pcap' \
-        -- --port-topology=chained
-
-Read packets from a pcap file and write them to a network interface:
-
-.. code-block:: console
-
-    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
-        --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_iface=eth1' \
-        -- --port-topology=chained
-
-Forward packets through two network interfaces:
-
-.. code-block:: console
-
-    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
-        --vdev 'net_pcap0,iface=eth0' --vdev='net_pcap1,iface=eth1'
-
-Enable 2 tx queues on a network interface:
-
-.. code-block:: console
-
-    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
-        --vdev 'net_pcap0,rx_iface=eth1,tx_iface=eth1,tx_iface=eth1' \
-        -- --txq 2
-
-Read only incoming packets from a network interface and write them back to the same network interface:
-
-.. code-block:: console
-
-    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
-        --vdev 'net_pcap0,rx_iface_in=eth1,tx_iface=eth1'
-
-Using libpcap-based PMD with the testpmd Application
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-One of the first things that testpmd does before starting to forward packets is to flush the RX streams
-by reading the first 512 packets on every RX stream and discarding them.
-When using a libpcap-based PMD this behavior can be turned off using the following command line option:
-
-.. code-block:: console
-
-    --no-flush-rx
-
-It is also available in the runtime command line:
-
-.. code-block:: console
-
-    set flush_rx on/off
-
-It is useful for the case where the rx_pcap is being used and no packets are meant to be discarded.
-Otherwise, the first 512 packets from the input pcap file will be discarded by the RX flushing operation.
-
-.. code-block:: console
-
-    ./<build_dir>/app/dpdk-testpmd -l 0-3 \
-        --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_pcap=file_tx.pcap' \
-        -- --port-topology=chained --no-flush-rx
-
-.. note::
-
-   The network interface provided to the PMD should be up. The PMD will return
-   an error if interface is down, and the PMD itself won't change the status
-   of the external network interface.
-
-
-Rings-based PMD
-~~~~~~~~~~~~~~~
-
-To run a DPDK application on a machine without any Ethernet devices, a pair of ring-based rte_ethdevs can be used as below.
-The device names passed to the --vdev option must start with net_ring and take no additional parameters.
-Multiple devices may be specified, separated by commas.
-
-.. code-block:: console
-
-    ./dpdk-testpmd -l 1-3 --vdev=net_ring0 --vdev=net_ring1 -- -i
-    ...
-    Interactive-mode selected
-    Configuring Port 0 (socket 0)
-    Configuring Port 1 (socket 0)
-    Checking link statuses...
-    Port 0 Link Up - speed 10000 Mbps - full-duplex
-    Port 1 Link Up - speed 10000 Mbps - full-duplex
-    Done
-
-    testpmd> start tx_first
-    io packet forwarding - CRC stripping disabled - packets/burst=16
-    nb forwarding cores=1 - nb forwarding ports=2
-    RX queues=1 - RX desc=128 - RX free threshold=0
-    RX threshold registers: pthresh=8 hthresh=8 wthresh=4
-    TX queues=1 - TX desc=512 - TX free threshold=0
-    TX threshold registers: pthresh=36 hthresh=0 wthresh=0
-    TX RS bit threshold=0 - TXQ flags=0x0
-
-    testpmd> stop
-    Telling cores to stop...
-    Waiting for lcores to finish...
-
-.. image:: img/forward_stats.*
-
-.. code-block:: console
-
-    +++++++++++++++ Accumulated forward statistics for allports++++++++++
-    RX-packets: 462384736  RX-dropped: 0 RX-total: 462384736
-    TX-packets: 462384768  TX-dropped: 0 TX-total: 462384768
-    +++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-    Done.
-
-
-Using the Poll Mode Driver from an Application
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Both drivers can provide similar APIs to allow the user to create a PMD, that is,
-rte_ethdev structure, instances at run-time in the end-application,
-for example, using rte_eth_from_rings() or rte_eth_from_pcaps() APIs.
-For the rings-based PMD, this functionality could be used, for example,
-to allow data exchange between cores using rings to be done in exactly the
-same way as sending or receiving packets from an Ethernet device.
-For the libpcap-based PMD, it allows an application to open one or more pcap files
-and use these as a source of packet input to the application.
-
-Usage Examples
-^^^^^^^^^^^^^^
-
-To create two pseudo-Ethernet ports where all traffic sent to a port is looped back
-for reception on the same port (error handling omitted for clarity):
-
-.. code-block:: c
-
-    #define RING_SIZE 256
-    #define NUM_RINGS 2
-    #define SOCKET0 0
-
-    struct rte_ring *ring[NUM_RINGS];
-    int port0, port1;
-
-    ring[0] = rte_ring_create("R0", RING_SIZE, SOCKET0, RING_F_SP_ENQ|RING_F_SC_DEQ);
-    ring[1] = rte_ring_create("R1", RING_SIZE, SOCKET0, RING_F_SP_ENQ|RING_F_SC_DEQ);
-
-    /* create two ethdev's */
-
-    port0 = rte_eth_from_rings("net_ring0", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0);
-    port1 = rte_eth_from_rings("net_ring1", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0);
-
-
-To create two pseudo-Ethernet ports where the traffic is switched between them,
-that is, traffic sent to port 0 is read back from port 1 and vice-versa,
-the final two lines could be changed as below:
-
-.. code-block:: c
-
-    port0 = rte_eth_from_rings("net_ring0", &ring[0], 1, &ring[1], 1, SOCKET0);
-    port1 = rte_eth_from_rings("net_ring1", &ring[1], 1, &ring[0], 1, SOCKET0);
-
-This type of configuration could be useful in a pipeline model, for example,
-where one may want to have inter-core communication using pseudo Ethernet devices rather than raw rings,
-for reasons of API consistency.
-
-Enqueuing and dequeuing items from an rte_ring using the rings-based PMD may be slower than using the native rings API.
-This is because DPDK Ethernet drivers make use of function pointers to call the appropriate enqueue or dequeue functions,
-while the rte_ring specific functions are direct function calls in the code and are often inlined by the compiler.
-
-   Once an ethdev has been created, for either a ring or a pcap-based PMD,
-   it should be configured and started in the same way as a regular Ethernet device, that is,
-   by calling rte_eth_dev_configure() to set the number of receive and transmit queues,
-   then calling rte_eth_rx_queue_setup() / tx_queue_setup() for each of those queues and
-   finally calling rte_eth_dev_start() to allow transmission and reception of packets to begin.
diff --git a/doc/guides/nics/ring.rst b/doc/guides/nics/ring.rst
new file mode 100644
index 0000000000..d4f080c818
--- /dev/null
+++ b/doc/guides/nics/ring.rst
@@ -0,0 +1,116 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2015 Intel Corporation.
+
+Ring Based Poll Mode Driver
+===========================
+
+The ring-based PMD (**librte_net_ring**) allows software FIFOs (rte_ring) to be accessed
+using the PMD APIs, as though they were physical NICs.
+
+Using the Driver from the EAL Command Line
+------------------------------------------
+
+The DPDK EAL has been extended to allow pseudo-Ethernet devices,
+using the ring driver, to be created at application startup time during EAL initialization.
+
+To do so, pass the ``--vdev=net_ring0`` parameter to the EAL.
+This parameter accepts options to allocate and use ring-based Ethernet transparently by the application.
+This can be used, for example, for testing on a virtual machine where there are no Ethernet ports.
+
+Ring-based PMD
+~~~~~~~~~~~~~~
+
+To run a DPDK application on a machine without any Ethernet devices, a pair of ring-based rte_ethdevs can be used as below.
+The device names passed to the ``--vdev`` option must start with net_ring and take no additional parameters.
+Multiple devices may be specified using multiple ``--vdev`` arguments.
+
+.. code-block:: console
+
+    ./dpdk-testpmd -l 1-3 --vdev=net_ring0 --vdev=net_ring1 -- -i
+    ...
+    Interactive-mode selected
+    Configuring Port 0 (socket 0)
+    Configuring Port 1 (socket 0)
+    Checking link statuses...
+    Port 0 Link Up - speed 10000 Mbps - full-duplex
+    Port 1 Link Up - speed 10000 Mbps - full-duplex
+    Done
+
+    testpmd> start tx_first
+    io packet forwarding - CRC stripping disabled - packets/burst=16
+    nb forwarding cores=1 - nb forwarding ports=2
+    RX queues=1 - RX desc=128 - RX free threshold=0
+    RX threshold registers: pthresh=8 hthresh=8 wthresh=4
+    TX queues=1 - TX desc=512 - TX free threshold=0
+    TX threshold registers: pthresh=36 hthresh=0 wthresh=0
+    TX RS bit threshold=0 - TXQ flags=0x0
+
+    testpmd> stop
+    Telling cores to stop...
+    Waiting for lcores to finish...
+
+.. image:: img/forward_stats.*
+
+.. code-block:: console
+
+    +++++++++++++++ Accumulated forward statistics for allports++++++++++
+    RX-packets: 462384736  RX-dropped: 0 RX-total: 462384736
+    TX-packets: 462384768  TX-dropped: 0 TX-total: 462384768
+    +++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+    Done.
+
+
+Using the Ring-based PMD from an Application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The driver provides APIs to create PMD (rte_ethdev structure) instances at run-time
+in the end-application using the rte_eth_from_rings() API.
+This functionality can be used to allow data exchange between cores using rings
+in the same way as sending or receiving packets from an Ethernet device.
+
+Usage Examples
+^^^^^^^^^^^^^^
+
+To create two pseudo-Ethernet ports where all traffic sent to a port is looped back
+for reception on the same port (error handling omitted for clarity):
+
+.. code-block:: c
+
+    #define RING_SIZE 256
+    #define NUM_RINGS 2
+    #define SOCKET0 0
+
+    struct rte_ring *ring[NUM_RINGS];
+    int port0, port1;
+
+    ring[0] = rte_ring_create("R0", RING_SIZE, SOCKET0, RING_F_SP_ENQ|RING_F_SC_DEQ);
+    ring[1] = rte_ring_create("R1", RING_SIZE, SOCKET0, RING_F_SP_ENQ|RING_F_SC_DEQ);
+
+    /* create two ethdev's */
+
+    port0 = rte_eth_from_rings("net_ring0", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0);
+    port1 = rte_eth_from_rings("net_ring1", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0);
+
+
+To create two pseudo-Ethernet ports where the traffic is switched between them
+(traffic sent to port 0 is read back from port 1 and vice-versa),
+the final two lines can be changed as follows:
+
+.. code-block:: c
+
+    port0 = rte_eth_from_rings("net_ring0", &ring[0], 1, &ring[1], 1, SOCKET0);
+    port1 = rte_eth_from_rings("net_ring1", &ring[1], 1, &ring[0], 1, SOCKET0);
+
+This type of configuration is useful in a pipeline model where inter-core communication
+using pseudo Ethernet devices is preferred over raw rings for API consistency.
+
+Enqueuing and dequeuing items from an rte_ring using the ring-based PMD may be slower than using the native rings API.
+DPDK Ethernet drivers use function pointers to call the appropriate enqueue or dequeue functions,
+while the rte_ring specific functions are direct function calls and are often inlined by the compiler.
+
+Once an ethdev has been created for a ring-based PMD,
+it should be configured and started in the same way as a regular Ethernet device:
+call rte_eth_dev_configure() to set the number of receive and transmit queues,
+then call rte_eth_rx_queue_setup() / tx_queue_setup() for each of those queues,
+and finally call rte_eth_dev_start() to allow transmission and reception of packets to begin.
-- 
2.51.0