summaryrefslogtreecommitdiffstats
path: root/doc/guides/linux_gsg
diff options
context:
space:
mode:
Diffstat (limited to 'doc/guides/linux_gsg')
-rw-r--r--doc/guides/linux_gsg/build_dpdk.rst282
-rw-r--r--doc/guides/linux_gsg/build_sample_apps.rst255
-rw-r--r--doc/guides/linux_gsg/enable_func.rst218
-rw-r--r--doc/guides/linux_gsg/img/intel_perf_test_setup.svg507
-rw-r--r--doc/guides/linux_gsg/index.rst46
-rw-r--r--doc/guides/linux_gsg/intro.rst63
-rw-r--r--doc/guides/linux_gsg/nic_perf_intel_platform.rst260
-rw-r--r--doc/guides/linux_gsg/quick_start.rst335
-rw-r--r--doc/guides/linux_gsg/sys_reqs.rst269
9 files changed, 2235 insertions, 0 deletions
diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
new file mode 100644
index 00000000..198c0b6f
--- /dev/null
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -0,0 +1,282 @@
+.. 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.
+
+.. _linux_gsg_compiling_dpdk:
+
+Compiling the DPDK Target from Source
+=====================================
+
+.. note::
+
+ Parts of this process can also be done using the setup script described in
+ the :ref:`linux_setup_script` section of this document.
+
+Install the DPDK and Browse Sources
+-----------------------------------
+
+First, uncompress the archive and move to the uncompressed DPDK source directory:
+
+.. code-block:: console
+
+ unzip DPDK-<version>.zip
+ cd DPDK-<version>
+
+ ls
+ app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Makefile
+ mk/ scripts/ tools/
+
+The DPDK is composed of several directories:
+
+* lib: Source code of DPDK libraries
+
+* drivers: Source code of DPDK poll-mode drivers
+
+* app: Source code of DPDK applications (automatic tests)
+
+* examples: Source code of DPDK application examples
+
+* config, tools, scripts, mk: Framework-related makefiles, scripts and configuration
+
+Installation of DPDK Target Environments
+----------------------------------------
+
+The format of a DPDK target is::
+
+ ARCH-MACHINE-EXECENV-TOOLCHAIN
+
+where:
+
+* ``ARCH`` can be: ``i686``, ``x86_64``, ``ppc_64``
+
+* ``MACHINE`` can be: ``native``, ``ivshmem``, ``power8``
+
+* ``EXECENV`` can be: ``linuxapp``, ``bsdapp``
+
+* ``TOOLCHAIN`` can be: ``gcc``, ``icc``
+
+The targets to be installed depend on the 32-bit and/or 64-bit packages and compilers installed on the host.
+Available targets can be found in the DPDK/config directory.
+The defconfig\_ prefix should not be used.
+
+.. note::
+
+ Configuration files are provided with the ``RTE_MACHINE`` optimization level set.
+ Within the configuration files, the ``RTE_MACHINE`` configuration value is set to native,
+ which means that the compiled software is tuned for the platform on which it is built.
+ For more information on this setting, and its possible values, see the *DPDK Programmers Guide*.
+
+When using the Intel® C++ Compiler (icc), one of the following commands should be invoked for 64-bit or 32-bit use respectively.
+Notice that the shell scripts update the ``$PATH`` variable and therefore should not be performed in the same session.
+Also, verify the compiler's installation directory since the path may be different:
+
+.. code-block:: console
+
+ source /opt/intel/bin/iccvars.sh intel64
+ source /opt/intel/bin/iccvars.sh ia32
+
+To install and make targets, use the ``make install T=<target>`` command in the top-level DPDK directory.
+
+For example, to compile a 64-bit target using icc, run:
+
+.. code-block:: console
+
+ make install T=x86_64-native-linuxapp-icc
+
+To compile a 32-bit build using gcc, the make command should be:
+
+.. code-block:: console
+
+ make install T=i686-native-linuxapp-gcc
+
+To prepare a target without building it, for example, if the configuration changes need to be made before compilation,
+use the ``make config T=<target>`` command:
+
+.. code-block:: console
+
+ make config T=x86_64-native-linuxapp-gcc
+
+.. warning::
+
+ Any kernel modules to be used, e.g. ``igb_uio``, ``kni``, must be compiled with the
+ same kernel as the one running on the target.
+ If the DPDK is not being built on the target machine,
+ the ``RTE_KERNELDIR`` environment variable should be used to point the compilation at a copy of the kernel version to be used on the target machine.
+
+Once the target environment is created, the user may move to the target environment directory and continue to make code changes and re-compile.
+The user may also make modifications to the compile-time DPDK configuration by editing the .config file in the build directory.
+(This is a build-local copy of the defconfig file from the top- level config directory).
+
+.. code-block:: console
+
+ cd x86_64-native-linuxapp-gcc
+ vi .config
+ make
+
+In addition, the make clean command can be used to remove any existing compiled files for a subsequent full, clean rebuild of the code.
+
+Browsing the Installed DPDK Environment Target
+----------------------------------------------
+
+Once a target is created it contains all libraries, including poll-mode drivers, and header files for the DPDK environment that are required to build customer applications.
+In addition, the test and testpmd applications are built under the build/app directory, which may be used for testing.
+A kmod directory is also present that contains kernel modules which may be loaded if needed.
+
+.. code-block:: console
+
+ ls x86_64-native-linuxapp-gcc
+
+ app build hostapp include kmod lib Makefile
+
+Loading Modules to Enable Userspace IO for DPDK
+-----------------------------------------------
+
+To run any DPDK application, a suitable uio module can be loaded into the running kernel.
+In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
+can provide the uio capability. This module can be loaded using the command
+
+.. code-block:: console
+
+ sudo modprobe uio_pci_generic
+
+As an alternative to the ``uio_pci_generic``, the DPDK also includes the igb_uio
+module which can be found in the kmod subdirectory referred to above. It can
+be loaded as shown below:
+
+.. code-block:: console
+
+ sudo modprobe uio
+ sudo insmod kmod/igb_uio.ko
+
+.. note::
+
+ For some devices which lack support for legacy interrupts, e.g. virtual function
+ (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
+
+Since DPDK release 1.7 onward provides VFIO support, use of UIO is optional
+for platforms that support using VFIO.
+
+Loading VFIO Module
+-------------------
+
+To run an DPDK application and make use of VFIO, the ``vfio-pci`` module must be loaded:
+
+.. code-block:: console
+
+ sudo modprobe vfio-pci
+
+Note that in order to use VFIO, your kernel must support it.
+VFIO kernel modules have been included in the Linux kernel since version 3.6.0 and are usually present by default,
+however please consult your distributions documentation to make sure that is the case.
+
+Also, to use VFIO, both kernel and BIOS must support and be configured to use IO virtualization (such as Intel® VT-d).
+
+For proper operation of VFIO when running DPDK applications as a non-privileged user, correct permissions should also be set up.
+This can be done by using the DPDK setup script (called setup.sh and located in the tools directory).
+
+.. _linux_gsg_binding_kernel:
+
+Binding and Unbinding Network Ports to/from the Kernel Modules
+--------------------------------------------------------------
+
+As of release 1.4, DPDK applications no longer automatically unbind all supported network ports from the kernel driver in use.
+Instead, all ports that are to be used by an DPDK application must be bound to the
+``uio_pci_generic``, ``igb_uio`` or ``vfio-pci`` module before the application is run.
+Any network ports under Linux* control will be ignored by the DPDK poll-mode drivers and cannot be used by the application.
+
+.. warning::
+
+ The DPDK will, by default, no longer automatically unbind network ports from the kernel driver at startup.
+ Any ports to be used by an DPDK application must be unbound from Linux* control and
+ bound to the ``uio_pci_generic``, ``igb_uio`` or ``vfio-pci`` module before the application is run.
+
+To bind ports to the ``uio_pci_generic``, ``igb_uio`` or ``vfio-pci`` module for DPDK use,
+and then subsequently return ports to Linux* control,
+a utility script called dpdk_nic _bind.py is provided in the tools subdirectory.
+This utility can be used to provide a view of the current state of the network ports on the system,
+and to bind and unbind those ports from the different kernel modules, including the uio and vfio modules.
+The following are some examples of how the script can be used.
+A full description of the script and its parameters can be obtained by calling the script with the ``--help`` or ``--usage`` options.
+Note that the uio or vfio kernel modules to be used, should be loaded into the kernel before
+running the ``dpdk_nic_bind.py`` script.
+
+.. warning::
+
+ Due to the way VFIO works, there are certain limitations to which devices can be used with VFIO.
+ Mainly it comes down to how IOMMU groups work.
+ Any Virtual Function device can be used with VFIO on its own, but physical devices will require either all ports bound to VFIO,
+ or some of them bound to VFIO while others not being bound to anything at all.
+
+ If your device is behind a PCI-to-PCI bridge, the bridge will then be part of the IOMMU group in which your device is in.
+ Therefore, the bridge driver should also be unbound from the bridge PCI device for VFIO to work with devices behind the bridge.
+
+.. warning::
+
+ While any user can run the dpdk_nic_bind.py script to view the status of the network ports,
+ binding or unbinding network ports requires root privileges.
+
+To see the status of all network ports on the system:
+
+.. code-block:: console
+
+ ./tools/dpdk_nic_bind.py --status
+
+ Network devices using DPDK-compatible driver
+ ============================================
+ 0000:82:00.0 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
+ 0000:82:00.1 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
+
+ Network devices using kernel driver
+ ===================================
+ 0000:04:00.0 'I350 1-GbE NIC' if=em0 drv=igb unused=uio_pci_generic *Active*
+ 0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=uio_pci_generic
+ 0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=uio_pci_generic
+ 0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=uio_pci_generic
+
+ Other network devices
+ =====================
+ <none>
+
+To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver:
+
+.. code-block:: console
+
+ ./tools/dpdk_nic_bind.py --bind=uio_pci_generic 04:00.1
+
+or, alternatively,
+
+.. code-block:: console
+
+ ./tools/dpdk_nic_bind.py --bind=uio_pci_generic eth1
+
+To restore device ``82:00.0`` to its original kernel binding:
+
+.. code-block:: console
+
+ ./tools/dpdk_nic_bind.py --bind=ixgbe 82:00.0
diff --git a/doc/guides/linux_gsg/build_sample_apps.rst b/doc/guides/linux_gsg/build_sample_apps.rst
new file mode 100644
index 00000000..e53bd517
--- /dev/null
+++ b/doc/guides/linux_gsg/build_sample_apps.rst
@@ -0,0 +1,255 @@
+.. BSD LICENSE
+ Copyright(c) 2010-2014 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.
+
+Compiling and Running Sample Applications
+=========================================
+
+The chapter describes how to compile and run applications in an DPDK environment.
+It also provides a pointer to where sample applications are stored.
+
+.. note::
+
+ Parts of this process can also be done using the setup script described the
+ :ref:`linux_setup_script` section of this document.
+
+Compiling a Sample Application
+------------------------------
+
+Once an DPDK target environment directory has been created (such as ``x86_64-native-linuxapp-gcc``),
+it contains all libraries and header files required to build an application.
+
+When compiling an application in the Linux* environment on the DPDK, the following variables must be exported:
+
+* ``RTE_SDK`` - Points to the DPDK installation directory.
+
+* ``RTE_TARGET`` - Points to the DPDK target environment directory.
+
+The following is an example of creating the ``helloworld`` application, which runs in the DPDK Linux environment.
+This example may be found in the ``${RTE_SDK}/examples`` directory.
+
+The directory contains the ``main.c`` file. This file, when combined with the libraries in the DPDK target environment,
+calls the various functions to initialize the DPDK environment,
+then launches an entry point (dispatch application) for each core to be utilized.
+By default, the binary is generated in the build directory.
+
+.. code-block:: console
+
+ cd examples/helloworld/
+ export RTE_SDK=$HOME/DPDK
+ export RTE_TARGET=x86_64-native-linuxapp-gcc
+
+ make
+ CC main.o
+ LD helloworld
+ INSTALL-APP helloworld
+ INSTALL-MAP helloworld.map
+
+ ls build/app
+ helloworld helloworld.map
+
+.. note::
+
+ In the above example, ``helloworld`` was in the directory structure of the DPDK.
+ However, it could have been located outside the directory structure to keep the DPDK structure intact.
+ In the following case, the ``helloworld`` application is copied to a new directory as a new starting point.
+
+ .. code-block:: console
+
+ export RTE_SDK=/home/user/DPDK
+ cp -r $(RTE_SDK)/examples/helloworld my_rte_app
+ cd my_rte_app/
+ export RTE_TARGET=x86_64-native-linuxapp-gcc
+
+ make
+ CC main.o
+ LD helloworld
+ INSTALL-APP helloworld
+ INSTALL-MAP helloworld.map
+
+Running a Sample Application
+----------------------------
+
+.. warning::
+
+ The UIO drivers and hugepages must be setup prior to running an application.
+
+.. warning::
+
+ Any ports to be used by the application must be already bound to an appropriate kernel
+ module, as described in :ref:`linux_gsg_binding_kernel`, prior to running the application.
+
+The application is linked with the DPDK target environment's Environmental Abstraction Layer (EAL) library,
+which provides some options that are generic to every DPDK application.
+
+The following is the list of options that can be given to the EAL:
+
+.. code-block:: console
+
+ ./rte-app -c COREMASK [-n NUM] [-b <domain:bus:devid.func>] \
+ [--socket-mem=MB,...] [-m MB] [-r NUM] [-v] [--file-prefix] \
+ [--proc-type <primary|secondary|auto>] [-- xen-dom0]
+
+The EAL options are as follows:
+
+* ``-c COREMASK``:
+ An hexadecimal bit mask of the cores to run on. Note that core numbering can
+ change between platforms and should be determined beforehand.
+
+* ``-n NUM``:
+ Number of memory channels per processor socket.
+
+* ``-b <domain:bus:devid.func>``:
+ Blacklisting of ports; prevent EAL from using specified PCI device
+ (multiple ``-b`` options are allowed).
+
+* ``--use-device``:
+ use the specified Ethernet device(s) only. Use comma-separate
+ ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option.
+
+* ``--socket-mem``:
+ Memory to allocate from hugepages on specific sockets.
+
+* ``-m MB``:
+ Memory to allocate from hugepages, regardless of processor socket. It is
+ recommended that ``--socket-mem`` be used instead of this option.
+
+* ``-r NUM``:
+ Number of memory ranks.
+
+* ``-v``:
+ Display version information on startup.
+
+* ``--huge-dir``:
+ The directory where hugetlbfs is mounted.
+
+* ``--file-prefix``:
+ The prefix text used for hugepage filenames.
+
+* ``--proc-type``:
+ The type of process instance.
+
+* ``--xen-dom0``:
+ Support application running on Xen Domain0 without hugetlbfs.
+
+* ``--vmware-tsc-map``:
+ Use VMware TSC map instead of native RDTSC.
+
+* ``--base-virtaddr``:
+ Specify base virtual address.
+
+* ``--vfio-intr``:
+ Specify interrupt type to be used by VFIO (has no effect if VFIO is not used).
+
+The ``-c`` and option is mandatory; the others are optional.
+
+Copy the DPDK application binary to your target, then run the application as follows
+(assuming the platform has four memory channels per processor socket,
+and that cores 0-3 are present and are to be used for running the application)::
+
+ ./helloworld -c f -n 4
+
+.. note::
+
+ The ``--proc-type`` and ``--file-prefix`` EAL options are used for running
+ multiple DPDK processes. See the "Multi-process Sample Application"
+ chapter in the *DPDK Sample Applications User Guide* and the *DPDK
+ Programmers Guide* for more details.
+
+Logical Core Use by Applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The coremask parameter is always mandatory for DPDK applications.
+Each bit of the mask corresponds to the equivalent logical core number as reported by Linux.
+Since these logical core numbers, and their mapping to specific cores on specific NUMA sockets, can vary from platform to platform,
+it is recommended that the core layout for each platform be considered when choosing the coremask to use in each case.
+
+On initialization of the EAL layer by an DPDK application, the logical cores to be used and their socket location are displayed.
+This information can also be determined for all cores on the system by examining the ``/proc/cpuinfo`` file, for example, by running cat ``/proc/cpuinfo``.
+The physical id attribute listed for each processor indicates the CPU socket to which it belongs.
+This can be useful when using other processors to understand the mapping of the logical cores to the sockets.
+
+.. note::
+
+ A more graphical view of the logical core layout may be obtained using the ``lstopo`` Linux utility.
+ On Fedora Linux, this may be installed and run using the following command::
+
+ sudo yum install hwloc
+ ./lstopo
+
+.. warning::
+
+ The logical core layout can change between different board layouts and should be checked before selecting an application coremask.
+
+Hugepage Memory Use by Applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When running an application, it is recommended to use the same amount of memory as that allocated for hugepages.
+This is done automatically by the DPDK application at startup,
+if no ``-m`` or ``--socket-mem`` parameter is passed to it when run.
+
+If more memory is requested by explicitly passing a ``-m`` or ``--socket-mem`` value, the application fails.
+However, the application itself can also fail if the user requests less memory than the reserved amount of hugepage-memory, particularly if using the ``-m`` option.
+The reason is as follows.
+Suppose the system has 1024 reserved 2 MB pages in socket 0 and 1024 in socket 1.
+If the user requests 128 MB of memory, the 64 pages may not match the constraints:
+
+* The hugepage memory by be given to the application by the kernel in socket 1 only.
+ In this case, if the application attempts to create an object, such as a ring or memory pool in socket 0, it fails.
+ To avoid this issue, it is recommended that the ``--socket-mem`` option be used instead of the ``-m`` option.
+
+* These pages can be located anywhere in physical memory, and, although the DPDK EAL will attempt to allocate memory in contiguous blocks,
+ it is possible that the pages will not be contiguous. In this case, the application is not able to allocate big memory pools.
+
+The socket-mem option can be used to request specific amounts of memory for specific sockets.
+This is accomplished by supplying the ``--socket-mem`` flag followed by amounts of memory requested on each socket,
+for example, supply ``--socket-mem=0,512`` to try and reserve 512 MB for socket 1 only.
+Similarly, on a four socket system, to allocate 1 GB memory on each of sockets 0 and 2 only, the parameter ``--socket-mem=1024,0,1024`` can be used.
+No memory will be reserved on any CPU socket that is not explicitly referenced, for example, socket 3 in this case.
+If the DPDK cannot allocate enough memory on each socket, the EAL initialization fails.
+
+Additional Sample Applications
+------------------------------
+
+Additional sample applications are included in the ${RTE_SDK}/examples directory.
+These sample applications may be built and run in a manner similar to that described in earlier sections in this manual.
+In addition, see the *DPDK Sample Applications User Guide* for a description of the application,
+specific instructions on compilation and execution and some explanation of the code.
+
+Additional Test Applications
+----------------------------
+
+In addition, there are two other applications that are built when the libraries are created.
+The source files for these are in the DPDK/app directory and are called test and testpmd.
+Once the libraries are created, they can be found in the build/app directory.
+
+* The test application provides a variety of specific tests for the various functions in the DPDK.
+
+* The testpmd application provides a number of different packet throughput tests and
+ examples of features such as how to use the Flow Director found in the Intel® 82599 10 Gigabit Ethernet Controller.
diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst
new file mode 100644
index 00000000..076770f2
--- /dev/null
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -0,0 +1,218 @@
+.. BSD LICENSE
+ Copyright(c) 2010-2014 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.
+
+.. _Enabling_Additional_Functionality:
+
+Enabling Additional Functionality
+=================================
+
+.. _High_Precision_Event_Timer:
+
+High Precision Event Timer HPET) Functionality
+----------------------------------------------
+
+BIOS Support
+~~~~~~~~~~~~
+
+The High Precision Timer (HPET) must be enabled in the platform BIOS if the HPET is to be used.
+Otherwise, the Time Stamp Counter (TSC) is used by default.
+The BIOS is typically accessed by pressing F2 while the platform is starting up.
+The user can then navigate to the HPET option. On the Crystal Forest platform BIOS, the path is:
+**Advanced -> PCH-IO Configuration -> High Precision Timer ->** (Change from Disabled to Enabled if necessary).
+
+On a system that has already booted, the following command can be issued to check if HPET is enabled::
+
+ grep hpet /proc/timer_list
+
+If no entries are returned, HPET must be enabled in the BIOS (as per the instructions above) and the system rebooted.
+
+Linux Kernel Support
+~~~~~~~~~~~~~~~~~~~~
+
+The DPDK makes use of the platform HPET timer by mapping the timer counter into the process address space, and as such,
+requires that the ``HPET_MMAP`` kernel configuration option be enabled.
+
+.. warning::
+
+ On Fedora, and other common distributions such as Ubuntu, the ``HPET_MMAP`` kernel option is not enabled by default.
+ To recompile the Linux kernel with this option enabled, please consult the distributions documentation for the relevant instructions.
+
+Enabling HPET in the DPDK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, HPET support is disabled in the DPDK build configuration files.
+To use HPET, the ``CONFIG_RTE_LIBEAL_USE_HPET`` setting should be changed to ``y``, which will enable the HPET settings at compile time.
+
+For an application to use the ``rte_get_hpet_cycles()`` and ``rte_get_hpet_hz()`` API calls,
+and optionally to make the HPET the default time source for the rte_timer library,
+the new ``rte_eal_hpet_init()`` API call should be called at application initialization.
+This API call will ensure that the HPET is accessible, returning an error to the application if it is not,
+for example, if ``HPET_MMAP`` is not enabled in the kernel.
+The application can then determine what action to take, if any, if the HPET is not available at run-time.
+
+.. note::
+
+ For applications that require timing APIs, but not the HPET timer specifically,
+ it is recommended that the ``rte_get_timer_cycles()`` and ``rte_get_timer_hz()`` API calls be used instead of the HPET-specific APIs.
+ These generic APIs can work with either TSC or HPET time sources, depending on what is requested by an application call to ``rte_eal_hpet_init()``,
+ if any, and on what is available on the system at runtime.
+
+Running DPDK Applications Without Root Privileges
+--------------------------------------------------------
+
+Although applications using the DPDK use network ports and other hardware resources directly,
+with a number of small permission adjustments it is possible to run these applications as a user other than "root".
+To do so, the ownership, or permissions, on the following Linux file system objects should be adjusted to ensure that
+the Linux user account being used to run the DPDK application has access to them:
+
+* All directories which serve as hugepage mount points, for example, ``/mnt/huge``
+
+* The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on
+
+* The userspace-io sysfs config and resource files, for example for ``uio0``::
+
+ /sys/class/uio/uio0/device/config
+ /sys/class/uio/uio0/device/resource*
+
+* If the HPET is to be used, ``/dev/hpet``
+
+.. note::
+
+ On some Linux installations, ``/dev/hugepages`` is also a hugepage mount point created by default.
+
+Power Management and Power Saving Functionality
+-----------------------------------------------
+
+Enhanced Intel SpeedStep® Technology must be enabled in the platform BIOS if the power management feature of DPDK is to be used.
+Otherwise, the sys file folder ``/sys/devices/system/cpu/cpu0/cpufreq`` will not exist, and the CPU frequency- based power management cannot be used.
+Consult the relevant BIOS documentation to determine how these settings can be accessed.
+
+For example, on some Intel reference platform BIOS variants, the path to Enhanced Intel SpeedStep® Technology is::
+
+ Advanced
+ -> Processor Configuration
+ -> Enhanced Intel SpeedStep® Tech
+
+In addition, C3 and C6 should be enabled as well for power management. The path of C3 and C6 on the same platform BIOS is::
+
+ Advanced
+ -> Processor Configuration
+ -> Processor C3 Advanced
+ -> Processor Configuration
+ -> Processor C6
+
+Using Linux Core Isolation to Reduce Context Switches
+-----------------------------------------------------
+
+While the threads used by an DPDK application are pinned to logical cores on the system,
+it is possible for the Linux scheduler to run other tasks on those cores also.
+To help prevent additional workloads from running on those cores,
+it is possible to use the ``isolcpus`` Linux kernel parameter to isolate them from the general Linux scheduler.
+
+For example, if DPDK applications are to run on logical cores 2, 4 and 6,
+the following should be added to the kernel parameter list:
+
+.. code-block:: console
+
+ isolcpus=2,4,6
+
+Loading the DPDK KNI Kernel Module
+----------------------------------
+
+To run the DPDK Kernel NIC Interface (KNI) sample application, an extra kernel module (the kni module) must be loaded into the running kernel.
+The module is found in the kmod sub-directory of the DPDK target directory.
+Similar to the loading of the ``igb_uio`` module, this module should be loaded using the insmod command as shown below
+(assuming that the current directory is the DPDK target directory):
+
+.. code-block:: console
+
+ insmod kmod/rte_kni.ko
+
+.. note::
+
+ See the "Kernel NIC Interface Sample Application" chapter in the *DPDK Sample Applications User Guide* for more details.
+
+Using Linux IOMMU Pass-Through to Run DPDK with Intel® VT-d
+-----------------------------------------------------------
+
+To enable Intel® VT-d in a Linux kernel, a number of kernel configuration options must be set. These include:
+
+* ``IOMMU_SUPPORT``
+
+* ``IOMMU_API``
+
+* ``INTEL_IOMMU``
+
+In addition, to run the DPDK with Intel® VT-d, the ``iommu=pt`` kernel parameter must be used when using ``igb_uio`` driver.
+This results in pass-through of the DMAR (DMA Remapping) lookup in the host.
+Also, if ``INTEL_IOMMU_DEFAULT_ON`` is not set in the kernel, the ``intel_iommu=on`` kernel parameter must be used too.
+This ensures that the Intel IOMMU is being initialized as expected.
+
+Please note that while using ``iommu=pt`` is compulsory for ``igb_uio driver``, the ``vfio-pci`` driver can actually work with both ``iommu=pt`` and ``iommu=on``.
+
+High Performance of Small Packets on 40G NIC
+--------------------------------------------
+
+As there might be firmware fixes for performance enhancement in latest version
+of firmware image, the firmware update might be needed for getting high performance.
+Check with the local Intel's Network Division application engineers for firmware updates.
+The base driver to support firmware version of FVL3E will be integrated in the next
+DPDK release, so currently the validated firmware version is 4.2.6.
+
+Enabling Extended Tag
+~~~~~~~~~~~~~~~~~~~~~
+
+PCI configuration of ``extended_tag`` has big impact on small packet size
+performance of 40G ports. Enabling ``extended_tag`` can help 40G port to
+achieve the best performance, especially for small packet size.
+
+* Disabling/enabling ``extended_tag`` can be done in some BIOS implementations.
+
+* If BIOS does not enable it, and does not support changing it, tools
+ (e.g. ``setpci`` on Linux) can be used to enable or disable ``extended_tag``.
+
+* From release 16.04, ``extended_tag`` is enabled by default during port
+ initialization, users don't need to care about that anymore.
+
+Use 16 Bytes RX Descriptor Size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As i40e PMD supports both 16 and 32 bytes RX descriptor sizes, and 16 bytes size can provide helps to high performance of small packets.
+Configuration of ``CONFIG_RTE_LIBRTE_I40E_16BYTE_RX_DESC`` in config files can be changed to use 16 bytes size RX descriptors.
+
+High Performance and per Packet Latency Tradeoff
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Due to the hardware design, the interrupt signal inside NIC is needed for per
+packet descriptor write-back. The minimum interval of interrupts could be set
+at compile time by ``CONFIG_RTE_LIBRTE_I40E_ITR_INTERVAL`` in configuration files.
+Though there is a default configuration, the interval could be tuned by the
+users with that configuration item depends on what the user cares about more,
+performance or per packet latency.
diff --git a/doc/guides/linux_gsg/img/intel_perf_test_setup.svg b/doc/guides/linux_gsg/img/intel_perf_test_setup.svg
new file mode 100644
index 00000000..27c3c1cd
--- /dev/null
+++ b/doc/guides/linux_gsg/img/intel_perf_test_setup.svg
@@ -0,0 +1,507 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="750.94739"
+ height="466.69046"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.91 r13725"
+ sodipodi:docname="intel_perf_test_setup.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow1Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Lstart"
+ style="overflow:visible">
+ <path
+ id="path4005"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(0.8,0,0,0.8,10,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="DotL"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="DotL"
+ style="overflow:visible">
+ <path
+ id="path4066"
+ d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(0.8,0,0,0.8,5.92,0.8)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="SquareL"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="SquareL"
+ style="overflow:visible">
+ <path
+ id="path4075"
+ d="M -5,-5 -5,5 5,5 5,-5 -5,-5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.8,0.8)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path4026"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Lend"
+ style="overflow:visible">
+ <path
+ id="path4008"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.8,0,0,-0.8,-10,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Lend-8"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4008-3"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.8,0,0,-0.8,-10,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker5981"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path5983"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.8,0,0,-0.8,-10,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1"
+ inkscape:cx="121.51181"
+ inkscape:cy="-18.047453"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1168"
+ inkscape:window-height="1153"
+ inkscape:window-x="236"
+ inkscape:window-y="101"
+ inkscape:window-maximized="0"
+ fit-margin-top="0"
+ fit-margin-left="0"
+ fit-margin-right="0"
+ fit-margin-bottom="0" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="BG and Nics"
+ inkscape:groupmode="layer"
+ id="layer1"
+ style="display:inline"
+ transform="translate(-1.4142135,-45.442127)">
+ <rect
+ style="fill:none;stroke:none"
+ id="rect6962"
+ width="750.94739"
+ height="466.69046"
+ x="1.4142135"
+ y="45.442127" />
+ <rect
+ style="fill:#4f87bb;fill-opacity:1;stroke:#4f87bb;stroke-width:1.99999988;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect2985"
+ width="219.20311"
+ height="385.99997"
+ x="22.223356"
+ y="63.362179" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:40px;line-height:125%;font-family:Sans;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none"
+ x="28.550247"
+ y="90.837059"
+ id="text3755"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757"
+ x="28.550247"
+ y="90.837059"
+ style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:125%;font-family:Sans;-inkscape-font-specification:Sans;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1">Traffic Generator</tspan></text>
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-5-4-9"
+ width="233.5"
+ height="126.23654"
+ x="21.723356"
+ y="116.68151" />
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-6-9"
+ width="80"
+ height="62.142132"
+ x="179.5"
+ y="148.72871" />
+ <text
+ xml:space="preserve"
+ style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="38.832031"
+ y="179.08876"
+ id="text3787-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3789-3"
+ x="38.832031"
+ y="179.08876"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Dest MAC: Port 0</tspan><tspan
+ sodipodi:role="line"
+ x="38.832031"
+ y="199.08876"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3814">Dest IP: 2.1.1.1</tspan><tspan
+ sodipodi:role="line"
+ x="38.832031"
+ y="219.08876"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3812">Src IP: Random</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="193.77002"
+ y="186.13669"
+ id="text3755-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757-6"
+ x="193.77002"
+ y="186.13669"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Port A</tspan></text>
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-5-8"
+ width="233.5"
+ height="126.23654"
+ x="20.499784"
+ y="312.46304" />
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-6-9-6"
+ width="80"
+ height="62.142132"
+ x="178.79289"
+ y="344.51025" />
+ <text
+ xml:space="preserve"
+ style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="37.831818"
+ y="375.68961"
+ id="text3787-2-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="37.831818"
+ y="375.68961"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan6829">Dest MAC: Port 1</tspan><tspan
+ sodipodi:role="line"
+ x="37.831818"
+ y="395.68961"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3814-7">Dest IP: 1.1.1.1</tspan><tspan
+ sodipodi:role="line"
+ x="37.831818"
+ y="415.68961"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3812-1">Src IP: Random</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="193.5551"
+ y="381.91824"
+ id="text3755-1-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757-6-6"
+ x="193.5551"
+ y="381.91824"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Port B</tspan></text>
+ <rect
+ style="fill:#4f87bb;fill-opacity:1;stroke:#4f87bb;stroke-width:1.99999964;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect2985-0"
+ width="388.73865"
+ height="379.41064"
+ x="352.02893"
+ y="118.51651" />
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-5-4"
+ width="233.5"
+ height="168.96492"
+ x="340.08374"
+ y="126.68118" />
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-6"
+ width="80"
+ height="62.142132"
+ x="333.83652"
+ y="148.75992" />
+ <text
+ xml:space="preserve"
+ style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="465.28302"
+ y="206.81598"
+ id="text3787-2-0"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="465.28302"
+ y="206.81598"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3812-2">Intel XL 710</tspan><tspan
+ sodipodi:role="line"
+ x="465.28302"
+ y="226.81598"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3954">40G Ethernet</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="349.54794"
+ y="186.15866"
+ id="text3755-1-4"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757-6-5"
+ x="349.54794"
+ y="186.15866"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Port 0</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="64.119629"
+ y="345.36218"
+ id="text6833"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan6835"
+ x="64.119629"
+ y="345.36218">Flow 2</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="65.428223"
+ y="151.4325"
+ id="text6833-6"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan6835-2"
+ x="65.428223"
+ y="151.4325">Flow 1</tspan></text>
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-6-7"
+ width="80"
+ height="62.142132"
+ x="334.14633"
+ y="218.72491" />
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="349.85776"
+ y="256.12366"
+ id="text3755-1-4-5"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757-6-5-7"
+ x="349.85776"
+ y="256.12366"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Port X</tspan></text>
+ </g>
+ <g
+ inkscape:groupmode="layer"
+ id="layer2"
+ inkscape:label="flows"
+ style="display:inline"
+ transform="translate(-1.4142135,-45.442127)">
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-5-4-8"
+ width="233.5"
+ height="168.96492"
+ x="339.71588"
+ y="322.33286" />
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-6-2"
+ width="80"
+ height="62.142132"
+ x="333.46866"
+ y="344.41159" />
+ <path
+ style="fill:none;stroke:#000018;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lend);marker-mid:none;marker-end:url(#Arrow1Lend)"
+ d="m 271.54621,160.17507 171.45382,0 0,234.88637 -185.57109,0"
+ id="path3981"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <text
+ xml:space="preserve"
+ style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="460.91516"
+ y="402.46765"
+ id="text3787-2-0-7"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="460.91516"
+ y="402.46765"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3812-2-8">Intel XL 710</tspan><tspan
+ sodipodi:role="line"
+ x="460.91516"
+ y="422.46765"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3954-0">40G Ethernet</tspan></text>
+ <path
+ style="fill:none;stroke:#000018;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-mid:none;marker-end:url(#Arrow1Lstart)"
+ d="m 258.67113,197.20047 170.29749,0 0,157.21541 -156.72961,0"
+ id="path3981-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="349.18008"
+ y="381.81033"
+ id="text3755-1-4-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757-6-5-0"
+ x="349.18008"
+ y="381.81033"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Port 1</tspan></text>
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-6-7-8"
+ width="80"
+ height="62.142132"
+ x="333.77847"
+ y="414.37659" />
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="349.4899"
+ y="451.77533"
+ id="text3755-1-4-5-9"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757-6-5-7-2"
+ x="349.4899"
+ y="451.77533"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Port X</tspan></text>
+ <rect
+ style="fill:#759fcc;fill-opacity:1;stroke:#ffffff;stroke-width:1.00000048;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3759-5-4-8-8"
+ width="153.5"
+ height="364.84363"
+ x="580.25"
+ y="126.87973" />
+ <text
+ xml:space="preserve"
+ style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="602.55469"
+ y="354.36218"
+ id="text6927"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="602.55469"
+ y="354.36218"
+ id="tspan6931"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Port 0 to Port 1</tspan><tspan
+ sodipodi:role="line"
+ x="602.55469"
+ y="374.36218"
+ id="tspan6933"
+ style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Port 1 to Port 0 </tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans"
+ x="601.75293"
+ y="323.36218"
+ id="text6937"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan6939"
+ x="601.75293"
+ y="323.36218"
+ style="font-size:22px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Forwarding</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="597.66797"
+ y="218.65639"
+ id="text3755-4"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757-9"
+ x="597.66797"
+ y="218.65639"
+ style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">IA Platform</tspan><tspan
+ sodipodi:role="line"
+ x="597.66797"
+ y="248.65639"
+ style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans"
+ id="tspan3948">(Socket 1)</tspan></text>
+ </g>
+</svg>
diff --git a/doc/guides/linux_gsg/index.rst b/doc/guides/linux_gsg/index.rst
new file mode 100644
index 00000000..3d3ada15
--- /dev/null
+++ b/doc/guides/linux_gsg/index.rst
@@ -0,0 +1,46 @@
+.. 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.
+
+.. _linux_gsg:
+
+Getting Started Guide for Linux
+===============================
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ intro
+ sys_reqs
+ build_dpdk
+ build_sample_apps
+ enable_func
+ quick_start
+ nic_perf_intel_platform
diff --git a/doc/guides/linux_gsg/intro.rst b/doc/guides/linux_gsg/intro.rst
new file mode 100644
index 00000000..a812f5c4
--- /dev/null
+++ b/doc/guides/linux_gsg/intro.rst
@@ -0,0 +1,63 @@
+.. BSD LICENSE
+ Copyright(c) 2010-2014 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.
+
+Introduction
+============
+
+This document contains instructions for installing and configuring the Data Plane Development Kit (DPDK) software.
+It is designed to get customers up and running quickly.
+The document describes how to compile and run a DPDK application in a Linux application (linuxapp) environment,
+without going deeply into detail.
+
+Documentation Roadmap
+---------------------
+
+The following is a list of DPDK documents in the suggested reading order:
+
+* Release Notes: Provides release-specific information, including supported features, limitations, fixed issues, known issues and so on.
+ Also, provides the answers to frequently asked questions in FAQ format.
+
+* Getting Started Guide (this document): Describes how to install and configure the DPDK; designed to get users up and running quickly with the software.
+
+* Programmer's Guide: Describes:
+
+ * The software architecture and how to use it (through examples), specifically in a Linux application (linuxapp) environment
+
+ * The content of the DPDK, the build system (including the commands that can be used in the root DPDK Makefile to build the development kit and
+ an application) and guidelines for porting an application
+
+ * Optimizations used in the software and those that should be considered for new development
+
+ A glossary of terms is also provided.
+
+* API Reference: Provides detailed information about DPDK functions, data structures and other programming constructs.
+
+* Sample Applications User Guide: Describes a set of sample applications.
+ Each chapter describes a sample application that showcases specific functionality and provides instructions on how to compile, run and use the sample application.
diff --git a/doc/guides/linux_gsg/nic_perf_intel_platform.rst b/doc/guides/linux_gsg/nic_perf_intel_platform.rst
new file mode 100644
index 00000000..b4337324
--- /dev/null
+++ b/doc/guides/linux_gsg/nic_perf_intel_platform.rst
@@ -0,0 +1,260 @@
+How to get best performance with NICs on Intel platforms
+========================================================
+
+This document is a step-by-step guide for getting high performance from DPDK applications on Intel platforms.
+
+
+Hardware and Memory Requirements
+--------------------------------
+
+For best performance use an Intel Xeon class server system such as Ivy Bridge, Haswell or newer.
+
+Ensure that each memory channel has at least one memory DIMM inserted, and that the memory size for each is at least 4GB.
+**Note**: this has one of the most direct effects on performance.
+
+You can check the memory configuration using ``dmidecode`` as follows::
+
+ dmidecode -t memory | grep Locator
+
+ Locator: DIMM_A1
+ Bank Locator: NODE 1
+ Locator: DIMM_A2
+ Bank Locator: NODE 1
+ Locator: DIMM_B1
+ Bank Locator: NODE 1
+ Locator: DIMM_B2
+ Bank Locator: NODE 1
+ ...
+ Locator: DIMM_G1
+ Bank Locator: NODE 2
+ Locator: DIMM_G2
+ Bank Locator: NODE 2
+ Locator: DIMM_H1
+ Bank Locator: NODE 2
+ Locator: DIMM_H2
+ Bank Locator: NODE 2
+
+The sample output above shows a total of 8 channels, from ``A`` to ``H``, where each channel has 2 DIMMs.
+
+You can also use ``dmidecode`` to determine the memory frequency::
+
+ dmidecode -t memory | grep Speed
+
+ Speed: 2133 MHz
+ Configured Clock Speed: 2134 MHz
+ Speed: Unknown
+ Configured Clock Speed: Unknown
+ Speed: 2133 MHz
+ Configured Clock Speed: 2134 MHz
+ Speed: Unknown
+ ...
+ Speed: 2133 MHz
+ Configured Clock Speed: 2134 MHz
+ Speed: Unknown
+ Configured Clock Speed: Unknown
+ Speed: 2133 MHz
+ Configured Clock Speed: 2134 MHz
+ Speed: Unknown
+ Configured Clock Speed: Unknown
+
+The output shows a speed of 2133 MHz (DDR4) and Unknown (not existing).
+This aligns with the previous output which showed that each channel has one memory bar.
+
+
+Network Interface Card Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use a `DPDK supported <http://dpdk.org/doc/nics>`_ high end NIC such as the Intel XL710 40GbE.
+
+Make sure each NIC has been flashed the latest version of NVM/firmware.
+
+Use PCIe Gen3 slots, such as Gen3 ``x8`` or Gen3 ``x16`` because PCIe Gen2 slots don't provide enough bandwidth
+for 2 x 10GbE and above.
+You can use ``lspci`` to check the speed of a PCI slot using something like the following::
+
+ lspci -s 03:00.1 -vv | grep LnkSta
+
+ LnkSta: Speed 8GT/s, Width x8, TrErr- Train- SlotClk+ DLActive- ...
+ LnkSta2: Current De-emphasis Level: -6dB, EqualizationComplete+ ...
+
+When inserting NICs into PCI slots always check the caption, such as CPU0 or CPU1 to indicate which socket it is connected to.
+
+Care should be take with NUMA.
+If you are using 2 or more ports from different NICs, it is best to ensure that these NICs are on the same CPU socket.
+An example of how to determine this is shown further below.
+
+
+BIOS Settings
+~~~~~~~~~~~~~
+
+The following are some recommendations on BIOS settings. Different platforms will have different BIOS naming
+so the following is mainly for reference:
+
+#. Before starting consider resetting all BIOS settings to their default.
+
+#. Disable all power saving options such as: Power performance tuning, CPU P-State, CPU C3 Report and CPU C6 Report.
+
+#. Select **Performance** as the CPU Power and Performance policy.
+
+#. Disable Turbo Boost to ensure the performance scaling increases with the number of cores.
+
+#. Set memory frequency to the highest available number, NOT auto.
+
+#. Disable all virtualization options when you test the physical function of the NIC, and turn on ``VT-d`` if you wants to use VFIO.
+
+
+Linux boot command line
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The following are some recommendations on GRUB boot settings:
+
+#. Use the default grub file as a starting point.
+
+#. Reserve 1G huge pages via grub configurations. For example to reserve 8 huge pages of 1G size::
+
+ default_hugepagesz=1G hugepagesz=1G hugepages=8
+
+#. Isolate CPU cores which will be used for DPDK. For example::
+
+ isolcpus=2,3,4,5,6,7,8
+
+#. If it wants to use VFIO, use the following additional grub parameters::
+
+ iommu=pt intel_iommu=on
+
+
+Configurations before running DPDK
+----------------------------------
+
+1. Build the DPDK target and reserve huge pages.
+ See the earlier section on :ref:`linux_gsg_hugepages` for more details.
+
+ The following shell commands may help with building and configuration:
+
+ .. code-block:: console
+
+ # Build DPDK target.
+ cd dpdk_folder
+ make install T=x86_64-native-linuxapp-gcc -j
+
+ # Get the hugepage size.
+ awk '/Hugepagesize/ {print $2}' /proc/meminfo
+
+ # Get the total huge page numbers.
+ awk '/HugePages_Total/ {print $2} ' /proc/meminfo
+
+ # Unmount the hugepages.
+ umount `awk '/hugetlbfs/ {print $2}' /proc/mounts`
+
+ # Create the hugepage mount folder.
+ mkdir -p /mnt/huge
+
+ # Mount to the specific folder.
+ mount -t hugetlbfs nodev /mnt/huge
+
+2. Check the CPU layout using using the DPDK ``cpu_layout`` utility:
+
+ .. code-block:: console
+
+ cd dpdk_folder
+
+ tools/cpu_layout.py
+
+ Or run ``lscpu`` to check the the cores on each socket.
+
+3. Check your NIC id and related socket id:
+
+ .. code-block:: console
+
+ # List all the NICs with PCI address and device IDs.
+ lspci -nn | grep Eth
+
+ For example suppose your output was as follows::
+
+ 82:00.0 Ethernet [0200]: Intel XL710 for 40GbE QSFP+ [8086:1583]
+ 82:00.1 Ethernet [0200]: Intel XL710 for 40GbE QSFP+ [8086:1583]
+ 85:00.0 Ethernet [0200]: Intel XL710 for 40GbE QSFP+ [8086:1583]
+ 85:00.1 Ethernet [0200]: Intel XL710 for 40GbE QSFP+ [8086:1583]
+
+ Check the PCI device related numa node id:
+
+ .. code-block:: console
+
+ cat /sys/bus/pci/devices/0000\:xx\:00.x/numa_node
+
+ Usually ``0x:00.x`` is on socket 0 and ``8x:00.x`` is on socket 1.
+ **Note**: To get the best performance, ensure that the core and NICs are in the same socket.
+ In the example above ``85:00.0`` is on socket 1 and should be used by cores on socket 1 for the best performance.
+
+4. Bind the test ports to DPDK compatible drivers, such as igb_uio. For example bind two ports to a DPDK compatible driver and check the status:
+
+ .. code-block:: console
+
+
+ # Bind ports 82:00.0 and 85:00.0 to dpdk driver
+ ./dpdk_folder/tools/dpdk_nic_bind.py -b igb_uio 82:00.0 85:00.0
+
+ # Check the port driver status
+ ./dpdk_folder/tools/dpdk_nic_bind.py --status
+
+ See ``dpdk_nic_bind.py --help`` for more details.
+
+
+More details about DPDK setup and Linux kernel requirements see :ref:`linux_gsg_compiling_dpdk`.
+
+
+Example of getting best performance for an Intel NIC
+----------------------------------------------------
+
+The following is an example of running the DPDK ``l3fwd`` sample application to get high performance with an
+Intel server platform and Intel XL710 NICs.
+For specific 40G NIC configuration please refer to the i40e NIC guide.
+
+The example scenario is to get best performance with two Intel XL710 40GbE ports.
+See :numref:`figure_intel_perf_test_setup` for the performance test setup.
+
+.. _figure_intel_perf_test_setup:
+
+.. figure:: img/intel_perf_test_setup.*
+
+ Performance Test Setup
+
+
+1. Add two Intel XL710 NICs to the platform, and use one port per card to get best performance.
+ The reason for using two NICs is to overcome a PCIe Gen3's limitation since it cannot provide 80G bandwidth
+ for two 40G ports, but two different PCIe Gen3 x8 slot can.
+ Refer to the sample NICs output above, then we can select ``82:00.0`` and ``85:00.0`` as test ports::
+
+ 82:00.0 Ethernet [0200]: Intel XL710 for 40GbE QSFP+ [8086:1583]
+ 85:00.0 Ethernet [0200]: Intel XL710 for 40GbE QSFP+ [8086:1583]
+
+2. Connect the ports to the traffic generator. For high speed testing, it's best to use a hardware traffic generator.
+
+3. Check the PCI devices numa node (socket id) and get the cores number on the exact socket id.
+ In this case, ``82:00.0`` and ``85:00.0`` are both in socket 1, and the cores on socket 1 in the referenced platform
+ are 18-35 and 54-71.
+ Note: Don't use 2 logical cores on the same core (e.g core18 has 2 logical cores, core18 and core54), instead, use 2 logical
+ cores from different cores (e.g core18 and core19).
+
+4. Bind these two ports to igb_uio.
+
+5. As to XL710 40G port, we need at least two queue pairs to achieve best performance, then two queues per port
+ will be required, and each queue pair will need a dedicated CPU core for receiving/transmitting packets.
+
+6. The DPDK sample application ``l3fwd`` will be used for performance testing, with using two ports for bi-directional forwarding.
+ Compile the ``l3fwd sample`` with the default lpm mode.
+
+7. The command line of running l3fwd would be something like the followings::
+
+ ./l3fwd -c 0x3c0000 -n 4 -w 82:00.0 -w 85:00.0 \
+ -- -p 0x3 --config '(0,0,18),(0,1,19),(1,0,20),(1,1,21)'
+
+ This means that the application uses core 18 for port 0, queue pair 0 forwarding, core 19 for port 0, queue pair 1 forwarding,
+ core 20 for port 1, queue pair 0 forwarding, and core 21 for port 1, queue pair 1 forwarding.
+
+
+8. Configure the traffic at a traffic generator.
+
+ * Start creating a stream on packet generator.
+
+ * Set the Ethernet II type to 0x0800.
diff --git a/doc/guides/linux_gsg/quick_start.rst b/doc/guides/linux_gsg/quick_start.rst
new file mode 100644
index 00000000..1e0f8ff3
--- /dev/null
+++ b/doc/guides/linux_gsg/quick_start.rst
@@ -0,0 +1,335 @@
+.. BSD LICENSE
+ Copyright(c) 2010-2014 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.
+
+.. _linux_setup_script:
+
+Quick Start Setup Script
+========================
+
+The setup.sh script, found in the tools subdirectory, allows the user to perform the following tasks:
+
+* Build the DPDK libraries
+
+* Insert and remove the DPDK IGB_UIO kernel module
+
+* Insert and remove VFIO kernel modules
+
+* Insert and remove the DPDK KNI kernel module
+
+* Create and delete hugepages for NUMA and non-NUMA cases
+
+* View network port status and reserve ports for DPDK application use
+
+* Set up permissions for using VFIO as a non-privileged user
+
+* Run the test and testpmd applications
+
+* Look at hugepages in the meminfo
+
+* List hugepages in ``/mnt/huge``
+
+* Remove built DPDK libraries
+
+Once these steps have been completed for one of the EAL targets,
+the user may compile their own application that links in the EAL libraries to create the DPDK image.
+
+Script Organization
+-------------------
+
+The setup.sh script is logically organized into a series of steps that a user performs in sequence.
+Each step provides a number of options that guide the user to completing the desired task.
+The following is a brief synopsis of each step.
+
+**Step 1: Build DPDK Libraries**
+
+Initially, the user must select a DPDK target to choose the correct target type and compiler options to use when building the libraries.
+
+The user must have all libraries, modules, updates and compilers installed in the system prior to this,
+as described in the earlier chapters in this Getting Started Guide.
+
+**Step 2: Setup Environment**
+
+The user configures the Linux* environment to support the running of DPDK applications.
+Hugepages can be set up for NUMA or non-NUMA systems. Any existing hugepages will be removed.
+The DPDK kernel module that is needed can also be inserted in this step,
+and network ports may be bound to this module for DPDK application use.
+
+**Step 3: Run an Application**
+
+The user may run the test application once the other steps have been performed.
+The test application allows the user to run a series of functional tests for the DPDK.
+The testpmd application, which supports the receiving and sending of packets, can also be run.
+
+**Step 4: Examining the System**
+
+This step provides some tools for examining the status of hugepage mappings.
+
+**Step 5: System Cleanup**
+
+The final step has options for restoring the system to its original state.
+
+Use Cases
+---------
+
+The following are some example of how to use the setup.sh script.
+The script should be run using the source command.
+Some options in the script prompt the user for further data before proceeding.
+
+.. warning::
+
+ The setup.sh script should be run with root privileges.
+
+.. code-block:: console
+
+ source tools/setup.sh
+
+ ------------------------------------------------------------------------
+
+ RTE_SDK exported as /home/user/rte
+
+ ------------------------------------------------------------------------
+
+ Step 1: Select the DPDK environment to build
+
+ ------------------------------------------------------------------------
+
+ [1] i686-native-linuxapp-gcc
+
+ [2] i686-native-linuxapp-icc
+
+ [3] ppc_64-power8-linuxapp-gcc
+
+ [4] x86_64-ivshmem-linuxapp-gcc
+
+ [5] x86_64-ivshmem-linuxapp-icc
+
+ [6] x86_64-native-bsdapp-clang
+
+ [7] x86_64-native-bsdapp-gcc
+
+ [8] x86_64-native-linuxapp-clang
+
+ [9] x86_64-native-linuxapp-gcc
+
+ [10] x86_64-native-linuxapp-icc
+
+ ------------------------------------------------------------------------
+
+ Step 2: Setup linuxapp environment
+
+ ------------------------------------------------------------------------
+
+ [11] Insert IGB UIO module
+
+ [12] Insert VFIO module
+
+ [13] Insert KNI module
+
+ [14] Setup hugepage mappings for non-NUMA systems
+
+ [15] Setup hugepage mappings for NUMA systems
+
+ [16] Display current Ethernet device settings
+
+ [17] Bind Ethernet device to IGB UIO module
+
+ [18] Bind Ethernet device to VFIO module
+
+ [19] Setup VFIO permissions
+
+ ------------------------------------------------------------------------
+
+ Step 3: Run test application for linuxapp environment
+
+ ------------------------------------------------------------------------
+
+ [20] Run test application ($RTE_TARGET/app/test)
+
+ [21] Run testpmd application in interactive mode ($RTE_TARGET/app/testpmd)
+
+ ------------------------------------------------------------------------
+
+ Step 4: Other tools
+
+ ------------------------------------------------------------------------
+
+ [22] List hugepage info from /proc/meminfo
+
+ ------------------------------------------------------------------------
+
+ Step 5: Uninstall and system cleanup
+
+ ------------------------------------------------------------------------
+
+ [23] Uninstall all targets
+
+ [24] Unbind NICs from IGB UIO driver
+
+ [25] Remove IGB UIO module
+
+ [26] Remove VFIO module
+
+ [27] Remove KNI module
+
+ [28] Remove hugepage mappings
+
+ [29] Exit Script
+
+Option:
+
+The following selection demonstrates the creation of the ``x86_64-native-linuxapp-gcc`` DPDK library.
+
+.. code-block:: console
+
+ Option: 9
+
+ ================== Installing x86_64-native-linuxapp-gcc
+
+ Configuration done
+ == Build lib
+ ...
+ Build complete
+ RTE_TARGET exported as x86_64-native-linuxapp-gcc
+
+The following selection demonstrates the starting of the DPDK UIO driver.
+
+.. code-block:: console
+
+ Option: 25
+
+ Unloading any existing DPDK UIO module
+ Loading DPDK UIO module
+
+The following selection demonstrates the creation of hugepages in a NUMA system.
+1024 2 MByte pages are assigned to each node.
+The result is that the application should use -m 4096 for starting the application to access both memory areas
+(this is done automatically if the -m option is not provided).
+
+.. note::
+
+ If prompts are displayed to remove temporary files, type 'y'.
+
+.. code-block:: console
+
+ Option: 15
+
+ Removing currently reserved hugepages
+ mounting /mnt/huge and removing directory
+ Input the number of 2MB pages for each node
+ Example: to have 128MB of hugepages available per node,
+ enter '64' to reserve 64 * 2MB pages on each node
+ Number of pages for node0: 1024
+ Number of pages for node1: 1024
+ Reserving hugepages
+ Creating /mnt/huge and mounting as hugetlbfs
+
+The following selection demonstrates the launch of the test application to run on a single core.
+
+.. code-block:: console
+
+ Option: 20
+
+ Enter hex bitmask of cores to execute test app on
+ Example: to execute app on cores 0 to 7, enter 0xff
+ bitmask: 0x01
+ Launching app
+ EAL: coremask set to 1
+ EAL: Detected lcore 0 on socket 0
+ ...
+ EAL: Master core 0 is ready (tid=1b2ad720)
+ RTE>>
+
+Applications
+------------
+
+Once the user has run the setup.sh script, built one of the EAL targets and set up hugepages (if using one of the Linux EAL targets),
+the user can then move on to building and running their application or one of the examples provided.
+
+The examples in the /examples directory provide a good starting point to gain an understanding of the operation of the DPDK.
+The following command sequence shows how the helloworld sample application is built and run.
+As recommended in Section 4.2.1 , "Logical Core Use by Applications",
+the logical core layout of the platform should be determined when selecting a core mask to use for an application.
+
+.. code-block:: console
+
+ cd helloworld/
+ make
+ CC main.o
+ LD helloworld
+ INSTALL-APP helloworld
+ INSTALL-MAP helloworld.map
+
+ sudo ./build/app/helloworld -c 0xf -n 3
+ [sudo] password for rte:
+
+ EAL: coremask set to f
+ EAL: Detected lcore 0 as core 0 on socket 0
+ EAL: Detected lcore 1 as core 0 on socket 1
+ EAL: Detected lcore 2 as core 1 on socket 0
+ EAL: Detected lcore 3 as core 1 on socket 1
+ EAL: Setting up hugepage memory...
+ EAL: Ask a virtual area of 0x200000 bytes
+ EAL: Virtual area found at 0x7f0add800000 (size = 0x200000)
+ EAL: Ask a virtual area of 0x3d400000 bytes
+ EAL: Virtual area found at 0x7f0aa0200000 (size = 0x3d400000)
+ EAL: Ask a virtual area of 0x400000 bytes
+ EAL: Virtual area found at 0x7f0a9fc00000 (size = 0x400000)
+ EAL: Ask a virtual area of 0x400000 bytes
+ EAL: Virtual area found at 0x7f0a9f600000 (size = 0x400000)
+ EAL: Ask a virtual area of 0x400000 bytes
+ EAL: Virtual area found at 0x7f0a9f000000 (size = 0x400000)
+ EAL: Ask a virtual area of 0x800000 bytes
+ EAL: Virtual area found at 0x7f0a9e600000 (size = 0x800000)
+ EAL: Ask a virtual area of 0x800000 bytes
+ EAL: Virtual area found at 0x7f0a9dc00000 (size = 0x800000)
+ EAL: Ask a virtual area of 0x400000 bytes
+ EAL: Virtual area found at 0x7f0a9d600000 (size = 0x400000)
+ EAL: Ask a virtual area of 0x400000 bytes
+ EAL: Virtual area found at 0x7f0a9d000000 (size = 0x400000)
+ EAL: Ask a virtual area of 0x400000 bytes
+ EAL: Virtual area found at 0x7f0a9ca00000 (size = 0x400000)
+ EAL: Ask a virtual area of 0x200000 bytes
+ EAL: Virtual area found at 0x7f0a9c600000 (size = 0x200000)
+ EAL: Ask a virtual area of 0x200000 bytes
+ EAL: Virtual area found at 0x7f0a9c200000 (size = 0x200000)
+ EAL: Ask a virtual area of 0x3fc00000 bytes
+ EAL: Virtual area found at 0x7f0a5c400000 (size = 0x3fc00000)
+ EAL: Ask a virtual area of 0x200000 bytes
+ EAL: Virtual area found at 0x7f0a5c000000 (size = 0x200000)
+ EAL: Requesting 1024 pages of size 2MB from socket 0
+ EAL: Requesting 1024 pages of size 2MB from socket 1
+ EAL: Master core 0 is ready (tid=de25b700)
+ EAL: Core 1 is ready (tid=5b7fe700)
+ EAL: Core 3 is ready (tid=5a7fc700)
+ EAL: Core 2 is ready (tid=5affd700)
+ hello from core 1
+ hello from core 2
+ hello from core 3
+ hello from core 0
diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
new file mode 100644
index 00000000..959709e5
--- /dev/null
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -0,0 +1,269 @@
+.. BSD LICENSE
+ Copyright(c) 2010-2014 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.
+
+System Requirements
+===================
+
+This chapter describes the packages required to compile the DPDK.
+
+.. note::
+
+ If the DPDK is being used on an Intel® Communications Chipset 89xx Series platform,
+ please consult the *Intel® Communications Chipset 89xx Series Software for Linux Getting Started Guide*.
+
+BIOS Setting Prerequisite on x86
+--------------------------------
+
+For the majority of platforms, no special BIOS settings are needed to use basic DPDK functionality.
+However, for additional HPET timer and power management functionality,
+and high performance of small packets on 40G NIC, BIOS setting changes may be needed.
+Consult the section on :ref:`Enabling Additional Functionality <Enabling_Additional_Functionality>`
+for more information on the required changes.
+
+Compilation of the DPDK
+-----------------------
+
+**Required Tools:**
+
+.. note::
+
+ Testing has been performed using Fedora 18. The setup commands and installed packages needed on other systems may be different.
+ For details on other Linux distributions and the versions tested, please consult the DPDK Release Notes.
+
+* GNU ``make``.
+
+* coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc.
+
+* gcc: versions 4.5.x or later is recommended for ``i686/x86_64``. Versions 4.8.x or later is recommended
+ for ``ppc_64`` and ``x86_x32`` ABI. On some distributions, some specific compiler flags and linker flags are enabled by
+ default and affect performance (``-fstack-protector``, for example). Please refer to the documentation
+ of your distribution and to ``gcc -dumpspecs``.
+
+* libc headers, often packaged as ``gcc-multilib`` (``glibc-devel.i686`` / ``libc6-dev-i386``;
+ ``glibc-devel.x86_64`` / ``libc6-dev`` for 64-bit compilation on Intel architecture;
+ ``glibc-devel.ppc64`` for 64 bit IBM Power architecture;)
+
+* Linux kernel headers or sources required to build kernel modules. (kernel - devel.x86_64;
+ kernel - devel.ppc64)
+
+* Additional packages required for 32-bit compilation on 64-bit systems are:
+
+ * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Intel i686/x86_64;
+
+ * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for IBM ppc_64;
+
+.. note::
+
+ x86_x32 ABI is currently supported with distribution packages only on Ubuntu
+ higher than 13.10 or recent Debian distribution. The only supported compiler is gcc 4.8+.
+
+.. note::
+
+ Python, version 2.6 or 2.7, to use various helper scripts included in the DPDK package.
+
+
+**Optional Tools:**
+
+* Intel® C++ Compiler (icc). For installation, additional libraries may be required.
+ See the icc Installation Guide found in the Documentation directory under the compiler installation.
+
+* IBM® Advance ToolChain for Powerlinux. This is a set of open source development tools and runtime libraries
+ which allows users to take leading edge advantage of IBM's latest POWER hardware features on Linux. To install
+ it, see the IBM official installation document.
+
+* libpcap headers and libraries (libpcap-devel) to compile and use the libpcap-based poll-mode driver.
+ This driver is disabled by default and can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_PCAP=y`` in the build time config file.
+
+Running DPDK Applications
+-------------------------
+
+To run an DPDK application, some customization may be required on the target machine.
+
+System Software
+~~~~~~~~~~~~~~~
+
+**Required:**
+
+* Kernel version >= 2.6.34
+
+ The kernel version in use can be checked using the command::
+
+ uname -r
+
+* glibc >= 2.7 (for features related to cpuset)
+
+ The version can be checked using the ``ldd --version`` command.
+
+* Kernel configuration
+
+ In the Fedora OS and other common distributions, such as Ubuntu, or Red Hat Enterprise Linux,
+ the vendor supplied kernel configurations can be used to run most DPDK applications.
+
+ For other kernel builds, options which should be enabled for DPDK include:
+
+ * UIO support
+
+ * HUGETLBFS
+
+ * PROC_PAGE_MONITOR support
+
+ * HPET and HPET_MMAP configuration options should also be enabled if HPET support is required.
+ See the section on :ref:`High Precision Event Timer (HPET) Functionality <High_Precision_Event_Timer>` for more details.
+
+.. _linux_gsg_hugepages:
+
+Use of Hugepages in the Linux Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Hugepage support is required for the large memory pool allocation used for packet buffers
+(the HUGETLBFS option must be enabled in the running kernel as indicated the previous section).
+By using hugepage allocations, performance is increased since fewer pages are needed,
+and therefore less Translation Lookaside Buffers (TLBs, high speed translation caches),
+which reduce the time it takes to translate a virtual page address to a physical page address.
+Without hugepages, high TLB miss rates would occur with the standard 4k page size, slowing performance.
+
+Reserving Hugepages for DPDK Use
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The allocation of hugepages should be done at boot time or as soon as possible after system boot
+to prevent memory from being fragmented in physical memory.
+To reserve hugepages at boot time, a parameter is passed to the Linux kernel on the kernel command line.
+
+For 2 MB pages, just pass the hugepages option to the kernel. For example, to reserve 1024 pages of 2 MB, use::
+
+ hugepages=1024
+
+For other hugepage sizes, for example 1G pages, the size must be specified explicitly and
+can also be optionally set as the default hugepage size for the system.
+For example, to reserve 4G of hugepage memory in the form of four 1G pages, the following options should be passed to the kernel::
+
+ default_hugepagesz=1G hugepagesz=1G hugepages=4
+
+.. note::
+
+ The hugepage sizes that a CPU supports can be determined from the CPU flags on Intel architecture.
+ If pse exists, 2M hugepages are supported; if pdpe1gb exists, 1G hugepages are supported.
+ On IBM Power architecture, the supported hugepage sizes are 16MB and 16GB.
+
+.. note::
+
+ For 64-bit applications, it is recommended to use 1 GB hugepages if the platform supports them.
+
+In the case of a dual-socket NUMA system,
+the number of hugepages reserved at boot time is generally divided equally between the two sockets
+(on the assumption that sufficient memory is present on both sockets).
+
+See the Documentation/kernel-parameters.txt file in your Linux source tree for further details of these and other kernel options.
+
+**Alternative:**
+
+For 2 MB pages, there is also the option of allocating hugepages after the system has booted.
+This is done by echoing the number of hugepages required to a nr_hugepages file in the ``/sys/devices/`` directory.
+For a single-node system, the command to use is as follows (assuming that 1024 pages are required)::
+
+ echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
+
+On a NUMA machine, pages should be allocated explicitly on separate nodes::
+
+ echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
+ echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages
+
+.. note::
+
+ For 1G pages, it is not possible to reserve the hugepage memory after the system has booted.
+
+Using Hugepages with the DPDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Once the hugepage memory is reserved, to make the memory available for DPDK use, perform the following steps::
+
+ mkdir /mnt/huge
+ mount -t hugetlbfs nodev /mnt/huge
+
+The mount point can be made permanent across reboots, by adding the following line to the ``/etc/fstab`` file::
+
+ nodev /mnt/huge hugetlbfs defaults 0 0
+
+For 1GB pages, the page size must be specified as a mount option::
+
+ nodev /mnt/huge_1GB hugetlbfs pagesize=1GB 0 0
+
+Xen Domain0 Support in the Linux Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The existing memory management implementation is based on the Linux kernel hugepage mechanism.
+On the Xen hypervisor, hugepage support for DomainU (DomU) Guests means that DPDK applications work as normal for guests.
+
+However, Domain0 (Dom0) does not support hugepages.
+To work around this limitation, a new kernel module rte_dom0_mm is added to facilitate the allocation and mapping of memory via
+**IOCTL** (allocation) and **MMAP** (mapping).
+
+Enabling Xen Dom0 Mode in the DPDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, Xen Dom0 mode is disabled in the DPDK build configuration files.
+To support Xen Dom0, the CONFIG_RTE_LIBRTE_XEN_DOM0 setting should be changed to “y”, which enables the Xen Dom0 mode at compile time.
+
+Furthermore, the CONFIG_RTE_EAL_ALLOW_INV_SOCKET_ID setting should also be changed to “y” in the case of the wrong socket ID being received.
+
+Loading the DPDK rte_dom0_mm Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To run any DPDK application on Xen Dom0, the ``rte_dom0_mm`` module must be loaded into the running kernel with rsv_memsize option.
+The module is found in the kmod sub-directory of the DPDK target directory.
+This module should be loaded using the insmod command as shown below (assuming that the current directory is the DPDK target directory)::
+
+ sudo insmod kmod/rte_dom0_mm.ko rsv_memsize=X
+
+The value X cannot be greater than 4096(MB).
+
+Configuring Memory for DPDK Use
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After the rte_dom0_mm.ko kernel module has been loaded, the user must configure the memory size for DPDK usage.
+This is done by echoing the memory size to a memsize file in the /sys/devices/ directory.
+Use the following command (assuming that 2048 MB is required)::
+
+ echo 2048 > /sys/kernel/mm/dom0-mm/memsize-mB/memsize
+
+The user can also check how much memory has already been used::
+
+ cat /sys/kernel/mm/dom0-mm/memsize-mB/memsize_rsvd
+
+Xen Domain0 does not support NUMA configuration, as a result the ``--socket-mem`` command line option is invalid for Xen Domain0.
+
+.. note::
+
+ The memsize value cannot be greater than the rsv_memsize value.
+
+Running the DPDK Application on Xen Domain0
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To run the DPDK application on Xen Domain0, an extra command line option ``--xen-dom0`` is required.