doc/guides/nics/pcap_ring.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2015 Intel Corporation.
   3
   4 Libpcap and Ring Based Poll Mode Drivers
   5 ========================================
   6
   7 In addition to Poll Mode Drivers (PMDs) for physical and virtual hardware,
   8 the DPDK also includes pure-software PMDs, two of these drivers are:
   9
  10 *   A libpcap -based PMD (librte_pmd_pcap) that reads and writes packets using libpcap,
  11     - both from files on disk, as well as from physical NIC devices using standard Linux kernel drivers.
  12
  13 *   A ring-based PMD (librte_pmd_ring) that allows a set of software FIFOs (that is, rte_ring)
  14     to be accessed using the PMD APIs, as though they were physical NICs.
  15
  16 .. note::
  17
  18     The libpcap -based PMD is disabled by default in the build configuration files,
  19     owing to an external dependency on the libpcap development files which must be installed on the board.
  20     Once the libpcap development files are installed,
  21     the library can be enabled by setting CONFIG_RTE_LIBRTE_PMD_PCAP=y and recompiling the DPDK.
  22
  23 Using the Drivers from the EAL Command Line
  24 -------------------------------------------
  25
  26 For ease of use, the DPDK EAL also has been extended to allow pseudo-Ethernet devices,
  27 using one or more of these drivers,
  28 to be created at application startup time during EAL initialization.
  29
  30 To do so, the --vdev= parameter must be passed to the EAL.
  31 This takes take options to allow ring and pcap-based Ethernet to be allocated and used transparently by the application.
  32 This can be used, for example, for testing on a virtual machine where there are no Ethernet ports.
  33
  34 Libpcap-based PMD
  35 ~~~~~~~~~~~~~~~~~
  36
  37 Pcap-based devices can be created using the virtual device --vdev option.
  38 The device name must start with the net_pcap prefix followed by numbers or letters.
  39 The name is unique for each device. Each device can have multiple stream options and multiple devices can be used.
  40 Multiple device definitions can be arranged using multiple --vdev.
  41 Device name and stream options must be separated by commas as shown below:
  42
  43 .. code-block:: console
  44
  45    $RTE_TARGET/app/testpmd -l 0-3 -n 4 \
  46        --vdev 'net_pcap0,stream_opt0=..,stream_opt1=..' \
  47        --vdev='net_pcap1,stream_opt0=..'
  48
  49 Device Streams
  50 ^^^^^^^^^^^^^^
  51
  52 Multiple ways of stream definitions can be assessed and combined as long as the following two rules are respected:
  53
  54 *   A device is provided with two different streams - reception and transmission.
  55
  56 *   A device is provided with one network interface name used for reading and writing packets.
  57
  58 The different stream types are:
  59
  60 *   rx_pcap: Defines a reception stream based on a pcap file.
  61     The driver reads each packet within the given pcap file as if it was receiving it from the wire.
  62     The value is a path to a valid pcap file.
  63
  64         rx_pcap=/path/to/file.pcap
  65
  66 *   tx_pcap: Defines a transmission stream based on a pcap file.
  67     The driver writes each received packet to the given pcap file.
  68     The value is a path to a pcap file.
  69     The file is overwritten if it already exists and it is created if it does not.
  70
  71         tx_pcap=/path/to/file.pcap
  72
  73 *   rx_iface: Defines a reception stream based on a network interface name.
  74     The driver reads packets coming from the given interface using the Linux kernel driver for that interface.
  75     The value is an interface name.
  76
  77         rx_iface=eth0
  78
  79 *   tx_iface: Defines a transmission stream based on a network interface name.
  80     The driver sends packets to the given interface using the Linux kernel driver for that interface.
  81     The value is an interface name.
  82
  83         tx_iface=eth0
  84
  85 *   iface: Defines a device mapping a network interface.
  86     The driver both reads and writes packets from and to the given interface.
  87     The value is an interface name.
  88
  89         iface=eth0
  90
  91 Examples of Usage
  92 ^^^^^^^^^^^^^^^^^
  93
  94 Read packets from one pcap file and write them to another:
  95
  96 .. code-block:: console
  97
  98     $RTE_TARGET/app/testpmd -l 0-3 -n 4 \
  99         --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_pcap=file_tx.pcap' \
 100         -- --port-topology=chained
 101
 102 Read packets from a network interface and write them to a pcap file:
 103
 104 .. code-block:: console
 105
 106     $RTE_TARGET/app/testpmd -l 0-3 -n 4 \
 107         --vdev 'net_pcap0,rx_iface=eth0,tx_pcap=file_tx.pcap' \
 108         -- --port-topology=chained
 109
 110 Read packets from a pcap file and write them to a network interface:
 111
 112 .. code-block:: console
 113
 114     $RTE_TARGET/app/testpmd -l 0-3 -n 4 \
 115         --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_iface=eth1' \
 116         -- --port-topology=chained
 117
 118 Forward packets through two network interfaces:
 119
 120 .. code-block:: console
 121
 122     $RTE_TARGET/app/testpmd -l 0-3 -n 4 \
 123         --vdev 'net_pcap0,iface=eth0' --vdev='net_pcap1;iface=eth1'
 124
 125 Using libpcap-based PMD with the testpmd Application
 126 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 127
 128 One of the first things that testpmd does before starting to forward packets is to flush the RX streams
 129 by reading the first 512 packets on every RX stream and discarding them.
 130 When using a libpcap-based PMD this behavior can be turned off using the following command line option:
 131
 132 .. code-block:: console
 133
 134     --no-flush-rx
 135
 136 It is also available in the runtime command line:
 137
 138 .. code-block:: console
 139
 140     set flush_rx on/off
 141
 142 It is useful for the case where the rx_pcap is being used and no packets are meant to be discarded.
 143 Otherwise, the first 512 packets from the input pcap file will be discarded by the RX flushing operation.
 144
 145 .. code-block:: console
 146
 147     $RTE_TARGET/app/testpmd -l 0-3 -n 4 \
 148         --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_pcap=file_tx.pcap' \
 149         -- --port-topology=chained --no-flush-rx
 150
 151 .. note::
 152
 153    The network interface provided to the PMD should be up. The PMD will return
 154    an error if interface is down, and the PMD itself won't change the status
 155    of the external network interface.
 156
 157
 158 Rings-based PMD
 159 ~~~~~~~~~~~~~~~
 160
 161 To run a DPDK application on a machine without any Ethernet devices, a pair of ring-based rte_ethdevs can be used as below.
 162 The device names passed to the --vdev option must start with net_ring and take no additional parameters.
 163 Multiple devices may be specified, separated by commas.
 164
 165 .. code-block:: console
 166
 167     ./testpmd -l 1-3 -n 4 --vdev=net_ring0 --vdev=net_ring1 -- -i
 168     EAL: Detected lcore 1 as core 1 on socket 0
 169     ...
 170
 171     Interactive-mode selected
 172     Configuring Port 0 (socket 0)
 173     Configuring Port 1 (socket 0)
 174     Checking link statuses...
 175     Port 0 Link Up - speed 10000 Mbps - full-duplex
 176     Port 1 Link Up - speed 10000 Mbps - full-duplex
 177     Done
 178
 179     testpmd> start tx_first
 180     io packet forwarding - CRC stripping disabled - packets/burst=16
 181     nb forwarding cores=1 - nb forwarding ports=2
 182     RX queues=1 - RX desc=128 - RX free threshold=0
 183     RX threshold registers: pthresh=8 hthresh=8 wthresh=4
 184     TX queues=1 - TX desc=512 - TX free threshold=0
 185     TX threshold registers: pthresh=36 hthresh=0 wthresh=0
 186     TX RS bit threshold=0 - TXQ flags=0x0
 187
 188     testpmd> stop
 189     Telling cores to stop...
 190     Waiting for lcores to finish...
 191
 192 .. image:: img/forward_stats.*
 193
 194 .. code-block:: console
 195
 196     +++++++++++++++ Accumulated forward statistics for allports++++++++++
 197     RX-packets: 462384736  RX-dropped: 0 RX-total: 462384736
 198     TX-packets: 462384768  TX-dropped: 0 TX-total: 462384768
 199     +++++++++++++++++++++++++++++++++++++++++++++++++++++
 200
 201     Done.
 202
 203
 204 Using the Poll Mode Driver from an Application
 205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 206
 207 Both drivers can provide similar APIs to allow the user to create a PMD, that is,
 208 rte_ethdev structure, instances at run-time in the end-application,
 209 for example, using rte_eth_from_rings() or rte_eth_from_pcaps() APIs.
 210 For the rings-based PMD, this functionality could be used, for example,
 211 to allow data exchange between cores using rings to be done in exactly the
 212 same way as sending or receiving packets from an Ethernet device.
 213 For the libpcap-based PMD, it allows an application to open one or more pcap files
 214 and use these as a source of packet input to the application.
 215
 216 Usage Examples
 217 ^^^^^^^^^^^^^^
 218
 219 To create two pseudo-Ethernet ports where all traffic sent to a port is looped back
 220 for reception on the same port (error handling omitted for clarity):
 221
 222 .. code-block:: c
 223
 224     #define RING_SIZE 256
 225     #define NUM_RINGS 2
 226     #define SOCKET0 0
 227
 228     struct rte_ring *ring[NUM_RINGS];
 229     int port0, port1;
 230
 231     ring[0] = rte_ring_create("R0", RING_SIZE, SOCKET0, RING_F_SP_ENQ|RING_F_SC_DEQ);
 232     ring[1] = rte_ring_create("R1", RING_SIZE, SOCKET0, RING_F_SP_ENQ|RING_F_SC_DEQ);
 233
 234     /* create two ethdev's */
 235
 236     port0 = rte_eth_from_rings("net_ring0", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0);
 237     port1 = rte_eth_from_rings("net_ring1", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0);
 238
 239
 240 To create two pseudo-Ethernet ports where the traffic is switched between them,
 241 that is, traffic sent to port 0 is read back from port 1 and vice-versa,
 242 the final two lines could be changed as below:
 243
 244 .. code-block:: c
 245
 246     port0 = rte_eth_from_rings("net_ring0", &ring[0], 1, &ring[1], 1, SOCKET0);
 247     port1 = rte_eth_from_rings("net_ring1", &ring[1], 1, &ring[0], 1, SOCKET0);
 248
 249 This type of configuration could be useful in a pipeline model, for example,
 250 where one may want to have inter-core communication using pseudo Ethernet devices rather than raw rings,
 251 for reasons of API consistency.
 252
 253 Enqueuing and dequeuing items from an rte_ring using the rings-based PMD may be slower than using the native rings API.
 254 This is because DPDK Ethernet drivers make use of function pointers to call the appropriate enqueue or dequeue functions,
 255 while the rte_ring specific functions are direct function calls in the code and are often inlined by the compiler.
 256
 257    Once an ethdev has been created, for either a ring or a pcap-based PMD,
 258    it should be configured and started in the same way as a regular Ethernet device, that is,
 259    by calling rte_eth_dev_configure() to set the number of receive and transmit queues,
 260    then calling rte_eth_rx_queue_setup() / tx_queue_setup() for each of those queues and
 261    finally calling rte_eth_dev_start() to allow transmission and reception of packets to begin.