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