a89055f58240b9ac5acb678bb72bb585c26fce58
[dpdk.git] / doc / guides / freebsd_gsg / build_sample_apps.rst
1 ..  BSD LICENSE
2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
3     All rights reserved.
4
5     Redistribution and use in source and binary forms, with or without
6     modification, are permitted provided that the following conditions
7     are met:
8
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
14     distribution.
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.
18
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.
30
31 .. _compiling_sample_apps:
32
33 Compiling and Running Sample Applications
34 =========================================
35
36 The chapter describes how to compile and run applications in a DPDK
37 environment. It also provides a pointer to where sample applications are stored.
38
39 Compiling a Sample Application
40 ------------------------------
41
42 Once a DPDK target environment directory has been created (such as
43 x86_64-native-bsdapp-clang), it contains all libraries and header files required
44 to build an application.
45
46 When compiling an application in the FreeBSD* environment on the DPDK,
47 the following variables must be exported:
48
49 *   RTE_SDK - Points to the DPDK installation directory.
50
51 *   RTE_TARGET - Points to the DPDK target environment directory.
52     For FreeBSD*, this is the x86_64-native-bsdapp-clang or
53     x86_64-native-bsdapp-gcc directory.
54
55 The following is an example of creating the helloworld application, which runs
56 in the DPDK FreeBSD* environment. While the example demonstrates compiling
57 using gcc version 4.8, compiling with clang will be similar, except that the "CC="
58 parameter can probably be omitted. The "helloworld" example may be found in the
59 ${RTE_SDK}/examples directory.
60
61 The directory contains the main.c file.  This file, when combined with the
62 libraries in the DPDK target environment, calls the various functions to
63 initialize the DPDK environment, then launches an entry point (dispatch
64 application) for each core to be utilized.  By default, the binary is generated
65 in the build directory.
66
67 .. code-block:: console
68
69     user@host:~/DPDK$ cd examples/helloworld/
70     user@host:~/DPDK/examples/helloworld$ setenv RTE_SDK $HOME/DPDK
71     user@host:~/DPDK/examples/helloworld$ setenv RTE_TARGET x86_64-native-bsdapp-gcc
72     user@host:~/DPDK/examples/helloworld$ gmake CC=gcc48
73     CC main.o
74     LD helloworld
75     INSTALL-APP helloworld
76     INSTALL-MAP helloworld.map
77     user@host:~/DPDK/examples/helloworld$ ls build/app
78     helloworld helloworld.map
79
80 .. note::
81
82     In the above example, helloworld was in the directory structure of the
83     DPDK.  However, it could have been located outside the directory
84     structure to keep the DPDK structure intact.  In the following case,
85     the helloworld application is copied to a new directory as a new starting
86     point.
87
88 .. code-block:: console
89
90     user@host:~$ setenv RTE_SDK /home/user/DPDK
91     user@host:~$ cp -r $(RTE_SDK)/examples/helloworld my_rte_app
92     user@host:~$ cd my_rte_app/
93     user@host:~$ setenv RTE_TARGET x86_64-native-bsdapp-gcc
94     user@host:~/my_rte_app$ gmake CC=gcc48
95     CC main.o
96     LD helloworld
97     INSTALL-APP helloworld
98     INSTALL-MAP helloworld.map
99
100 .. _running_sample_app:
101
102 Running a Sample Application
103 ----------------------------
104
105 #.  The contigmem and nic_uio modules must be set up prior to running an application.
106
107 #.  Any ports to be used by the application must be already bound to the nic_uio module,
108     as described in section :ref:`binding_network_ports`, prior to running the application.
109     The application is linked with the DPDK target environment's Environment
110     Abstraction Layer (EAL) library, which provides some options that are generic
111     to every DPDK application.
112
113 The following is the list of options that can be given to the EAL:
114
115 .. code-block:: console
116
117     ./rte-app -n NUM [-c COREMASK] [-b <domain:bus:devid.func>] [-r NUM] [-v] [--proc-type <primary|secondary|auto>]
118
119 .. note::
120
121     EAL has a common interface between all operating systems and is based on the
122     Linux* notation for PCI devices. For example, a FreeBSD* device selector of
123     pci0:2:0:1 is referred to as 02:00.1 in EAL.
124
125 The EAL options for FreeBSD* are as follows:
126
127 *   -c COREMASK
128     : A hexadecimal bit mask of the cores to run on.  Note that core numbering
129     can change between platforms and should be determined beforehand.
130
131 *   -n NUM
132     : Number of memory channels per processor socket.
133
134 *   -b <domain:bus:devid.func>
135     : blacklisting of ports; prevent EAL from using specified PCI device
136     (multiple -b options are allowed).
137
138 *   --use-device
139     : use the specified Ethernet device(s) only.  Use comma-separate
140     <[domain:]bus:devid.func> values. Cannot be used with -b option.
141
142 *   -r NUM
143     : Number of memory ranks.
144
145 *   -v
146     : Display version information on startup.
147
148 *   --proc-type
149     : The type of process instance.
150
151 Other options, specific to Linux* and are not supported under FreeBSD* are as follows:
152
153 *   socket-mem
154     : Memory to allocate from hugepages on specific sockets.
155
156 *   --huge-dir
157     : The directory where hugetlbfs is mounted.
158
159 *   --file-prefix
160     : The prefix text used for hugepage filenames.
161
162 *   -m MB
163     : Memory to allocate from hugepages, regardless of processor socket.
164     It is recommended that --socket-mem be used instead of this option.
165
166 The -c and the -n options are mandatory; the others are optional.
167
168 Copy the DPDK application binary to your target, then run the application
169 as follows (assuming the platform has four memory channels, and that cores 0-3
170 are present and are to be used for running the application):
171
172 .. code-block:: console
173
174     root@target:~$ ./helloworld -c f -n 4
175
176 .. note::
177
178     The --proc-type and --file-prefix EAL options are used for running multiple
179     DPDK processes.  See the “Multi-process Sample Application” chapter
180     in the *DPDK Sample Applications User Guide and the DPDK
181     Programmers Guide* for more details.
182
183 .. _running_non_root:
184
185 Running DPDK Applications Without Root Privileges
186 -------------------------------------------------
187
188 Although applications using the DPDK use network ports and other hardware
189 resources directly, with a number of small permission adjustments, it is possible
190 to run these applications as a user other than “root”.  To do so, the ownership,
191 or permissions, on the following file system objects should be adjusted to ensure
192 that the user account being used to run the DPDK application has access
193 to them:
194
195 *   The userspace-io device files in /dev, for example, /dev/uio0, /dev/uio1, and so on
196
197 *   The userspace contiguous memory device:  /dev/contigmem
198
199 .. note::
200
201     Please refer to the DPDK Release Notes for supported applications.