3 Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
6 Redistribution and use in source and binary forms, with or without
7 modification, are permitted provided that the following conditions
10 * Redistributions of source code must retain the above copyright
11 notice, this list of conditions and the following disclaimer.
12 * Redistributions in binary form must reproduce the above copyright
13 notice, this list of conditions and the following disclaimer in
14 the documentation and/or other materials provided with the
16 * Neither the name of Intel Corporation nor the names of its
17 contributors may be used to endorse or promote products derived
18 from this software without specific prior written permission.
20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 TEP termination Sample Application
34 ==================================
36 The TEP (Tunnel End point) termination sample application simulates a VXLAN
37 Tunnel Endpoint (VTEP) termination in DPDK, which is used to demonstrate
38 the offload and filtering capabilities of Intel® XL710 10/40 Gigabit Ethernet
39 Controller for VXLAN packet.
40 This sample uses the basic virtio devices management mechanism from vhost example,
41 and also uses the us-vHost interface and tunnel filtering mechanism to direct
42 a specified traffic to a specific VM.
43 In addition, this sample is also designed to show how tunneling protocols can be handled.
48 With virtualization, overlay networks allow a network structure to be built
49 or imposed across physical nodes which is abstracted away from the actual
50 underlining physical network connections.
51 This allows network isolation, QOS, etc to be provided on a per client basis.
53 .. _figure_overlay_networking:
55 .. figure:: img/overlay_networking.*
59 In a typical setup, the network overlay tunnel is terminated at the Virtual/Tunnel End Point (VEP/TEP).
60 The TEP is normally located at the physical host level ideally in the software switch.
61 Due to processing constraints and the inevitable bottleneck that the switch
62 becomes, the ability to offload overlay support features becomes an important requirement.
63 Intel® XL710 10/40 Gigabit Ethernet network card provides hardware filtering
64 and offload capabilities to support overlay networks implementations such as MAC in UDP and MAC in GRE.
69 The DPDK TEP termination sample code demonstrates the offload and filtering
70 capabilities of Intel® XL710 10/40 Gigabit Ethernet Controller for VXLAN packet.
72 The sample code is based on vhost library.
73 The vhost library is developed for user space Ethernet switch to easily integrate with vhost functionality.
75 The sample will support the followings:
77 * Tunneling packet recognition.
79 * The port of UDP tunneling is configurable
81 * Directing incoming traffic to the correct queue based on the tunnel filter type.
82 The supported filter type are listed below.
84 * Inner MAC and VLAN and tenant ID
86 * Inner MAC and tenant ID, and Outer MAC
88 * Inner MAC and tenant ID
90 The tenant ID will be assigned from a static internal table based on the us-vhost device ID.
91 Each device will receive a unique device ID.
92 The inner MAC will be learned by the first packet transmitted from a device.
94 * Decapsulation of RX VXLAN traffic. This is a software only operation.
96 * Encapsulation of TX VXLAN traffic. This is a software only operation.
98 * Inner IP and inner L4 checksum offload.
100 * TSO offload support for tunneling packet.
102 The following figure shows the framework of the TEP termination sample
103 application based on DPDK vhost lib.
105 .. _figure_tep_termination_arch:
107 .. figure:: img/tep_termination_arch.*
109 TEP termination Framework Overview
111 Supported Distributions
112 -----------------------
114 The example in this section have been validated with the following distributions:
122 Compiling the Sample Code
123 -------------------------
125 To enable vhost, turn on vhost library in the configure file
126 ``config/common_linuxapp``.
128 .. code-block:: console
130 CONFIG_RTE_LIBRTE_VHOST=y
132 Then following the to compile the sample application shown in
135 Running the Sample Code
136 -----------------------
138 #. Go to the examples directory:
140 .. code-block:: console
142 export RTE_SDK=/path/to/rte_sdk
143 cd ${RTE_SDK}/examples/tep_termination
145 #. Run the tep_termination sample code:
147 .. code-block:: console
149 user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
150 -p 0x1 --dev-basename tep-termination --nb-devices 4
151 --udp-port 4789 --filter-type 1
155 Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.
160 **The same parameters with the vhost sample.**
162 Refer to :ref:`vhost_app_parameters` for detailed explanation.
164 **Number of Devices.**
166 The nb-devices option specifies the number of virtIO device.
167 The default value is 2.
169 .. code-block:: console
171 user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
174 **Tunneling UDP port.**
176 The udp-port option is used to specify the destination UDP number for UDP tunneling packet.
177 The default value is 4789.
179 .. code-block:: console
181 user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
182 --nb-devices 2 --udp-port 4789
186 The filter-type option is used to specify which filter type is used to
187 filter UDP tunneling packet to a specified queue.
188 The default value is 1, which means the filter type of inner MAC and tenant ID is used.
190 .. code-block:: console
192 user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
193 --nb-devices 2 --udp-port 4789 --filter-type 1
197 The tx-checksum option is used to enable or disable the inner header checksum offload.
198 The default value is 0, which means the checksum offload is disabled.
200 .. code-block:: console
202 user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
203 --nb-devices 2 --tx-checksum
205 **TCP segment size.**
207 The tso-segsz option specifies the TCP segment size for TSO offload for tunneling packet.
208 The default value is 0, which means TSO offload is disabled.
210 .. code-block:: console
212 user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
213 --tx-checksum --tso-segsz 800
215 **Decapsulation option.**
217 The decap option is used to enable or disable decapsulation operation for received VXLAN packet.
218 The default value is 1.
220 .. code-block:: console
222 user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
223 --nb-devices 4 --udp-port 4789 --decap 1
225 **Encapsulation option.**
227 The encap option is used to enable or disable encapsulation operation for transmitted packet.
228 The default value is 1.
230 .. code-block:: console
232 user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
233 --nb-devices 4 --udp-port 4789 --encap 1
236 Running the Virtual Machine (QEMU)
237 ----------------------------------
239 Refer to :ref:`vhost_app_run_vm`.
241 Running DPDK in the Virtual Machine
242 -----------------------------------
244 Refer to :ref:`vhost_app_run_dpdk_inside_guest`.
246 Passing Traffic to the Virtual Machine Device
247 ---------------------------------------------
249 For a virtio-net device to receive traffic, the traffic's Layer 2 header must include
250 both the virtio-net device's MAC address.
251 The DPDK sample code behaves in a similar manner to a learning switch in that
252 it learns the MAC address of the virtio-net devices from the first transmitted packet.
253 On learning the MAC address,
254 the DPDK vhost sample code prints a message with the MAC address and tenant ID virtio-net device.
257 .. code-block:: console
259 DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VNI 1000 registered
261 The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VNI 1000.
262 Any packets received on the NIC with these values are placed on the devices receive queue.