From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jijiang Liu Subject: =?utf-8?q?=5BPATCH=5D_doc/sample=5Fapp=5Fug=3Aadd_a_VX?= =?utf-8?q?LAN_sample_guide?= Date: Thu, 25 Jun 2015 11:08:49 +0800 Message-ID: <1435201729-1266-1-git-send-email-jijiang.liu@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable To: dev@dpdk.org Return-path: Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id 84877C4FA for ; Thu, 25 Jun 2015 05:08:58 +0200 (CEST) List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Add a VXLAN sample guide in the sample_app_ug directory. =20 It includes: =20 - Add the overlay networking picture with svg format. =20 - Add the TEP termination framework picture with svg format. =20 - 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 --- .../sample_app_ug/img/overlay_networking.svg | 820 ++++++++++++++= ++++++ .../sample_app_ug/img/tep_termination_arch.svg | 551 +++++++++++++ doc/guides/sample_app_ug/index.rst | 2 + doc/guides/sample_app_ug/tep_termination.rst | 319 ++++++++ 4 files changed, 1692 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/gu= ides/sample_app_ug/img/overlay_networking.svg new file mode 100644 index 0000000..e16b5ac --- /dev/null +++ b/doc/guides/sample_app_ug/img/overlay_networking.svg @@ -0,0 +1,820 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + Box + T E P + + + + + + + + + + + + TEP= + + Box.65 + T E P + + + + + + + + + + + + TEP= + + Arced arrow.68 + + + + + + + + + + + + + Box.67 + T E P + + + + + + + + + + + + TEP= + + Arced arrow.70 + + + + + + + + + + + + + + + + Box.69 + T E P + + + + + + + + + + + + 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..8fd6704 --- /dev/null +++ b/doc/guides/sample_app_ug/img/tep_termination_arch.svg @@ -0,0 +1,551 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Rectangle.18 + + + + + + + + + + + + Rounded rectangle.10 + Userspace Vhost Interface + + + + + + + + + + + + Userspace VhostInterface = + + 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 + + Rounded rectangle.21 + TSO offload + + + + + + + + + + + + TSO offload + + 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 VNI:200 + + + + + + + + + + + + VM-2VNI:200 = + + Rounded rectangle + VM-1 VNI: 100 + + + + + + + + + + + + VM-1VNI: 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 + + diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_u= g/index.rst index e1a0c56..8dc7ce2 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -131,6 +131,8 @@ Sample Applications User Guide :numref:`figure_vm_power_mgr_highlevel` :ref:`figure_vm_power_mgr_highle= vel` =20 :numref:`figure_vm_power_mgr_vm_request_seq` :ref:`figure_vm_power_mgr_v= m_request_seq` +:numref:`figure_overlay_networking` :ref:`figure_overlay_networking` +:numref:`figure_tep_termination_arch` :ref:`figure_tep_termination_arch` =20 **Tables** =20 diff --git a/doc/guides/sample_app_ug/tep_termination.rst b/doc/guides/sa= mple_app_ug/tep_termination.rst new file mode 100644 index 0000000..bd0cd5d --- /dev/null +++ b/doc/guides/sample_app_ug/tep_termination.rst @@ -0,0 +1,319 @@ + +.. 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 FO= R + 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 AN= Y + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +TEP termination Sample Application +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The TEP(Tunnel End point) termination sample application simulates a VXL= AN Tunnel Endpoint (VTEP) termination in DPDK, which is used to +demonstrate the offload and filtering capabilities of Intel=C2=AE XL710 = 10/40 Gigabit Ethernet Controller for VXLAN packet. +This sample uses the basic virtio devices management mechanism from vhos= t example, and also uses the us-vHost interface and +tunnel filtering mechanism to direct a specified traffic to a specific V= M. +In addition, this sample is also designed to show how tunneling protocol= s can be handled. + +Background +---------- +With virtualization, overlay networks allow a network structure to be bu= ilt or imposed across physical nodes which=20 +is abstracted away from the actual underlining physical network connecti= ons. This allows network isolation, QOS, etc +to be provided on a per client basis.=20 + +.. _figure_overlay_networking: + =20 +.. figure:: img/overlay_networking.* + =20 + Overlay Networking. + +In a typical setup, the network overlay tunnel is terminated at the Virt= ual/Tunnel End Point (VEP/TEP). +The TEP is normally located at the physical host level ideally in the so= ftware 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=C2=AE XL710 10/40 G Ethernet network card provides hardware filter= ing and offload capabilities to support overlay networks +implementations such as MAC in UDP and MAC in GRE.=20 + +Sample Code Overview +-------------------- + +The DPDK TEP termination sample code demonstrates the offload and filter= ing capabilities of Intel=C2=AE XL710 10/40 Gigabit Ethernet=20 +Controller for VXLAN packet. +=20 +The sample code is based on vhost library. The vhost library is develope= d 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 l= earned 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 a= pplication based on vhost-cuse. + +.. _figure_tep_termination_arch: + =20 +.. figure:: img/tep_termination_arch.* + =20 + TEP termination Framework Overview + +Supported Distributions +----------------------- + +The example in this section have been validated with the following distr= ibutions: + +* 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=3Dn + + vhost user is turned on by default in the configure file config/comm= on_linuxapp. + To enable vhost cuse, disable vhost user. + + .. code-block:: console + + CONFIG_RTE_LIBRTE_VHOST_USER=3Dy + + After vhost is enabled and the implementation is selected, build th= e vhost library. + +#. Go to the examples directory: + + .. code-block:: console + + export RTE_SDK=3D/path/to/rte_sdk + cd ${RTE_SDK}/examples/tep_termination + +#. Set the target (a default target is used if not specified). For exam= ple: + + .. code-block:: console + + export RTE_TARGET=3Dx86_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=3D/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=3D/path/to/rte_sdk + cd ${RTE_SDK}/examples/tep_termination + +#. Run the tep_termination sample code: + + vhost cuse: + + .. code-block:: console + + user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir = /mnt/huge -- -p 0x1 --dev-basename tep-termination=20 + + vhost user: a socket file named usvhost will be created under curren= t directory. Use its path as the socket path in guest's qemu commandline. + + .. code-block:: console + + user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir = /mnt/huge -- -p 0x1 --dev-basename tep-termination=20 + +.. note:: + + Please note the huge-dir parameter instructs the DPDK to allocate it= s 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 meaning= s of 'Basename',=20 +'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=20 + +**Tunneling UDP port.** + +The udp-port option is used to specify the destination UDP number for UD= P tunneling packet. +The default value is 4789. + =20 +.. 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 f= ilter UDP tunneling packet to a specified queue. +The default value is 1, which means the filter type of inner MAC and ten= ant 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 che= cksum 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.=20 + +.. 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 fo= r received VXLAN packet. +The default value is 1. +=20 +.. code-block:: console + =20 + 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 fo= r transmited packet. +The default value is 1. +=20 +.. code-block:: console + =20 + user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt= /huge -- --nb-devices 4 --udp-port 4789 --encap 1 +=20 + +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=20 +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 trans= mitted packet. +On learning the MAC address, +the DPDK vhost sample code prints a message with the MAC address and ten= ant ID virtio-net device. +For example: +=20 +.. code-block:: console + =20 + DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VNI 1000 registered +=20 +The above message indicates that device 0 has been registered with MAC a= ddress cc:bb:bb:bb:bb:bb and VNI 1000. +Any packets received on the NIC with these values is placed on the devic= es receive queue. --=20 1.7.7.6