-.. 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 a Sample Application
------------------------------
-Once a DPDK target environment directory has been created (such as
-``x86_64-native-bsdapp-clang``), it contains all libraries and header files required
-to build an application.
+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.
-When compiling an application in the FreeBSD 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.
- For FreeBSD, this is the ``x86_64-native-bsdapp-clang`` or
- ``x86_64-native-bsdapp-gcc`` directory.
-
-The following is an example of creating the ``helloworld`` application, which runs
-in the DPDK FreeBSD environment. While the example demonstrates compiling
-using gcc version 4.8, compiling with clang will be similar, except that the ``CC=``
-parameter can probably be omitted. The ``helloworld`` 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
-
- setenv RTE_SDK /home/user/DPDK
- cd $(RTE_SDK)
- cd examples/helloworld/
- setenv RTE_SDK $HOME/DPDK
- setenv RTE_TARGET x86_64-native-bsdapp-gcc
-
- gmake CC=gcc48
- CC main.o
- LD helloworld
- INSTALL-APP helloworld
- INSTALL-MAP helloworld.map
+.. note::
- ls build/app
- helloworld helloworld.map
+ 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.
-.. note::
+The following shows how to compile the helloworld example app, following
+the installation of DPDK using `ninja install` as described previously::
- 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.
+ $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
-.. code-block:: console
+ $ cd examples/helloworld/
- setenv RTE_SDK /home/user/DPDK
- cp -r $(RTE_SDK)/examples/helloworld my_rte_app
- cd my_rte_app/
- setenv RTE_TARGET x86_64-native-bsdapp-gcc
+ $ 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
- gmake CC=gcc48
- CC main.o
- LD helloworld
- INSTALL-APP helloworld
- INSTALL-MAP helloworld.map
.. _running_sample_app:
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 -n NUM [-c COREMASK] [-b <domain:bus:devid.func>] \
- [-r NUM] [-v] [--proc-type <primary|secondary|auto>]
-
-.. note::
-
- EAL has a common interface between all operating systems and is based on the
- Linux notation for PCI devices. For example, a FreeBSD device selector of
- ``pci0:2:0:1`` is referred to as ``02:00.1`` in EAL.
+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:
-The EAL options for FreeBSD are as follows:
-
-* ``-c COREMASK``:
+* ``-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.
-
-* ``-n NUM``:
- Number of memory channels per processor socket.
+ can change between platforms and should be determined beforehand. The corelist
+ is a list of cores to use instead of a core mask.
* ``-b <domain:bus:devid.func>``:
- Blacklisting of ports; prevent EAL from using specified PCI device
+ Blocklisting 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.
-* ``-r NUM``:
- Number of memory ranks.
-
* ``-v``:
Display version information on startup.
-* ``--proc-type``:
- The type of process instance.
+* ``-m MB``:
+ Memory to allocate from hugepages, regardless of processor socket.
Other options, specific to Linux and are not supported under FreeBSD are as follows:
* ``--huge-dir``:
The directory where hugetlbfs is mounted.
+* ``mbuf-pool-ops-name``:
+ Pool ops name for mbuf to use.
+
* ``--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`` 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, 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.
+The ``-c`` or ``-l`` option is mandatory; the others are optional.
.. _running_non_root: