doc/guides/sample_app_ug/tep_termination.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2015 Intel Corporation.
   3
   4 TEP termination Sample Application
   5 ==================================
   6
   7 The TEP (Tunnel End point) termination sample application simulates a VXLAN
   8 Tunnel Endpoint (VTEP) termination in DPDK, which is used to demonstrate
   9 the offload and filtering capabilities of Intel® XL710 10/40 Gigabit Ethernet
  10 Controller for VXLAN packet.
  11 This sample uses the basic virtio devices management mechanism from vhost example,
  12 and also uses the us-vHost interface and tunnel filtering mechanism to direct
  13 a specified traffic to a specific VM.
  14 In addition, this sample is also designed to show how tunneling protocols can be handled.
  15
  16 Background
  17 ----------
  18
  19 With virtualization, overlay networks allow a network structure to be built
  20 or imposed across physical nodes which is abstracted away from the actual
  21 underlining physical network connections.
  22 This allows network isolation, QOS, etc to be provided on a per client basis.
  23
  24 .. _figure_overlay_networking:
  25
  26 .. figure:: img/overlay_networking.*
  27
  28    Overlay Networking.
  29
  30 In a typical setup, the network overlay tunnel is terminated at the Virtual/Tunnel End Point (VEP/TEP).
  31 The TEP is normally located at the physical host level ideally in the software switch.
  32 Due to processing constraints and the inevitable bottleneck that the switch
  33 becomes, the ability to offload overlay support features becomes an important requirement.
  34 Intel® XL710 10/40 Gigabit Ethernet network card provides hardware filtering
  35 and offload capabilities to support overlay networks implementations such as MAC in UDP and MAC in GRE.
  36
  37 Sample Code Overview
  38 --------------------
  39
  40 The DPDK TEP termination sample code demonstrates the offload and filtering
  41 capabilities of Intel® XL710 10/40 Gigabit Ethernet Controller for VXLAN packet.
  42
  43 The sample code is based on vhost library.
  44 The vhost library is developed for user space Ethernet switch to easily integrate with vhost functionality.
  45
  46 The sample will support the followings:
  47
  48 *   Tunneling packet recognition.
  49
  50 *   The port of UDP tunneling is configurable
  51
  52 *   Directing incoming traffic to the correct queue based on the tunnel filter type.
  53     The supported filter type are listed below.
  54
  55     * Inner MAC and VLAN and tenant ID
  56
  57     * Inner MAC and tenant ID, and Outer MAC
  58
  59     * Inner MAC and tenant ID
  60
  61     The tenant ID will be assigned from a static internal table based on the us-vhost device ID.
  62     Each device will receive a unique device ID.
  63     The inner MAC will be learned by the first packet transmitted from a device.
  64
  65 *   Decapsulation of RX VXLAN traffic. This is a software only operation.
  66
  67 *   Encapsulation of TX VXLAN traffic. This is a software only operation.
  68
  69 *   Inner IP and inner L4 checksum offload.
  70
  71 *   TSO offload support for tunneling packet.
  72
  73 The following figure shows the framework of the TEP termination sample
  74 application based on DPDK vhost lib.
  75
  76 .. _figure_tep_termination_arch:
  77
  78 .. figure:: img/tep_termination_arch.*
  79
  80    TEP termination Framework Overview
  81
  82 Supported Distributions
  83 -----------------------
  84
  85 The example in this section have been validated with the following distributions:
  86
  87 *   Fedora* 18
  88
  89 *   Fedora* 19
  90
  91 *   Fedora* 20
  92
  93
  94 Running the Sample Code
  95 -----------------------
  96
  97 Run the tep_termination sample code:
  98
  99 .. code-block:: console
 100
 101     user@target:~$ ./<build_dir>/examples/dpdk-tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 102                     -p 0x1 --dev-basename tep-termination --nb-devices 4
 103                     --udp-port 4789 --filter-type 1
 104
 105 .. note::
 106
 107     Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.
 108
 109 Parameters
 110 ~~~~~~~~~~
 111
 112 **The same parameters with the vhost sample.**
 113
 114 Refer to :ref:`vhost_app_parameters` for detailed explanation.
 115
 116 **Number of Devices.**
 117
 118 The nb-devices option specifies the number of virtIO device.
 119 The default value is 2.
 120
 121 .. code-block:: console
 122
 123     user@target:~$ ./<build_dir>/examples/dpdk-tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 124                     --nb-devices 2
 125
 126 **Tunneling UDP port.**
 127
 128 The udp-port option is used to specify the destination UDP number for UDP tunneling packet.
 129 The default value is 4789.
 130
 131 .. code-block:: console
 132
 133     user@target:~$ ./<build_dir>/examples/dpdk-tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 134                     --nb-devices 2 --udp-port 4789
 135
 136 **Filter Type.**
 137
 138 The filter-type option is used to specify which filter type is used to
 139 filter UDP tunneling packet to a specified queue.
 140 The default value is 1, which means the filter type of inner MAC and tenant ID is used.
 141
 142 .. code-block:: console
 143
 144     user@target:~$ ./<build_dir>/examples/dpdk-tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 145                 --nb-devices 2 --udp-port 4789 --filter-type 1
 146
 147 **TX Checksum.**
 148
 149 The tx-checksum option is used to enable or disable the inner header checksum offload.
 150 The default value is 0, which means the checksum offload is disabled.
 151
 152 .. code-block:: console
 153
 154     user@target:~$ ./<build_dir>/examples/dpdk-tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 155                 --nb-devices 2 --tx-checksum
 156
 157 **TCP segment size.**
 158
 159 The tso-segsz option specifies the TCP segment size for TSO offload for tunneling packet.
 160 The default value is 0, which means TSO offload is disabled.
 161
 162 .. code-block:: console
 163
 164     user@target:~$ ./<build_dir>/examples/dpdk-tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 165                 --tx-checksum --tso-segsz 800
 166
 167 **Decapsulation option.**
 168
 169 The decap option is used to enable or disable decapsulation operation for received VXLAN packet.
 170 The default value is 1.
 171
 172 .. code-block:: console
 173
 174     user@target:~$ ./<build_dir>/examples/dpdk-tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 175                 --nb-devices 4 --udp-port 4789 --decap 1
 176
 177 **Encapsulation option.**
 178
 179 The encap option is used to enable or disable encapsulation operation for transmitted packet.
 180 The default value is 1.
 181
 182 .. code-block:: console
 183
 184     user@target:~$ ./<build_dir>/examples/dpdk-tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 185                 --nb-devices 4 --udp-port 4789 --encap 1
 186
 187
 188 Running the Virtual Machine (QEMU)
 189 ----------------------------------
 190
 191 Refer to :ref:`vhost_app_run_vm`.
 192
 193 Running DPDK in the Virtual Machine
 194 -----------------------------------
 195
 196 Refer to :ref:`vhost_app_run_dpdk_inside_guest`.
 197
 198 Passing Traffic to the Virtual Machine Device
 199 ---------------------------------------------
 200
 201 For a virtio-net device to receive traffic, the traffic's Layer 2 header must include
 202 both the virtio-net device's MAC address.
 203 The DPDK sample code behaves in a similar manner to a learning switch in that
 204 it learns the MAC address of the virtio-net devices from the first transmitted packet.
 205 On learning the MAC address,
 206 the DPDK vhost sample code prints a message with the MAC address and tenant ID virtio-net device.
 207 For example:
 208
 209 .. code-block:: console
 210
 211     DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VNI 1000 registered
 212
 213 The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VNI 1000.
 214 Any packets received on the NIC with these values are placed on the devices receive queue.