--- /dev/null
+.. 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.
Code Review / deb_dpdk.git / blobdiff