-.. 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.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation.
+
+.. _compiling_sample_apps:
Compiling and Running Sample Applications
=========================================
-The chapter describes how to compile and run applications in an Intel® DPDK environment.
-It also provides a pointer to where sample applications are stored.
+The chapter describes how to compile and run applications in a DPDK
+environment. It also provides a pointer to where sample applications are stored.
Compiling a Sample Application
------------------------------
-Once an Intel® DPDK target environment directory has been created (such as x86_64-native-bsdapp-gcc),
-it contains all libraries and header files required to build an application.
-
-When compiling an application in the FreeBSD* environment on the Intel® DPDK,
-the following variables must be exported:
-
-* RTE_SDK - Points to the Intel® DPDK installation directory.
+The DPDK example applications make use of the pkg-config file installed on
+the system when DPDK is installed, and so can be built using GNU make.
-* RTE_TARGET - Points to the Intel® DPDK target environment directory.
- For FreeBSD*, this is the x86_64-native-bsdapp-gcc directory.
-
-The following is an example of creating the helloworld application,
-which runs in the Intel® DPDK FreeBSD* environment.
-This example may be found in the ${RTE_SDK}/examples directory.
+.. note::
-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.
+ BSD make cannot be used to compile the DPDK example applications. GNU
+ make can be installed using `pkg install gmake` if not already installed
+ on the FreeBSD system.
-.. code-block:: console
+The following shows how to compile the helloworld example app, following
+the installation of DPDK using `ninja install` as described previously::
- user@host:~/DPDK$ cd examples/helloworld/
- user@host:~/DPDK/examples/helloworld$ setenv RTE_SDK $HOME/DPDK
- user@host:~/DPDK/examples/helloworld$ setenv RTE_TARGET x86_64-native-bsdapp-gcc
- user@host:~/DPDK/examples/helloworld$ gmake CC=gcc48
- CC main.o
- LD helloworld
- INSTALL-APP helloworld
- INSTALL-MAP helloworld.map
- user@host:~/DPDK/examples/helloworld$ ls build/app
- helloworld helloworld.map
+ $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
-.. note::
+ $ cd examples/helloworld/
- 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.
+ $ gmake
+ cc -O3 -I/usr/local/include -include rte_config.h -march=native
+ -D__BSD_VISIBLE main.c -o build/helloworld-shared
+ -L/usr/local/lib -lrte_telemetry -lrte_bpf -lrte_flow_classify
+ -lrte_pipeline -lrte_table -lrte_port -lrte_fib -lrte_ipsec
+ -lrte_stack -lrte_security -lrte_sched -lrte_reorder -lrte_rib
+ -lrte_rcu -lrte_rawdev -lrte_pdump -lrte_member -lrte_lpm
+ -lrte_latencystats -lrte_jobstats -lrte_ip_frag -lrte_gso -lrte_gro
+ -lrte_eventdev -lrte_efd -lrte_distributor -lrte_cryptodev
+ -lrte_compressdev -lrte_cfgfile -lrte_bitratestats -lrte_bbdev
+ -lrte_acl -lrte_timer -lrte_hash -lrte_metrics -lrte_cmdline
+ -lrte_pci -lrte_ethdev -lrte_meter -lrte_net -lrte_mbuf
+ -lrte_mempool -lrte_ring -lrte_eal -lrte_kvargs
+ ln -sf helloworld-shared build/helloworld
-.. code-block:: console
- user@host:~$ setenv RTE_SDK /home/user/DPDK
- user@host:~$ cp -r $(RTE_SDK)/examples/helloworld my_rte_app
- user@host:~$ cd my_rte_app/
- user@host:~$ setenv RTE_TARGET x86_64-native-bsdapp-gcc
- user@host:~/my_rte_app$ gmake CC=gcc48
- CC main.o
- LD helloworld
- INSTALL-APP helloworld
- INSTALL-MAP helloworld.map
+.. _running_sample_app:
Running a Sample Application
----------------------------
-#. The contigmem and nic_uio modules must be set up prior to running an application.
-
-#. Any ports to be used by the application must be already bound to the nic_uio module,
- as described in section Section 3.6, “ , ” prior to running the application.
- The application is linked with the Intel® DPDK target environment's Environment Abstraction Layer (EAL) library,
- which provides some options that are generic to every Intel® DPDK application.
-
-The following is the list of options that can be given to the EAL:
+#. The ``contigmem`` and ``nic_uio`` modules must be set up prior to running an application.
-.. code-block:: console
+#. Any ports to be used by the application must be already bound to the ``nic_uio`` module,
+ as described in section :ref:`binding_network_ports`, prior to running the application.
+ The application is linked with the DPDK target environment's Environment
+ Abstraction Layer (EAL) library, which provides some options that are generic
+ to every DPDK application.
- ./rte-app -c COREMASK -n NUM [-b <domain:bus:devid.func>] [-m MB] [-r NUM] [-v] [--file-prefix] [--proc-type <primary|secondary|auto>]
-
-.. note::
+A large number of options can be given to the EAL when running an
+application. A full list of options can be got by passing `--help` to a
+DPDK application. Some of the EAL options for FreeBSD are as follows:
- EAL has a common interface between all operating systems and is based on the Linux* notation for PCI devices.
- The device and function separator used is a ":" rather than "." as seen with pciconf on FreeBSD*.
- For example, a FreeBSD* device selector of pci0:2:0:1 is referred to as 02:00.1 in EAL.
+* ``-c COREMASK`` or ``-l CORELIST``:
+ A hexadecimal bit mask of the cores to run on. Note that core numbering
+ can change between platforms and should be determined beforehand. The corelist
+ is a list of cores to use instead of a core mask.
-The EAL options for FreeBSD* are as follows:
+* ``-b <domain:bus:devid.func>``:
+ Blacklisting of ports; prevent EAL from using specified PCI device
+ (multiple ``-b`` options are allowed).
-* -c COREMASK
- : A hexadecimal bit mask of the cores to run on.
- Note that core numbering can change between platforms and should be determined beforehand.
+* ``--use-device``:
+ Use the specified Ethernet device(s) only. Use comma-separate
+ ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option.
-* -n NUM
- : Number of memory channels per processor socket.
+* ``-v``:
+ Display version information on startup.
-* -b <domain:bus:devid.func>
- : blacklisting of ports; prevent EAL from using specified PCI device (multiple -b options are allowed).
+* ``-m MB``:
+ Memory to allocate from hugepages, regardless of processor socket.
-* --use-device
- : use the specified ethernet device(s) only.
- Use comma-separate <[domain:]bus:devid.func> values. Cannot be used with -b option.
+Other options, specific to Linux and are not supported under FreeBSD are as follows:
-* -r NUM
- : Number of memory ranks.
+* ``socket-mem``:
+ Memory to allocate from hugepages on specific sockets.
-* -v
- : Display version information on startup.
+* ``--huge-dir``:
+ The directory where hugetlbfs is mounted.
-* --proc-type
- : The type of process instance.
+* ``mbuf-pool-ops-name``:
+ Pool ops name for mbuf to use.
-Other options, specific to Linux* and are not supported under FreeBSD* are as follows:
+* ``--file-prefix``:
+ The prefix text used for hugepage filenames.
-* socket-mem
- : Memory to allocate from hugepages on specific sockets.
-
-* --huge-dir
- : The directory where hugetlbfs is mounted.
-
-* --file-prefix
- : The prefix text used for hugepage filenames.
-
-* -m MB
- : Memory to allocate from hugepages, regardless of processor socket.
- It is recommended that --socket-mem be used instead of this option.
-
-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 (assuming the platform has four memory channels,
-and that cores 0-3 are present and are to be used for running the application):
-
-.. code-block:: console
-
- root@target:~$ ./helloworld -c f -n 4
-
-.. note::
+The ``-c`` or ``-l`` option is mandatory; the others are optional.
- 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.
+.. _running_non_root:
-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 file system objects should be adjusted to ensure
-that the 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 file system objects should be adjusted to ensure
+that the user account being used to run the DPDK application has access
+to them:
-* The userspace-io device files in /dev, for example, /dev/uio0, /dev/uio1, and so on
+* The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on
-* The userspace contiguous memory device: /dev/contigmem
+* The userspace contiguous memory device: ``/dev/contigmem``
.. note::
- Please refer to the Intel® DPDK Release Notes for supported applications.
+ Please refer to the DPDK Release Notes for supported applications.
git.droids-corp.org / dpdk.git / blobdiff