From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 2C4AB11C5 for ; Fri, 3 Jul 2015 08:58:28 +0200 (CEST) Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga103.jf.intel.com with ESMTP; 02 Jul 2015 23:58:27 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.15,398,1432623600"; d="scan'208,217";a="722233941" Received: from shvmail01.sh.intel.com ([10.239.29.42]) by orsmga001.jf.intel.com with ESMTP; 02 Jul 2015 23:58:25 -0700 Received: from shecgisg004.sh.intel.com (shecgisg004.sh.intel.com [10.239.29.89]) by shvmail01.sh.intel.com with ESMTP id t636wNVC004293; Fri, 3 Jul 2015 14:58:23 +0800 Received: from shecgisg004.sh.intel.com (localhost [127.0.0.1]) by shecgisg004.sh.intel.com (8.13.6/8.13.6/SuSE Linux 0.8) with ESMTP id t636wJta016858; Fri, 3 Jul 2015 14:58:21 +0800 Received: (from jijiangl@localhost) by shecgisg004.sh.intel.com (8.13.6/8.13.6/Submit) id t636wJwe016854; Fri, 3 Jul 2015 14:58:19 +0800 From: Jijiang Liu To: dev@dpdk.org Date: Fri, 3 Jul 2015 14:58:17 +0800 Message-Id: <1435906697-16823-1-git-send-email-jijiang.liu@intel.com> X-Mailer: git-send-email 1.7.12.2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] =?utf-8?q?=5BPATCH_v2=5D_doc/sample=5Fapp=5Fug=3Aadd_a?= =?utf-8?q?_VXLAN_sample_guide?= X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 03 Jul 2015 06:58:29 -0000 Add a VXLAN sample guide in the sample_app_ug directory. It includes: - Add the overlay networking picture with svg format. - Add the TEP termination framework picture with svg format. - Add the tep_termination.rst file - Change the index.rst file for the above pictures index. Signed-off-by: Jijiang Liu Signed-off-by: Thomas Long v2 changes: optimize the two pictures add tep_termination index in index.rst file fix a typo and a command line --- .../sample_app_ug/img/overlay_networking.svg | 786 ++++++++++++++++++++ .../sample_app_ug/img/tep_termination_arch.svg | 548 ++++++++++++++ doc/guides/sample_app_ug/index.rst | 3 + doc/guides/sample_app_ug/tep_termination.rst | 321 ++++++++ 4 files changed, 1658 insertions(+), 0 deletions(-) create mode 100644 doc/guides/sample_app_ug/img/overlay_networking.svg create mode 100644 doc/guides/sample_app_ug/img/tep_termination_arch.svg create mode 100644 doc/guides/sample_app_ug/tep_termination.rst diff --git a/doc/guides/sample_app_ug/img/overlay_networking.svg b/doc/guides/sample_app_ug/img/overlay_networking.svg new file mode 100644 index 0000000..2ce440d --- /dev/null +++ b/doc/guides/sample_app_ug/img/overlay_networking.svg @@ -0,0 +1,786 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + + Rounded rectangle + Host + + + + + + + + + + + + Host + + Rounded rectangle.10 + VM + + + + + + + + + + + + VM + + Rounded rectangle.11 + VNID 100 + + + + + + + + + + + + VNID 100 + + Object + IP Network + + + + + + + + + + + + + + + + + IP Network + + Rounded rectangle.1 + VM + + + + + + + + + + + + VM + + Rounded rectangle.22 + VNID 101 + + + + + + + + + + + + VNID 101 + + Rounded rectangle.23 + Host + + + + + + + + + + + + Host + + Rounded rectangle.24 + VM + + + + + + + + + + + + VM + + Rounded rectangle.25 + VNID 100 + + + + + + + + + + + + VNID 100 + + Rounded rectangle.31 + VM + + + + + + + + + + + + VM + + Rounded rectangle.32 + VNID 101 + + + + + + + + + + + + VNID 101 + + Rounded rectangle.34 + Host + + + + + + + + + + + + Host + + Rounded rectangle.35 + VM + + + + + + + + + + + + VM + + Rounded rectangle.36 + VNID 100 + + + + + + + + + + + + VNID 100 + + Rounded rectangle.37 + VM + + + + + + + + + + + + VM + + Rounded rectangle.38 + VNID 101 + + + + + + + + + + + + VNID 101 + + Rounded rectangle.40 + Host + + + + + + + + + + + + Host + + Rounded rectangle.41 + VM + + + + + + + + + + + + VM + + Rounded rectangle.42 + VNID 100 + + + + + + + + + + + + VNID 100 + + Rounded rectangle.43 + VM + + + + + + + + + + + + VM + + Rounded rectangle.44 + VNID 102 + + + + + + + + + + + + VNID 102 + + Rounded rectangle.46 + VNID 102 + + + + + + + + + + + + VNID 102 + + Rounded rectangle.47 + VM + + + + + + + + + + + + VM + + Arced arrow + + + + + + + + + + + + + + + + Arced arrow.49 + + + + + + + + + + + + + + + + Arced arrow.50 + + + + + + + + + + + + + + + + Sheet.4 + + + + + + + + + + + Sheet.5 + + + + + + + + + + + Sheet.6 + + + + + + + + + + + Sheet.7 + + + + + + + + + + + Sheet.8 + + + + + + + + + + + Sheet.13 + + + + + + + + + + + Sheet.15 + + + + + + + + + + + Sheet.16 + + + + + + + + + + + Sheet.17 + + + + + + + + + + + Sheet.18 + + + + + + + + + + + Sheet.19 + + + + + + + + + + + Sheet.20 + + + + + + + + + + + Sheet.21 + + + + + + + + + + + Arced arrow.68 + + + + + + + + + + + + + Arced arrow.70 + + + + + + + + + + + + + + + + Sheet.84 + TEP + + + + + + + + TEP + + Sheet.86 + TEP + + + + + + + + TEP + + Sheet.87 + TEP + + + + + + + + TEP + + Sheet.88 + TEP + + + + + + + + TEP + + diff --git a/doc/guides/sample_app_ug/img/tep_termination_arch.svg b/doc/guides/sample_app_ug/img/tep_termination_arch.svg new file mode 100644 index 0000000..6f4754d --- /dev/null +++ b/doc/guides/sample_app_ug/img/tep_termination_arch.svg @@ -0,0 +1,548 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Rectangle.18 + + + + + + + + + + + + Rounded rectangle.10 + Userspace vhost Interface + + + + + + + + + + + + Userspace vhost Interface + + Rounded rectangle.12 + Encapsulation + + + + + + + + + + + + Encapsulation + + Rounded rectangle.13 + Decapsulation + + + + + + + + + + + + Decapsulation + + Rectangle.18.35 + + + + + + + + + + + + Data store + + + + + + + + + Rounded rectangle.16 + Inner IP/L4 checksum offload + + + + + + + + + + + + Inner IP/L4 checksum offload + + Rounded rectangle.17 + UDP port configuration + + + + + + + + + + + + UDP port configuration + + Rounded rectangle.18 + Inner IP/L4 csum verify + + + + + + + + + + + + Inner IP/L4 csum verify + + Rounded rectangle.19 + Tunnel Filter + + + + + + + + + + + + Tunnel Filter + + Rounded rectangle.20 + Packet Type + + + + + + + + + + + + Packet Type + + Sheet.27 + DPDK Application + + + + + + + + DPDK Application + + Sheet.26 + VXLAN Tunnel + + + + + + + + VXLAN Tunnel + + Sheet.28 + NIC + + + + + + + + NIC + + 45 degree single + + + + + + + + + + + + 45 degree single.30 + + + + + + + + + + + + Object + WAN/LAN + + + + + + + + + + + + + + + + + WAN/LAN + + Rounded rectangle.11 + TEP + + + + + + + + + + + + TEP + + Rectangle.18.36 + + + + + + + + + + + + Rounded rectangle.5 + VM-2 (VNID:200) + + + + + + + + + + + + VM-2 (VNID:200) + + Rounded rectangle + VM-1 (VNID: 100) + + + + + + + + + + + + VM-1 (VNID: 100) + + Process boundary.23 + + + + + + + + + Process boundary + + + + + + + + + Process boundary.24 + + + + + + + + + Process boundary.25 + + + + + + + + + Rectangle + vport-0 + + + + + + + + + + + + vport-0 + + Rectangle.2 + vport-1 + + + + + + + + + + + + vport-1 + + Rectangle.6 + vport-0 + + + + + + + + + + + + vport-0 + + Rectangle.7 + vport-1 + + + + + + + + + + + + vport-1 + + Sheet.37 + Guest + + + + + + + + Guest + + Rounded rectangle.38 + TSO offload + + + + + + + + + + + + TSO offload + + diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index e1a0c56..63434ed 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -71,6 +71,7 @@ Sample Applications User Guide test_pipeline dist_app vm_power_management + tep_termination **Figures** @@ -131,6 +132,8 @@ Sample Applications User Guide :numref:`figure_vm_power_mgr_highlevel` :ref:`figure_vm_power_mgr_highlevel` :numref:`figure_vm_power_mgr_vm_request_seq` :ref:`figure_vm_power_mgr_vm_request_seq` +:numref:`figure_overlay_networking` :ref:`figure_overlay_networking` +:numref:`figure_tep_termination_arch` :ref:`figure_tep_termination_arch` **Tables** diff --git a/doc/guides/sample_app_ug/tep_termination.rst b/doc/guides/sample_app_ug/tep_termination.rst new file mode 100644 index 0000000..86df8f8 --- /dev/null +++ b/doc/guides/sample_app_ug/tep_termination.rst @@ -0,0 +1,321 @@ + +.. 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 the guide in section 27.4 in the vhost sample. + +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 the guide in section 27.6.1 in the vhost sample 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 sise.** + +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 the guide in section 27.7 in the vhost sample. + +Running DPDK in the Virtual Machine +----------------------------------- + +Refer to the guide in section 27.8 in the vHost sample. + +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. -- 1.7.7.6