doc/guides/sample_app_ug/tep_termination.rst

   1
   2 ..  BSD LICENSE
   3     Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
   4     All rights reserved.
   5
   6     Redistribution and use in source and binary forms, with or without
   7     modification, are permitted provided that the following conditions
   8     are met:
   9
  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
  15     distribution.
  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.
  19
  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.
  31
  32
  33 TEP termination Sample Application
  34 ==================================
  35
  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.
  44
  45 Background
  46 ----------
  47
  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.
  52
  53 .. _figure_overlay_networking:
  54
  55 .. figure:: img/overlay_networking.*
  56
  57    Overlay Networking.
  58
  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.
  65
  66 Sample Code Overview
  67 --------------------
  68
  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.
  71
  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.
  74
  75 The sample will support the followings:
  76
  77 *   Tunneling packet recognition.
  78
  79 *   The port of UDP tunneling is configurable
  80
  81 *   Directing incoming traffic to the correct queue based on the tunnel filter type.
  82     The supported filter type are listed below.
  83
  84     * Inner MAC and VLAN and tenant ID
  85
  86     * Inner MAC and tenant ID, and Outer MAC
  87
  88     * Inner MAC and tenant ID
  89
  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.
  93
  94 *   Decapsulation of RX VXLAN traffic. This is a software only operation.
  95
  96 *   Encapsulation of TX VXLAN traffic. This is a software only operation.
  97
  98 *   Inner IP and inner L4 checksum offload.
  99
 100 *   TSO offload support for tunneling packet.
 101
 102 The following figure shows the framework of the TEP termination sample
 103 application based on DPDK vhost lib.
 104
 105 .. _figure_tep_termination_arch:
 106
 107 .. figure:: img/tep_termination_arch.*
 108
 109    TEP termination Framework Overview
 110
 111 Supported Distributions
 112 -----------------------
 113
 114 The example in this section have been validated with the following distributions:
 115
 116 *   Fedora* 18
 117
 118 *   Fedora* 19
 119
 120 *   Fedora* 20
 121
 122 Compiling the Sample Code
 123 -------------------------
 124 #.  Compile vhost lib:
 125
 126     To enable vhost, turn on vhost library in the configure file config/common_linuxapp.
 127
 128     .. code-block:: console
 129
 130         CONFIG_RTE_LIBRTE_VHOST=y
 131
 132
 133 #.  Go to the examples directory:
 134
 135     .. code-block:: console
 136
 137         export RTE_SDK=/path/to/rte_sdk
 138         cd ${RTE_SDK}/examples/tep_termination
 139
 140 #.  Set the target (a default target is used if not specified). For example:
 141
 142     .. code-block:: console
 143
 144         export RTE_TARGET=x86_64-native-linuxapp-gcc
 145
 146     See the DPDK Getting Started Guide for possible RTE_TARGET values.
 147
 148 #.  Build the application:
 149
 150     .. code-block:: console
 151
 152         cd ${RTE_SDK}
 153         make config ${RTE_TARGET}
 154         make install ${RTE_TARGET}
 155         cd ${RTE_SDK}/examples/tep_termination
 156         make
 157
 158 Running the Sample Code
 159 -----------------------
 160
 161 #.  Go to the examples directory:
 162
 163     .. code-block:: console
 164
 165         export RTE_SDK=/path/to/rte_sdk
 166         cd ${RTE_SDK}/examples/tep_termination
 167
 168 #.  Run the tep_termination sample code:
 169
 170     .. code-block:: console
 171
 172         user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 173                         -p 0x1 --dev-basename tep-termination --nb-devices 4
 174                         --udp-port 4789 --filter-type 1
 175
 176 .. note::
 177
 178     Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.
 179
 180 Parameters
 181 ~~~~~~~~~~
 182
 183 **The same parameters with the vhost sample.**
 184
 185 Refer to :ref:`vhost_app_parameters` for detailed explanation.
 186
 187 **Number of Devices.**
 188
 189 The nb-devices option specifies the number of virtIO device.
 190 The default value is 2.
 191
 192 .. code-block:: console
 193
 194     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 195                     --nb-devices 2
 196
 197 **Tunneling UDP port.**
 198
 199 The udp-port option is used to specify the destination UDP number for UDP tunneling packet.
 200 The default value is 4789.
 201
 202 .. code-block:: console
 203
 204     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 205                     --nb-devices 2 --udp-port 4789
 206
 207 **Filter Type.**
 208
 209 The filter-type option is used to specify which filter type is used to
 210 filter UDP tunneling packet to a specified queue.
 211 The default value is 1, which means the filter type of inner MAC and tenant ID is used.
 212
 213 .. code-block:: console
 214
 215     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 216                 --nb-devices 2 --udp-port 4789 --filter-type 1
 217
 218 **TX Checksum.**
 219
 220 The tx-checksum option is used to enable or disable the inner header checksum offload.
 221 The default value is 0, which means the checksum offload is disabled.
 222
 223 .. code-block:: console
 224
 225     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 226                 --nb-devices 2 --tx-checksum
 227
 228 **TCP segment size.**
 229
 230 The tso-segsz option specifies the TCP segment size for TSO offload for tunneling packet.
 231 The default value is 0, which means TSO offload is disabled.
 232
 233 .. code-block:: console
 234
 235     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 236                 --tx-checksum --tso-segsz 800
 237
 238 **Decapsulation option.**
 239
 240 The decap option is used to enable or disable decapsulation operation for received VXLAN packet.
 241 The default value is 1.
 242
 243 .. code-block:: console
 244
 245     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 246                 --nb-devices 4 --udp-port 4789 --decap 1
 247
 248 **Encapsulation option.**
 249
 250 The encap option is used to enable or disable encapsulation operation for transmitted packet.
 251 The default value is 1.
 252
 253 .. code-block:: console
 254
 255     user@target:~$ ./build/app/tep_termination -l 0-3 -n 4 --huge-dir /mnt/huge --
 256                 --nb-devices 4 --udp-port 4789 --encap 1
 257
 258
 259 Running the Virtual Machine (QEMU)
 260 ----------------------------------
 261
 262 Refer to :ref:`vhost_app_run_vm`.
 263
 264 Running DPDK in the Virtual Machine
 265 -----------------------------------
 266
 267 Refer to :ref:`vhost_app_run_dpdk_inside_guest`.
 268
 269 Passing Traffic to the Virtual Machine Device
 270 ---------------------------------------------
 271
 272 For a virtio-net device to receive traffic, the traffic's Layer 2 header must include
 273 both the virtio-net device's MAC address.
 274 The DPDK sample code behaves in a similar manner to a learning switch in that
 275 it learns the MAC address of the virtio-net devices from the first transmitted packet.
 276 On learning the MAC address,
 277 the DPDK vhost sample code prints a message with the MAC address and tenant ID virtio-net device.
 278 For example:
 279
 280 .. code-block:: console
 281
 282     DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VNI 1000 registered
 283
 284 The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VNI 1000.
 285 Any packets received on the NIC with these values are placed on the devices receive queue.