2 Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
9 * Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
11 * Redistributions in binary form must reproduce the above copyright
12 notice, this list of conditions and the following disclaimer in
13 the documentation and/or other materials provided with the
15 * Neither the name of Intel Corporation nor the names of its
16 contributors may be used to endorse or promote products derived
17 from this software without specific prior written permission.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 Compiling and Running Sample Applications
32 =========================================
34 The chapter describes how to compile and run applications in an Intel® DPDK
35 environment. It also provides a pointer to where sample applications are stored.
37 Compiling a Sample Application
38 ------------------------------
40 Once an Intel® DPDK target environment directory has been created (such as
41 x86_64-native-bsdapp-gcc), it contains all libraries and header files required
42 to build an application.
44 When compiling an application in the FreeBSD* environment on the Intel® DPDK,
45 the following variables must be exported:
47 * RTE_SDK - Points to the Intel® DPDK installation directory.
49 * RTE_TARGET - Points to the Intel® DPDK target environment directory.
50 For FreeBSD*, this is the x86_64-native-bsdapp-gcc directory.
52 The following is an example of creating the helloworld application, which runs
53 in the Intel® DPDK FreeBSD* environment. This example may be found in the
54 ${RTE_SDK}/examples directory.
56 The directory contains the main.c file. This file, when combined with the
57 libraries in the Intel® DPDK target environment, calls the various functions to
58 initialize the Intel® DPDK environment, then launches an entry point (dispatch
59 application) for each core to be utilized. By default, the binary is generated
60 in the build directory.
62 .. code-block:: console
64 user@host:~/DPDK$ cd examples/helloworld/
65 user@host:~/DPDK/examples/helloworld$ setenv RTE_SDK $HOME/DPDK
66 user@host:~/DPDK/examples/helloworld$ setenv RTE_TARGET x86_64-native-bsdapp-gcc
67 user@host:~/DPDK/examples/helloworld$ gmake CC=gcc48
70 INSTALL-APP helloworld
71 INSTALL-MAP helloworld.map
72 user@host:~/DPDK/examples/helloworld$ ls build/app
73 helloworld helloworld.map
77 In the above example, helloworld was in the directory structure of the
78 Intel® DPDK. However, it could have been located outside the directory
79 structure to keep the Intel® DPDK structure intact. In the following case,
80 the helloworld application is copied to a new directory as a new starting
83 .. code-block:: console
85 user@host:~$ setenv RTE_SDK /home/user/DPDK
86 user@host:~$ cp -r $(RTE_SDK)/examples/helloworld my_rte_app
87 user@host:~$ cd my_rte_app/
88 user@host:~$ setenv RTE_TARGET x86_64-native-bsdapp-gcc
89 user@host:~/my_rte_app$ gmake CC=gcc48
92 INSTALL-APP helloworld
93 INSTALL-MAP helloworld.map
95 Running a Sample Application
96 ----------------------------
98 #. The contigmem and nic_uio modules must be set up prior to running an application.
100 #. Any ports to be used by the application must be already bound to the nic_uio module,
101 as described in section Section 3.6, “ , ” prior to running the application.
102 The application is linked with the Intel® DPDK target environment's Environment
103 Abstraction Layer (EAL) library, which provides some options that are generic
104 to every Intel® DPDK application.
106 The following is the list of options that can be given to the EAL:
108 .. code-block:: console
110 ./rte-app -c COREMASK -n NUM [-b <domain:bus:devid.func>] [-m MB] [-r NUM] [-v] [--file-prefix] [--proc-type <primary|secondary|auto>]
114 EAL has a common interface between all operating systems and is based on the
115 Linux* notation for PCI devices. The device and function separator used is
116 a ":" rather than "." as seen with pciconf on FreeBSD*. For example, a
117 FreeBSD* device selector of pci0:2:0:1 is referred to as 02:00.1 in EAL.
119 The EAL options for FreeBSD* are as follows:
122 : A hexadecimal bit mask of the cores to run on. Note that core numbering
123 can change between platforms and should be determined beforehand.
126 : Number of memory channels per processor socket.
128 * -b <domain:bus:devid.func>
129 : blacklisting of ports; prevent EAL from using specified PCI device
130 (multiple -b options are allowed).
133 : use the specified ethernet device(s) only. Use comma-separate
134 <[domain:]bus:devid.func> values. Cannot be used with -b option.
137 : Number of memory ranks.
140 : Display version information on startup.
143 : The type of process instance.
145 Other options, specific to Linux* and are not supported under FreeBSD* are as follows:
148 : Memory to allocate from hugepages on specific sockets.
151 : The directory where hugetlbfs is mounted.
154 : The prefix text used for hugepage filenames.
157 : Memory to allocate from hugepages, regardless of processor socket.
158 It is recommended that --socket-mem be used instead of this option.
160 The -c and the -n options are mandatory; the others are optional.
162 Copy the Intel® DPDK application binary to your target, then run the application
163 as follows (assuming the platform has four memory channels, and that cores 0-3
164 are present and are to be used for running the application):
166 .. code-block:: console
168 root@target:~$ ./helloworld -c f -n 4
172 The --proc-type and --file-prefix EAL options are used for running multiple
173 Intel® DPDK processes. See the “Multi-process Sample Application” chapter
174 in the *Intel® DPDK Sample Applications User Guide and the Intel® DPDK
175 Programmers Guide* for more details.
177 Running Intel®DPDK Applications Without Root Privileges
178 -------------------------------------------------------
180 Although applications using the Intel® DPDK use network ports and other hardware
181 resources directly, with a number of small permission adjustments, it is possible
182 to run these applications as a user other than “root”. To do so, the ownership,
183 or permissions, on the following file system objects should be adjusted to ensure
184 that the user account being used to run the Intel® DPDK application has access
187 * The userspace-io device files in /dev, for example, /dev/uio0, /dev/uio1, and so on
189 * The userspace contiguous memory device: /dev/contigmem
193 Please refer to the Intel® DPDK Release Notes for supported applications.