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 Compiling the Sample Code
  94 -------------------------
  95
  96 To enable vhost, turn on vhost library in the configure file
  97 ``config/common_linux``.
  98
  99     .. code-block:: console
 100
 101         CONFIG_RTE_LIBRTE_VHOST=y
 102
 103 Then following the to compile the sample application shown in
 104 :doc:`compiling`.
 105
 106 Running the Sample Code
 107 -----------------------
 108
 109 #.  Go to the examples directory:
 110
 111     .. code-block:: console
 112
 113         export RTE_SDK=/path/to/rte_sdk
 114         cd ${RTE_SDK}/examples/tep_termination
 115
 116 #.  Run the tep_termination sample code:
 117
 118     .. code-block:: console
 119
 120         user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 121                         -p 0x1 --dev-basename tep-termination --nb-devices 4
 122                         --udp-port 4789 --filter-type 1
 123
 124 .. note::
 125
 126     Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.
 127
 128 Parameters
 129 ~~~~~~~~~~
 130
 131 **The same parameters with the vhost sample.**
 132
 133 Refer to :ref:`vhost_app_parameters` for detailed explanation.
 134
 135 **Number of Devices.**
 136
 137 The nb-devices option specifies the number of virtIO device.
 138 The default value is 2.
 139
 140 .. code-block:: console
 141
 142     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 143                     --nb-devices 2
 144
 145 **Tunneling UDP port.**
 146
 147 The udp-port option is used to specify the destination UDP number for UDP tunneling packet.
 148 The default value is 4789.
 149
 150 .. code-block:: console
 151
 152     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 153                     --nb-devices 2 --udp-port 4789
 154
 155 **Filter Type.**
 156
 157 The filter-type option is used to specify which filter type is used to
 158 filter UDP tunneling packet to a specified queue.
 159 The default value is 1, which means the filter type of inner MAC and tenant ID is used.
 160
 161 .. code-block:: console
 162
 163     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 164                 --nb-devices 2 --udp-port 4789 --filter-type 1
 165
 166 **TX Checksum.**
 167
 168 The tx-checksum option is used to enable or disable the inner header checksum offload.
 169 The default value is 0, which means the checksum offload is disabled.
 170
 171 .. code-block:: console
 172
 173     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 174                 --nb-devices 2 --tx-checksum
 175
 176 **TCP segment size.**
 177
 178 The tso-segsz option specifies the TCP segment size for TSO offload for tunneling packet.
 179 The default value is 0, which means TSO offload is disabled.
 180
 181 .. code-block:: console
 182
 183     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 184                 --tx-checksum --tso-segsz 800
 185
 186 **Decapsulation option.**
 187
 188 The decap option is used to enable or disable decapsulation operation for received VXLAN packet.
 189 The default value is 1.
 190
 191 .. code-block:: console
 192
 193     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 194                 --nb-devices 4 --udp-port 4789 --decap 1
 195
 196 **Encapsulation option.**
 197
 198 The encap option is used to enable or disable encapsulation operation for transmitted packet.
 199 The default value is 1.
 200
 201 .. code-block:: console
 202
 203     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 204                 --nb-devices 4 --udp-port 4789 --encap 1
 205
 206
 207 Running the Virtual Machine (QEMU)
 208 ----------------------------------
 209
 210 Refer to :ref:`vhost_app_run_vm`.
 211
 212 Running DPDK in the Virtual Machine
 213 -----------------------------------
 214
 215 Refer to :ref:`vhost_app_run_dpdk_inside_guest`.
 216
 217 Passing Traffic to the Virtual Machine Device
 218 ---------------------------------------------
 219
 220 For a virtio-net device to receive traffic, the traffic's Layer 2 header must include
 221 both the virtio-net device's MAC address.
 222 The DPDK sample code behaves in a similar manner to a learning switch in that
 223 it learns the MAC address of the virtio-net devices from the first transmitted packet.
 224 On learning the MAC address,
 225 the DPDK vhost sample code prints a message with the MAC address and tenant ID virtio-net device.
 226 For example:
 227
 228 .. code-block:: console
 229
 230     DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VNI 1000 registered
 231
 232 The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VNI 1000.
 233 Any packets received on the NIC with these values are placed on the devices receive queue.