--- /dev/null
+
+.. BSD LICENSE
+ Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Intel Corporation nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+TEP termination Sample Application
+==================================
+
+The TEP (Tunnel End point) termination sample application simulates a VXLAN
+Tunnel Endpoint (VTEP) termination in DPDK, which is used to demonstrate
+the offload and filtering capabilities of Intel® XL710 10/40 Gigabit Ethernet
+Controller for VXLAN packet.
+This sample uses the basic virtio devices management mechanism from vhost example,
+and also uses the us-vHost interface and tunnel filtering mechanism to direct
+a specified traffic to a specific VM.
+In addition, this sample is also designed to show how tunneling protocols can be handled.
+
+Background
+----------
+
+With virtualization, overlay networks allow a network structure to be built
+or imposed across physical nodes which is abstracted away from the actual
+underlining physical network connections.
+This allows network isolation, QOS, etc to be provided on a per client basis.
+
+.. _figure_overlay_networking:
+
+.. figure:: img/overlay_networking.*
+
+ Overlay Networking.
+
+In a typical setup, the network overlay tunnel is terminated at the Virtual/Tunnel End Point (VEP/TEP).
+The TEP is normally located at the physical host level ideally in the software switch.
+Due to processing constraints and the inevitable bottleneck that the switch
+becomes the ability to offload overlay support features becomes an important requirement.
+Intel® XL710 10/40 G Ethernet network card provides hardware filtering
+and offload capabilities to support overlay networks implementations such as MAC in UDP and MAC in GRE.
+
+Sample Code Overview
+--------------------
+
+The DPDK TEP termination sample code demonstrates the offload and filtering
+capabilities of Intel® XL710 10/40 Gigabit Ethernet Controller for VXLAN packet.
+
+The sample code is based on vhost library.
+The vhost library is developed for user space Ethernet switch to easily integrate with vhost functionality.
+
+The sample will support the followings:
+
+* Tunneling packet recognition.
+
+* The port of UDP tunneling is configurable
+
+* Directing incoming traffic to the correct queue based on the tunnel filter type.
+ The supported filter type are listed below.
+
+ * Inner MAC and VLAN and tenant ID
+
+ * Inner MAC and tenant ID, and Outer MAC
+
+ * Inner MAC and tenant ID
+
+ The tenant ID will be assigned from a static internal table based on the us-vhost device ID.
+ Each device will receive a unique device ID.
+ The inner MAC will be learned by the first packet transmitted from a device.
+
+* Decapsulation of RX VXLAN traffic. This is a software only operation.
+
+* Encapsulation of TX VXLAN traffic. This is a software only operation.
+
+* Inner IP and inner L4 checksum offload.
+
+* TSO offload support for tunneling packet.
+
+The following figure shows the framework of the TEP termination sample application based on vhost-cuse.
+
+.. _figure_tep_termination_arch:
+
+.. figure:: img/tep_termination_arch.*
+
+ TEP termination Framework Overview
+
+Supported Distributions
+-----------------------
+
+The example in this section have been validated with the following distributions:
+
+* Fedora* 18
+
+* Fedora* 19
+
+* Fedora* 20
+
+Prerequisites
+-------------
+
+Refer to :ref:`vhost_app_prerequisites`.
+
+Compiling the Sample Code
+-------------------------
+#. Compile vhost lib:
+
+ To enable vhost, turn on vhost library in the configure file config/common_linuxapp.
+
+ .. code-block:: console
+
+ CONFIG_RTE_LIBRTE_VHOST=n
+
+ vhost user is turned on by default in the configure file config/common_linuxapp.
+ To enable vhost cuse, disable vhost user.
+
+ .. code-block:: console
+
+ CONFIG_RTE_LIBRTE_VHOST_USER=y
+
+ After vhost is enabled and the implementation is selected, build the vhost library.
+
+#. Go to the examples directory:
+
+ .. code-block:: console
+
+ export RTE_SDK=/path/to/rte_sdk
+ cd ${RTE_SDK}/examples/tep_termination
+
+#. Set the target (a default target is used if not specified). For example:
+
+ .. code-block:: console
+
+ export RTE_TARGET=x86_64-native-linuxapp-gcc
+
+ See the DPDK Getting Started Guide for possible RTE_TARGET values.
+
+#. Build the application:
+
+ .. code-block:: console
+
+ cd ${RTE_SDK}
+ make config ${RTE_TARGET}
+ make install ${RTE_TARGET}
+ cd ${RTE_SDK}/examples/tep_termination
+ make
+
+#. Go to the eventfd_link directory(vhost cuse required):
+
+ .. code-block:: console
+
+ cd ${RTE_SDK}/lib/librte_vhost/eventfd_link
+
+#. Build the eventfd_link kernel module(vhost cuse required):
+
+ .. code-block:: console
+
+ make
+
+Running the Sample Code
+-----------------------
+
+#. Install the cuse kernel module(vhost cuse required):
+
+ .. code-block:: console
+
+ modprobe cuse
+
+#. Go to the eventfd_link directory(vhost cuse required):
+
+ .. code-block:: console
+
+ export RTE_SDK=/path/to/rte_sdk
+ cd ${RTE_SDK}/lib/librte_vhost/eventfd_link
+
+#. Install the eventfd_link module(vhost cuse required):
+
+ .. code-block:: console
+
+ insmod ./eventfd_link.ko
+
+#. Go to the examples directory:
+
+ .. code-block:: console
+
+ export RTE_SDK=/path/to/rte_sdk
+ cd ${RTE_SDK}/examples/tep_termination
+
+#. Run the tep_termination sample code:
+
+ .. code-block:: console
+
+ user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
+ -p 0x1 --dev-basename tep-termination --nb-devices 4
+ --udp-port 4789 --filter-type 1
+
+.. note::
+
+ Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.
+
+Parameters
+~~~~~~~~~~
+
+**The same parameters with the vhost sample.**
+
+Refer to :ref:`vhost_app_parameters` for the meanings of 'Basename',
+'Stats', 'RX Retry', 'RX Retry Number' and 'RX Retry Delay Time'.
+
+**Number of Devices.**
+
+The nb-devices option specifies the number of virtIO device.
+The default value is 2.
+
+.. code-block:: console
+
+ user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
+ --nb-devices 2
+
+**Tunneling UDP port.**
+
+The udp-port option is used to specify the destination UDP number for UDP tunneling packet.
+The default value is 4789.
+
+.. code-block:: console
+
+ user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
+ --nb-devices 2 --udp-port 4789
+
+**Filter Type.**
+
+The filter-type option is used to specify which filter type is used to
+filter UDP tunneling packet to a specified queue.
+The default value is 1, which means the filter type of inner MAC and tenant ID is used.
+
+.. code-block:: console
+
+ user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
+ --nb-devices 2 --udp-port 4789 --filter-type 1
+
+**TX Checksum.**
+
+The tx-checksum option is used to enable or disable the inner header checksum offload.
+The default value is 0, which means the checksum offload is disabled.
+
+.. code-block:: console
+
+ user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
+ --nb-devices 2 --tx-checksum
+
+**TCP segment size.**
+
+The tso-segsz option specifies the TCP segment size for TSO offload for tunneling packet.
+The default value is 0, which means TSO offload is disabled.
+
+.. code-block:: console
+
+ user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
+ --tx-checksum --tso-segsz 800
+
+**Decapsulation option.**
+
+The decap option is used to enable or disable decapsulation operation for received VXLAN packet.
+The default value is 1.
+
+.. code-block:: console
+
+ user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
+ --nb-devices 4 --udp-port 4789 --decap 1
+
+**Encapsulation option.**
+
+The encap option is used to enable or disable encapsulation operation for transmitted packet.
+The default value is 1.
+
+.. code-block:: console
+
+ user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
+ --nb-devices 4 --udp-port 4789 --encap 1
+
+
+Running the Virtual Machine (QEMU)
+----------------------------------
+
+Refer to :ref:`vhost_app_running`.
+
+Running DPDK in the Virtual Machine
+-----------------------------------
+
+Refer to :ref:`vhost_app_running_dpdk`.
+
+Passing Traffic to the Virtual Machine Device
+---------------------------------------------
+
+For a virtio-net device to receive traffic, the traffic's Layer 2 header must include
+both the virtio-net device's MAC address.
+The DPDK sample code behaves in a similar manner to a learning switch in that
+it learns the MAC address of the virtio-net devices from the first transmitted packet.
+On learning the MAC address,
+the DPDK vhost sample code prints a message with the MAC address and tenant ID virtio-net device.
+For example:
+
+.. code-block:: console
+
+ DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VNI 1000 registered
+
+The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VNI 1000.
+Any packets received on the NIC with these values are placed on the devices receive queue.
Code Review / deb_dpdk.git / blobdiff