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