]>
Commit | Line | Data |
---|---|---|
9f95a23c TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright(c) 2010-2014 Intel Corporation. | |
7c673cae FG |
3 | |
4 | Compiling and Running Sample Applications | |
5 | ========================================= | |
6 | ||
7 | The chapter describes how to compile and run applications in an DPDK environment. | |
8 | It also provides a pointer to where sample applications are stored. | |
9 | ||
10 | .. note:: | |
11 | ||
12 | Parts of this process can also be done using the setup script described the | |
13 | :ref:`linux_setup_script` section of this document. | |
14 | ||
15 | Compiling a Sample Application | |
16 | ------------------------------ | |
17 | ||
9f95a23c | 18 | Once an DPDK target environment directory has been created (such as ``x86_64-native-linux-gcc``), |
7c673cae FG |
19 | it contains all libraries and header files required to build an application. |
20 | ||
21 | When compiling an application in the Linux* environment on the DPDK, the following variables must be exported: | |
22 | ||
23 | * ``RTE_SDK`` - Points to the DPDK installation directory. | |
24 | ||
25 | * ``RTE_TARGET`` - Points to the DPDK target environment directory. | |
26 | ||
27 | The following is an example of creating the ``helloworld`` application, which runs in the DPDK Linux environment. | |
28 | This example may be found in the ``${RTE_SDK}/examples`` directory. | |
29 | ||
30 | The directory contains the ``main.c`` file. This file, when combined with the libraries in the DPDK target environment, | |
31 | calls the various functions to initialize the DPDK environment, | |
32 | then launches an entry point (dispatch application) for each core to be utilized. | |
33 | By default, the binary is generated in the build directory. | |
34 | ||
35 | .. code-block:: console | |
36 | ||
37 | cd examples/helloworld/ | |
38 | export RTE_SDK=$HOME/DPDK | |
9f95a23c | 39 | export RTE_TARGET=x86_64-native-linux-gcc |
7c673cae FG |
40 | |
41 | make | |
42 | CC main.o | |
43 | LD helloworld | |
44 | INSTALL-APP helloworld | |
45 | INSTALL-MAP helloworld.map | |
46 | ||
47 | ls build/app | |
48 | helloworld helloworld.map | |
49 | ||
50 | .. note:: | |
51 | ||
52 | In the above example, ``helloworld`` was in the directory structure of the DPDK. | |
53 | However, it could have been located outside the directory structure to keep the DPDK structure intact. | |
54 | In the following case, the ``helloworld`` application is copied to a new directory as a new starting point. | |
55 | ||
56 | .. code-block:: console | |
57 | ||
58 | export RTE_SDK=/home/user/DPDK | |
59 | cp -r $(RTE_SDK)/examples/helloworld my_rte_app | |
60 | cd my_rte_app/ | |
9f95a23c | 61 | export RTE_TARGET=x86_64-native-linux-gcc |
7c673cae FG |
62 | |
63 | make | |
64 | CC main.o | |
65 | LD helloworld | |
66 | INSTALL-APP helloworld | |
67 | INSTALL-MAP helloworld.map | |
68 | ||
69 | Running a Sample Application | |
70 | ---------------------------- | |
71 | ||
72 | .. warning:: | |
73 | ||
9f95a23c | 74 | Before running the application make sure: |
7c673cae | 75 | |
9f95a23c TL |
76 | - Hugepages setup is done. |
77 | - Any kernel driver being used is loaded. | |
78 | - In case needed, ports being used by the application should be | |
79 | bound to the corresponding kernel driver. | |
7c673cae | 80 | |
9f95a23c | 81 | refer to :ref:`linux_gsg_linux_drivers` for more details. |
7c673cae FG |
82 | |
83 | The application is linked with the DPDK target environment's Environmental Abstraction Layer (EAL) library, | |
84 | which provides some options that are generic to every DPDK application. | |
85 | ||
86 | The following is the list of options that can be given to the EAL: | |
87 | ||
88 | .. code-block:: console | |
89 | ||
11fdf7f2 TL |
90 | ./rte-app [-c COREMASK | -l CORELIST] [-n NUM] [-b <domain:bus:devid.func>] \ |
91 | [--socket-mem=MB,...] [-d LIB.so|DIR] [-m MB] [-r NUM] [-v] [--file-prefix] \ | |
9f95a23c | 92 | [--proc-type <primary|secondary|auto>] |
7c673cae FG |
93 | |
94 | The EAL options are as follows: | |
95 | ||
11fdf7f2 | 96 | * ``-c COREMASK`` or ``-l CORELIST``: |
7c673cae | 97 | An hexadecimal bit mask of the cores to run on. Note that core numbering can |
11fdf7f2 TL |
98 | change between platforms and should be determined beforehand. The corelist is |
99 | a set of core numbers instead of a bitmap core mask. | |
7c673cae FG |
100 | |
101 | * ``-n NUM``: | |
102 | Number of memory channels per processor socket. | |
103 | ||
104 | * ``-b <domain:bus:devid.func>``: | |
105 | Blacklisting of ports; prevent EAL from using specified PCI device | |
106 | (multiple ``-b`` options are allowed). | |
107 | ||
108 | * ``--use-device``: | |
109 | use the specified Ethernet device(s) only. Use comma-separate | |
110 | ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option. | |
111 | ||
112 | * ``--socket-mem``: | |
9f95a23c TL |
113 | Memory to allocate from hugepages on specific sockets. In dynamic memory mode, |
114 | this memory will also be pinned (i.e. not released back to the system until | |
115 | application closes). | |
116 | ||
117 | * ``--socket-limit``: | |
118 | Limit maximum memory available for allocation on each socket. Does not support | |
119 | legacy memory mode. | |
7c673cae | 120 | |
11fdf7f2 TL |
121 | * ``-d``: |
122 | Add a driver or driver directory to be loaded. | |
123 | The application should use this option to load the pmd drivers | |
124 | that are built as shared libraries. | |
125 | ||
7c673cae FG |
126 | * ``-m MB``: |
127 | Memory to allocate from hugepages, regardless of processor socket. It is | |
128 | recommended that ``--socket-mem`` be used instead of this option. | |
129 | ||
130 | * ``-r NUM``: | |
131 | Number of memory ranks. | |
132 | ||
133 | * ``-v``: | |
134 | Display version information on startup. | |
135 | ||
136 | * ``--huge-dir``: | |
137 | The directory where hugetlbfs is mounted. | |
138 | ||
9f95a23c TL |
139 | * ``mbuf-pool-ops-name``: |
140 | Pool ops name for mbuf to use. | |
141 | ||
7c673cae FG |
142 | * ``--file-prefix``: |
143 | The prefix text used for hugepage filenames. | |
144 | ||
145 | * ``--proc-type``: | |
146 | The type of process instance. | |
147 | ||
7c673cae FG |
148 | * ``--vmware-tsc-map``: |
149 | Use VMware TSC map instead of native RDTSC. | |
150 | ||
151 | * ``--base-virtaddr``: | |
152 | Specify base virtual address. | |
153 | ||
154 | * ``--vfio-intr``: | |
155 | Specify interrupt type to be used by VFIO (has no effect if VFIO is not used). | |
156 | ||
9f95a23c TL |
157 | * ``--legacy-mem``: |
158 | Run DPDK in legacy memory mode (disable memory reserve/unreserve at runtime, | |
159 | but provide more IOVA-contiguous memory). | |
160 | ||
161 | * ``--single-file-segments``: | |
162 | Store memory segments in fewer files (dynamic memory mode only - does not | |
163 | affect legacy memory mode). | |
164 | ||
11fdf7f2 | 165 | The ``-c`` or ``-l`` and option is mandatory; the others are optional. |
7c673cae FG |
166 | |
167 | Copy the DPDK application binary to your target, then run the application as follows | |
168 | (assuming the platform has four memory channels per processor socket, | |
169 | and that cores 0-3 are present and are to be used for running the application):: | |
170 | ||
11fdf7f2 | 171 | ./helloworld -l 0-3 -n 4 |
7c673cae FG |
172 | |
173 | .. note:: | |
174 | ||
175 | The ``--proc-type`` and ``--file-prefix`` EAL options are used for running | |
176 | multiple DPDK processes. See the "Multi-process Sample Application" | |
177 | chapter in the *DPDK Sample Applications User Guide* and the *DPDK | |
178 | Programmers Guide* for more details. | |
179 | ||
180 | Logical Core Use by Applications | |
181 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
182 | ||
11fdf7f2 TL |
183 | The coremask (-c 0x0f) or corelist (-l 0-3) parameter is always mandatory for DPDK applications. |
184 | Each bit of the mask corresponds to the equivalent logical core number as reported by Linux. The preferred corelist option is a cleaner method to define cores to be used. | |
7c673cae | 185 | Since these logical core numbers, and their mapping to specific cores on specific NUMA sockets, can vary from platform to platform, |
11fdf7f2 | 186 | it is recommended that the core layout for each platform be considered when choosing the coremask/corelist to use in each case. |
7c673cae FG |
187 | |
188 | On initialization of the EAL layer by an DPDK application, the logical cores to be used and their socket location are displayed. | |
189 | 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``. | |
190 | The physical id attribute listed for each processor indicates the CPU socket to which it belongs. | |
191 | This can be useful when using other processors to understand the mapping of the logical cores to the sockets. | |
192 | ||
193 | .. note:: | |
194 | ||
195 | A more graphical view of the logical core layout may be obtained using the ``lstopo`` Linux utility. | |
196 | On Fedora Linux, this may be installed and run using the following command:: | |
197 | ||
198 | sudo yum install hwloc | |
199 | ./lstopo | |
200 | ||
201 | .. warning:: | |
202 | ||
11fdf7f2 | 203 | The logical core layout can change between different board layouts and should be checked before selecting an application coremask/corelist. |
7c673cae FG |
204 | |
205 | Hugepage Memory Use by Applications | |
206 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
207 | ||
208 | When running an application, it is recommended to use the same amount of memory as that allocated for hugepages. | |
209 | This is done automatically by the DPDK application at startup, | |
210 | if no ``-m`` or ``--socket-mem`` parameter is passed to it when run. | |
211 | ||
212 | If more memory is requested by explicitly passing a ``-m`` or ``--socket-mem`` value, the application fails. | |
213 | 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. | |
214 | The reason is as follows. | |
215 | Suppose the system has 1024 reserved 2 MB pages in socket 0 and 1024 in socket 1. | |
216 | If the user requests 128 MB of memory, the 64 pages may not match the constraints: | |
217 | ||
218 | * The hugepage memory by be given to the application by the kernel in socket 1 only. | |
219 | In this case, if the application attempts to create an object, such as a ring or memory pool in socket 0, it fails. | |
220 | To avoid this issue, it is recommended that the ``--socket-mem`` option be used instead of the ``-m`` option. | |
221 | ||
222 | * These pages can be located anywhere in physical memory, and, although the DPDK EAL will attempt to allocate memory in contiguous blocks, | |
223 | it is possible that the pages will not be contiguous. In this case, the application is not able to allocate big memory pools. | |
224 | ||
225 | The socket-mem option can be used to request specific amounts of memory for specific sockets. | |
226 | This is accomplished by supplying the ``--socket-mem`` flag followed by amounts of memory requested on each socket, | |
227 | for example, supply ``--socket-mem=0,512`` to try and reserve 512 MB for socket 1 only. | |
228 | 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. | |
229 | No memory will be reserved on any CPU socket that is not explicitly referenced, for example, socket 3 in this case. | |
230 | If the DPDK cannot allocate enough memory on each socket, the EAL initialization fails. | |
231 | ||
232 | Additional Sample Applications | |
233 | ------------------------------ | |
234 | ||
235 | Additional sample applications are included in the ${RTE_SDK}/examples directory. | |
236 | These sample applications may be built and run in a manner similar to that described in earlier sections in this manual. | |
237 | In addition, see the *DPDK Sample Applications User Guide* for a description of the application, | |
238 | specific instructions on compilation and execution and some explanation of the code. | |
239 | ||
240 | Additional Test Applications | |
241 | ---------------------------- | |
242 | ||
243 | In addition, there are two other applications that are built when the libraries are created. | |
244 | The source files for these are in the DPDK/app directory and are called test and testpmd. | |
245 | Once the libraries are created, they can be found in the build/app directory. | |
246 | ||
247 | * The test application provides a variety of specific tests for the various functions in the DPDK. | |
248 | ||
249 | * The testpmd application provides a number of different packet throughput tests and | |
250 | examples of features such as how to use the Flow Director found in the Intel® 82599 10 Gigabit Ethernet Controller. |