doc/guides/nics/pcap_ring.rst

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