Adjusted line lengths and removed references to Intel which
are no longer relevant in linux gsg.
Signed-off-by: Siobhan Butler <siobhan.a.butler at intel.com>
---
doc/guides/linux_gsg/build_dpdk.rst | 149 +++++++++++++----------
doc/guides/linux_gsg/build_sample_apps.rst | 146 +++++++++++++----------
doc/guides/linux_gsg/enable_func.rst | 144 ++++++++++++++---------
doc/guides/linux_gsg/intro.rst | 37 +++---
doc/guides/linux_gsg/quick_start.rst | 57 +++++----
doc/guides/linux_gsg/sys_reqs.rst | 182 +++++++++++++++++------------
6 files changed, 423 insertions(+), 292 deletions(-)
diff --git a/doc/guides/linux_gsg/build_dpdk.rst
b/doc/guides/linux_gsg/build_dpdk.rst
index ee6cb69..db452d5 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -28,17 +28,18 @@
(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 the Intel? DPDK Target from Source
-============================================
+Compiling the DPDK Target from Source
+=====================================
.. note::
- Parts of this process can also be done using the setup script described in
Chapter 6 of this document.
+ Parts of this process can also be done using the setup script described in
+ Chapter 6 of this document.
-Install the Intel? DPDK and Browse Sources
-------------------------------------------
+Install the DPDK and Browse Sources
+-----------------------------------
-First, uncompress the archive and move to the uncompressed Intel? DPDK source
directory:
+First, uncompress the archive and move to the uncompressed DPDK source
directory:
.. code-block:: console
@@ -47,20 +48,20 @@ First, uncompress the archive and move to the uncompressed
Intel? DPDK source d
user at host:~/DPDK-<version>$ ls
app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Makefile
mk/ scripts/ tools/
-The Intel? DPDK is composed of several directories:
+The DPDK is composed of several directories:
-* lib: Source code of Intel? DPDK libraries
+* lib: Source code of DPDK libraries
-* app: Source code of Intel? DPDK applications (automatic tests)
+* app: Source code of DPDK applications (automatic tests)
-* examples: Source code of Intel? DPDK application examples
+* examples: Source code of DPDK application examples
* config, tools, scripts, mk: Framework-related makefiles, scripts and
configuration
-Installation of Intel? DPDK Target Environments
------------------------------------------------
+Installation of DPDK Target Environments
+----------------------------------------
-The format of a Intel? DPDK target is:
+The format of a DPDK target is:
ARCH-MACHINE-EXECENV-TOOLCHAIN
@@ -74,8 +75,8 @@ where:
* 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 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::
@@ -83,10 +84,12 @@ The defconfig\_ prefix should not be used.
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
*Intel? DPDK Programmers Guide*.
+ 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.
+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
@@ -94,7 +97,8 @@ Also, verify the compiler's installation directory since the
path may be differe
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 Intel? DPDK directory.
+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:
@@ -122,9 +126,11 @@ To compile all 64-bit targets using both gcc and icc, use:
.. note::
- The wildcard operator (*) can be used to create multiple targets at the
same time.
+ The wildcard operator (*) can be used to create multiple targets at the
same
+ time.
-To prepare a target without building it, for example, if the configuration
changes need to be made before compilation,
+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
@@ -133,12 +139,15 @@ use the make config T=<target> command:
.. warning::
- The igb_uio module must be compiled with the same kernel as the one
running on the target.
- If the Intel? 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.
+ The igb_uio module 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 Intel? DPDK
configuration by editing the .config file in the build directory.
+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
@@ -147,13 +156,15 @@ The user may also make modifications to the compile-time
Intel? DPDK configurat
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.
+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 Intel? DPDK Environment Target
------------------------------------------------------
+Browsing the Installed DPDK Environment Target
+----------------------------------------------
-Once a target is created it contains all libraries and header files for the
Intel? 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.
+Once a target is created it contains all libraries 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.
In the case of Linux, a kmod directory is also present that contains a module
to install:
.. code-block:: console
@@ -161,13 +172,15 @@ In the case of Linux, a kmod directory is also present
that contains a module t
$ ls x86_64-native-linuxapp-gcc
app build hostapp include kmod lib Makefile
-Loading the Intel? DPDK igb_uio Module
---------------------------------------
+Loading the DPDK igb_uio Module
+-------------------------------
-To run any Intel? DPDK application, the igb_uio module can be loaded into the
running kernel.
-The module is found in the kmod sub-directory of the Intel? DPDK target
directory.
-This module should be loaded using the insmod command as shown below (assuming
that the current directory is the Intel? DPDK target directory).
-In many cases, the uio support in the Linux* kernel is compiled as a module
rather than as part of the kernel,
+To run any DPDK application, the igb_uio module can be loaded into the running
kernel.
+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).
+In many cases, the uio support in the Linux* kernel is compiled as a module
rather
+than as part of the kernel,
so it is often necessary to load the uio module first:
.. code-block:: console
@@ -175,54 +188,68 @@ so it is often necessary to load the uio module first:
sudo modprobe uio
sudo insmod kmod/igb_uio.ko
-Since Intel? DPDK release 1.7 provides VFIO support, compilation and use of
igb_uio module has become optional for platforms that support using VFIO.
+Since DPDK release 1.7 provides VFIO support, compilation and use of igb_uio
module
+has become optional for platforms that support using VFIO.
Loading VFIO Module
-------------------
-To run an Intel? DPDK application and make use of VFIO, the vfio-pci module
must be loaded:
+To run a 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.
+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).
+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 Intel? DPDK applications as a
non-privileged user, correct permissions should also be set up.
-This can be done by using the Intel? DPDK setup script (called setup.sh and
located in the tools directory).
+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).
Binding and Unbinding Network Ports to/from the igb_uioor VFIO Modules
----------------------------------------------------------------------
-As of release 1.4, Intel? 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 Intel? DPDK application must be
bound to the igb_uio or vfio-pci module before the application is run.
-Any network ports under Linux* control will be ignored by the Intel? DPDK
poll-mode drivers and cannot be used by the application.
+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 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 Intel? DPDK will, by default, no longer automatically unbind network
ports from the kernel driver at startup.
- Any ports to be used by an Intel? DPDK application must be unbound from
Linux* control and bound to the igb_uio or vfio-pci module before the
application is run.
-
-To bind ports to the igb_uio or vfio-pci module for Intel? 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 igb_uio and vfio-pci.
+ 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 igb_uio or vfio-pci module
before
+ the application is run.
+
+To bind ports to the 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 igb_uio and vfio-pci.
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.
+A full description of the script and its parameters can be obtained by calling
the
+script with the --help or --usage options.
.. 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.
+ 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.
+ 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::
diff --git a/doc/guides/linux_gsg/build_sample_apps.rst
b/doc/guides/linux_gsg/build_sample_apps.rst
index 0eec4b1..87edbcd 100644
--- a/doc/guides/linux_gsg/build_sample_apps.rst
+++ b/doc/guides/linux_gsg/build_sample_apps.rst
@@ -31,32 +31,34 @@
Compiling and Running Sample Applications
=========================================
-The chapter describes how to compile and run applications in an Intel? DPDK
environment.
+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 in
**Chapter 6** of this document.
+ Parts of this process can also be done using the setup script described
+ in **Chapter 6** of this document.
Compiling a Sample Application
------------------------------
-Once an Intel? DPDK target environment directory has been created (such as
x86_64-native-linuxapp-gcc),
+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 Intel? DPDK,
the following variables must be exported:
+When compiling an application in the Linux* environment on the DPDK, the
+following variables must be exported:
-* RTE_SDK - Points to the Intel? DPDK installation directory.
+* RTE_SDK - Points to the DPDK installation directory.
-* RTE_TARGET - Points to the Intel? DPDK target environment directory.
+* RTE_TARGET - Points to the DPDK target environment directory.
-The following is an example of creating the helloworld application, which runs
in the Intel? DPDK Linux environment.
-This example may be found in the ${RTE_SDK}/examples 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 Intel? DPDK target environment,
-calls the various functions to initialize the Intel? 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.
+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
@@ -74,9 +76,11 @@ By default, the binary is generated in the build directory.
.. note::
- In the above example, helloworld was in the directory structure of the
Intel? DPDK.
- However, it could have been located outside the directory structure to
keep the Intel? DPDK structure intact.
- In the following case, the helloworld application is copied to a new
directory as a new starting point.
+ 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
@@ -99,10 +103,12 @@ Running a Sample Application
.. warning::
- Any ports to be used by the application must be already bound to the
igb_uio module, as described in Section 3.5, prior to running the application.
+ Any ports to be used by the application must be already bound to the
igb_uio module,
+ as described in Section 3.5, prior to running the application.
-The application is linked with the Intel? DPDK target environment's
Environmental Abstraction Layer (EAL) library,
-which provides some options that are generic to every Intel? DPDK 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:
@@ -112,17 +118,21 @@ The following is the list of options that can be given to
the EAL:
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.
+* -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)
+* -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
+* --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.
+* -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
@@ -144,7 +154,7 @@ The EAL options are as follows:
The -c and the -n options are mandatory; the others are optional.
-Copy the Intel? DPDK application binary to your target, then run the
application as follows
+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):
@@ -154,27 +164,35 @@ and that cores 0-3 are present and are to be used for
running the application):
.. note::
- The --proc-type and --file-prefix EAL options are used for running
multiple Intel? DPDK processes.
- See the ?Multi-process Sample Application? chapter in the *Intel? DPDK
Sample Applications User Guide* and
- the *Intel? DPDK Programmers Guide* for more details.
+ 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 Intel? 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 Intel? 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.
+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 Intel? 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* 18, this may be installed and run using the following command:
+ A more graphical view of the logical core layout may be obtained using the
+ lstopo Linux utility. On Fedora* 18, this may be installed and run using
the
+ following command:
.. code-block:: console
@@ -183,42 +201,52 @@ This can be useful when using other processors to
understand the mapping of the
.. warning::
- The logical core layout can change between different board layouts and
should be checked before selecting an application coremask.
+ 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 Intel? DPDK application at startup,
-if no -m or --socket-mem parameter is passed to it when run.
+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.
+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
Intel? 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 Intel? DPDK cannot allocate enough memory on each socket, the EAL
initialization fails.
+ 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 *Intel? DPDK Sample Applications User Guide* for a
description of the application,
-specific instructions on compilation and execution and some explanation of the
code.
+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
----------------------------
@@ -227,7 +255,7 @@ In addition, there are two other applications that are
built when the libraries
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 Intel? DPDK.
+* 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
index 00c6d9e..e54a913 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -41,58 +41,70 @@ 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 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).
+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:
+On a system that has already booted, the following command can be issued to
check
+if HPET is enabled:
.. code-block:: console
# 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.
+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 Intel? 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.
+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.
+ 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 Intel? DPDK
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Enabling HPET in the DPDK
+~~~~~~~~~~~~~~~~~~~~~~~~~
-By default, HPET support is disabled in the Intel? 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.
+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.
+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.
+ 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 Intel? DPDK Applications Without Root Privileges
---------------------------------------------------------
+Running DPDK Applications Without Root Privileges
+-------------------------------------------------
-Although applications using the Intel? 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 Intel? DPDK application has
access to them:
+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
@@ -102,45 +114,53 @@ the Linux user account being used to run the Intel? DPDK
application has access
.. note::
- On some Linux installations, /dev/hugepages is also a hugepage mount
point created by default.
+ 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 Intel? 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.
+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:
+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:
+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 Intel? DPDK application are pinned to logical
cores on the system,
+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.
+it is possible to use the isolcpus Linux* kernel parameter to isolate them from
+the general Linux scheduler.
-For example, if Intel? DPDK applications are to run on logical cores 2, 4 and
6,
+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 Intel? DPDK KNI Kernel Module
------------------------------------------
+Loading the DPDK KNI Kernel Module
+----------------------------------
-To run the Intel? 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 Intel? 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 Intel? DPDK target directory):
+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
@@ -148,12 +168,14 @@ Similar to the loading of the igb_uio module, this module
should be loaded using
.. note::
- See the ?Kernel NIC Interface Sample Application? chapter in the *Intel?
DPDK Sample Applications User Guide* for more details.
+ 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 Intel? DPDK with Intel? VT-d
+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:
+To enable Intel? VT-d in a Linux kernel, a number of kernel configuration
options
+must be set. These include:
* IOMMU_SUPPORT
@@ -161,12 +183,15 @@ To enable Intel? VT-d in a Linux kernel, a number of
kernel configuration optio
* INTEL_IOMMU
-In addition, to run the Intel? 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.
+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.
+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
--------------------------------------------
@@ -178,18 +203,23 @@ Check with the local Intel's Network Division application
engineers for firmware
Enabling Extended Tag and Setting Max Read Request Size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-PCI configurations of extended_tag and max _read_requ st_size have big impacts
on performance of small packets on 40G NIC.
-Enabling extended_tag and setting max _read_requ st_size to small size such as
128 bytes provide great helps to high performance of small packets.
+PCI configurations of extended_tag and max _read_requ st_size have big impacts
on
+performance of small packets on 40G NIC. Enabling extended_tag and setting
+max _read_requ st_size to small size such as 128 bytes provide great helps to
+high performance of small packets.
* These can be done in some BIOS implementations.
-* For other BIOS implementations, PCI configurations can be changed by using
command of setpci, or special configurations in DPDK config file of
common_linux.
+* For other BIOS implementations, PCI configurations can be changed by using
+ command of setpci, or special configurations in DPDK config file of
common_linux.
- * Bits 7:5 at address of 0xA8 of each PCI device is used for setting the
max_read_request_size,
- and bit 8 of 0xA8 of each PCI device is used for enabling/disabling
the extended_tag.
- lspci and setpci can be used to read the values of 0xA8 and then write
it back after being changed.
+ * Bits 7:5 at address of 0xA8 of each PCI device is used for setting the
+ max_read_request_size, and bit 8 of 0xA8 of each PCI device is used for
+ enabling/disabling the extended_tag. lspci and setpci can be used to
+ read the values of 0xA8 and then write it back after being changed.
- * In config file of common_linux, below three configurations can be
changed for the same purpose.
+ * In config file of common_linux, below three configurations can be
changed
+ for the same purpose.
CONFIG_RTE_PCI_CONFIG
@@ -200,8 +230,10 @@ Enabling extended_tag and setting max _read_requ st_size
to small size such as 1
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.
+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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/linux_gsg/intro.rst b/doc/guides/linux_gsg/intro.rst
index 6bcc80b..c8adad6 100644
--- a/doc/guides/linux_gsg/intro.rst
+++ b/doc/guides/linux_gsg/intro.rst
@@ -31,37 +31,42 @@
Introduction
============
-This document contains instructions for installing and configuring the Intel?
Data Plane Development Kit (Intel? DPDK) software.
-It is designed to get customers up and running quickly.
-The document describes how to compile and run an Intel? DPDK application in a
Linux* application (linuxapp) environment,
-without going deeply into detail.
+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 Intel? DPDK documents in the suggested reading
order:
+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.
+* 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 Intel? DPDK; designed to get users up and running quickly with
the software.
+* 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 software architecture and how to use it (through examples),
+ specifically in a Linux* application (linuxapp) environment
- * The content of the Intel? DPDK, the build system (including the
commands that can be used in the root Intel? DPDK Makefile to build the
development kit and
+ * 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
+ * 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 Intel? DPDK functions,
data structures and other programming constructs.
+* 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.
-
-.. note::
-
- These documents are available for download as a separate documentation
package at the same location as the Intel? DPDK code package.
+ 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/quick_start.rst
b/doc/guides/linux_gsg/quick_start.rst
index 089dddb..a19ae00 100644
--- a/doc/guides/linux_gsg/quick_start.rst
+++ b/doc/guides/linux_gsg/quick_start.rst
@@ -33,17 +33,17 @@ Quick Start Setup Script
The setup.sh script, found in the tools subdirectory, allows the user to
perform the following tasks:
-* Build the Intel? DPDK libraries
+* Build the DPDK libraries
-* Insert and remove the Intel? DPDK IGB_UIO kernel module
+* Insert and remove the DPDK IGB_UIO kernel module
* Insert and remove VFIO kernel modules
-* Insert and remove the Intel? DPDK KNI kernel module
+* 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 Intel? DPDK application use
+* View network port status and reserve ports for DPDK application use
* Set up permissions for using VFIO as a non-privileged user
@@ -53,37 +53,40 @@ The setup.sh script, found in the tools subdirectory,
allows the user to perform
* List hugepages in /mnt/huge
-* Remove built Intel? DPDK libraries
+* 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 Intel? DPDK image.
+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.
+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 an Intel? DPDK target to choose the correct
target type and compiler options to use when building the 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.
+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 Intel?
DPDK applications.
-Hugepages can be set up for NUMA or non-NUMA systems. Any existing hugepages
will be removed.
-The Intel? DPDK kernel module that is needed can also be inserted in this step,
-and network ports may be bound to this module for Intel? DPDK application use.
+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 Intel? DPDK.
-The testpmd application, which supports the receiving and sending of packets,
can also be run.
+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**
@@ -196,7 +199,8 @@ Some options in the script prompt the user for further data
before proceeding.
Option:
-The following selection demonstrates the creation of the
x86_64-native-linuxapp-gcc Intel? DPDK library.
+The following selection demonstrates the creation of the
x86_64-native-linuxapp-gcc
+DPDK library.
.. code-block:: console
@@ -212,7 +216,7 @@ The following selection demonstrates the creation of the
x86_64-native-linuxapp-
Build complete
RTE_TARGET exported as x86_64-native -linuxapp-gcc
-The following selection demonstrates the starting of the Intel? DPDK UIO
driver.
+The following selection demonstrates the starting of the DPDK UIO driver.
.. code-block:: console
@@ -263,13 +267,16 @@ The following selection demonstrates the launch of the
test application to run o
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.
+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 Intel? DPDK.
-The following command sequence shows how the helloworld sample application is
built and run.
+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 ? on page
14,
-the logical core layout of the platform should be determined when selecting a
core mask to use for an application.
+the logical core layout of the platform should be determined when selecting a
+core mask to use for an application.
.. code-block:: console
diff --git a/doc/guides/linux_gsg/sys_reqs.rst
b/doc/guides/linux_gsg/sys_reqs.rst
index c14411e..b134482 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -31,42 +31,46 @@
System Requirements
===================
-This chapter describes the packages required to compile the Intel? DPDK.
+This chapter describes the packages required to compile the DPDK.
.. note::
- If the Intel? 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*.
+ 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
-------------------------
-For the majority of platforms, no special BIOS settings are needed to use
basic Intel? 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.
+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 :ref:`Chapter 5. Enabling Additional Functionality
<Enabling_Additional_Functionality>`
for more information on the required changes.
-Compilation of the Intel? DPDK
-------------------------------
+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 Intel? DPDK Release Notes.
+ Testing has been performed using Fedora* 20. 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
* gcc: versions 4.5.x or later is recommended.
- On some distributions, some specific compiler flags and linker flags are
enabled by default and
- affect performance (- fstack-protector, for example).
+ 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 (glibc-devel.i686 / libc6-dev-i386; glibc-devel.x86_64 for
64-bit compilation)
+* libc headers (glibc-devel.i686 / libc6-dev-i386; glibc-devel.x86_64 for
64-bit compilation)
* Linux kernel headers or sources required to build kernel modules. (kernel-
devel.x86_64)
@@ -74,22 +78,25 @@ Compilation of the Intel? DPDK
glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686
-* Python, version 2.6 or 2.7, to use various helper scripts included in the
Intel? DPDK package
+* 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.
- This release has been tested using version 12.1.
+* 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. This release has been tested using version 12.1.
-* 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.
+* 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 Intel? DPDK Applications
+Running DPDK Applications
--------------------------------
-To run an Intel? DPDK application, some customization may be required on the
target machine.
+To run a DPDK application, some customization may be required on the target
machine.
System Software
~~~~~~~~~~~~~~~
@@ -104,13 +111,15 @@ System Software
uname -r
-For details of the patches needed to use the Intel? DPDK with earlier kernel
versions,
-see the Intel? DPDK FAQ included in the *Intel? DPDK Release Notes*.
-Note also that Redhat* Linux* 6.2 and 6.3 uses a 2.6.32 kernel that already
has all the necessary patches applied.
+For details of the patches needed to use the DPDK with earlier kernel versions,
+see the DPDK FAQ included in the *DPDK Release Notes*.
+Note also that Redhat* Linux* 6.2 and 6.3 uses a 2.6.32 kernel that already
+has all the necessary patches applied.
* glibc >= 2.7 (for features related to cpuset)
- The version can be checked using the ldd --version command. A sample
output is shown below:
+ The version can be checked using the ldd --version command.
+ A sample output is shown below:
.. code-block:: console
@@ -124,10 +133,11 @@ Note also that Redhat* Linux* 6.2 and 6.3 uses a 2.6.32
kernel that already has
* Kernel configuration
- In the Fedora* OS and other common distributions, such as Ubuntu*, or
RedHat Enterprise Linux*,
- the vendor supplied kernel configurations can be used to run most Intel?
DPDK applications.
+ In the Fedora* OS and other common distributions, such as Ubuntu*, or
RedHat
+ 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 Intel? DPDK
include:
+ For other kernel builds, options which should be enabled for DPDK include:
* UIO support
@@ -135,8 +145,9 @@ Note also that Redhat* Linux* 6.2 and 6.3 uses a 2.6.32
kernel that already has
* PROC_PAGE_MONITOR support
- * HPET and HPET_MMAP configuration options should also be enabled if
HPET support is required.
- See :ref:`Section 5.1 High Precision Event Timer (HPET) Functionality
<High_Precision_Event_Timer>` for more details.
+ * HPET and HPET_MMAP configuration options should also be enabled if HPET
+ support is required. See :ref:`Section 5.1 High Precision Event Timer
+ (HPET) Functionality <High_Precision_Event_Timer>` for more details.
Use of Hugepages in the Linux* Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -146,24 +157,28 @@ Hugepage support is required for the large memory pool
allocation used for packe
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.
+Without hugepages, high TLB miss rates would occur with the standard 4k page
size,
+slowing performance.
-Reserving Hugepages for Intel? DPDK Use
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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.
+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:
+For 2 MB pages, just pass the hugepages option to the kernel. For example, to
+reserve 1024 pages of 2 MB, use:
.. code-block:: console
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:
+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:
.. code-block:: console
@@ -172,23 +187,29 @@ For example, to reserve 4G of hugepage memory in the form
of four 1G pages, the
.. note::
The hugepage sizes that a CPU supports can be determined from the CPU
flags.
- If pse exists, 2M hugepages are supported; if pdpe1gb exists, 1G hugepages
are supported.
+ If pse exists, 2M hugepages are supported; if pdpe1gb exists, 1G hugepages
+ are supported.
.. note::
- For 64-bit applications, it is recommended to use 1 GB hugepages if the
platform supports them.
+ 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
+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.
+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):
+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):
.. code-block:: console
@@ -203,19 +224,22 @@ On a NUMA machine, pages should be allocated explicitly
on separate nodes:
.. note::
- For 1G pages, it is not possible to reserve the hugepage memory after the
system has booted.
+ For 1G pages, it is not possible to reserve the hugepage memory after the
+ system has booted.
-Using Hugepages with the Intel? DPDK
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using Hugepages with the DPDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Once the hugepage memory is reserved, to make the memory available for Intel?
DPDK use, perform the following steps:
+Once the hugepage memory is reserved, to make the memory available for
+DPDK use, perform the following steps:
.. code-block:: console
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:
+The mount point can be made permanent across reboots, by adding the following
line
+to the /etc/fstab file:
.. code-block:: console
@@ -230,27 +254,33 @@ For 1GB pages, the page size must be specified as a mount
option:
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
Intel? DPDK applications work as normal for guests.
+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).
+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 Intel? DPDK
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Enabling Xen Dom0 Mode in the DPDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By default, Xen Dom0 mode is disabled in the Intel? 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.
+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.
+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 Intel? DPDK rte_dom0_mm Module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Loading the DPDK rte_dom0_mm Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To run any Intel? 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 Intel? DPDK target
directory.
-This module should be loaded using the insmod command as shown below (assuming
that the current directory is the Intel? DPDK target directory):
+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):
.. code-block:: console
@@ -258,11 +288,12 @@ This module should be loaded using the insmod command as
shown below (assuming t
The value X cannot be greater than 4096(MB).
-Configuring Memory for Intel? DPDK Use
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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.
+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):
.. code-block:: console
@@ -275,13 +306,14 @@ 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.
+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 Intel? DPDK Application on Xen Domain0
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Running the DPDK Application on Xen Domain0
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To run the Intel? DPDK application on Xen Domain0, an extra command line
option --xen-dom0 is required.
+To run the DPDK application on Xen Domain0, an extra command line option
--xen-dom0 is required.
--
1.9.4.msysgit.2
