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.9, 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     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
 107 Running 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
 118 The following is the list of options that can be given to the EAL:
 119
 120 .. code-block:: console
 121
 122     ./rte-app -l CORELIST [-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
 131 The EAL options for FreeBSD are as follows:
 132
 133 *   ``-c COREMASK`` or ``-l CORELIST``:
 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. The corelist
 136     is a list of cores to use instead of a core mask.
 137
 138 *   ``-n NUM``:
 139     Number of memory channels per processor socket.
 140
 141 *   ``-b <domain:bus:devid.func>``:
 142     Blacklisting of ports; prevent EAL from using specified PCI device
 143     (multiple ``-b`` options are allowed).
 144
 145 *   ``--use-device``:
 146     Use the specified Ethernet device(s) only.  Use comma-separate
 147     ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option.
 148
 149 *   ``-r NUM``:
 150     Number of memory ranks.
 151
 152 *   ``-v``:
 153     Display version information on startup.
 154
 155 *   ``--proc-type``:
 156     The type of process instance.
 157
 158 Other options, specific to Linux and are not supported under FreeBSD are as follows:
 159
 160 *   ``socket-mem``:
 161     Memory to allocate from hugepages on specific sockets.
 162
 163 *   ``--huge-dir``:
 164     The directory where hugetlbfs is mounted.
 165
 166 *   ``--file-prefix``:
 167     The prefix text used for hugepage filenames.
 168
 169 *   ``-m MB``:
 170     Memory to allocate from hugepages, regardless of processor socket.
 171     It is recommended that ``--socket-mem`` be used instead of this option.
 172
 173 The ``-c`` or ``-l`` option is mandatory; the others are optional.
 174
 175 Copy the DPDK application binary to your target, then run the application
 176 as follows (assuming the platform has four memory channels, and that cores 0-3
 177 are present and are to be used for running the application)::
 178
 179     ./helloworld -l 0-3 -n 4
 180
 181 .. note::
 182
 183     The ``--proc-type`` and ``--file-prefix`` EAL options are used for running multiple
 184     DPDK processes.  See the "Multi-process Sample Application" chapter
 185     in the *DPDK Sample Applications User Guide and the DPDK
 186     Programmers Guide* for more details.
 187
 188 .. _running_non_root:
 189
 190 Running DPDK Applications Without Root Privileges
 191 -------------------------------------------------
 192
 193 Although applications using the DPDK use network ports and other hardware
 194 resources directly, with a number of small permission adjustments, it is possible
 195 to run these applications as a user other than "root".  To do so, the ownership,
 196 or permissions, on the following file system objects should be adjusted to ensure
 197 that the user account being used to run the DPDK application has access
 198 to them:
 199
 200 *   The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on
 201
 202 *   The userspace contiguous memory device: ``/dev/contigmem``
 203
 204 .. note::
 205
 206     Please refer to the DPDK Release Notes for supported applications.