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 and Running Sample Applications
  32 =========================================
  33
  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.
  36
  37 Compiling a Sample Application
  38 ------------------------------
  39
  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.
  43
  44 When compiling an application in the FreeBSD* environment on the Intel® DPDK,
  45 the following variables must be exported:
  46
  47 *   RTE_SDK - Points to the Intel® DPDK installation directory.
  48
  49 *   RTE_TARGET - Points to the Intel® DPDK target environment directory.
  50     For FreeBSD*, this is the x86_64-native-bsdapp-gcc directory.
  51
  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.
  55
  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.
  61
  62 .. code-block:: console
  63
  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
  68     CC main.o
  69     LD helloworld
  70     INSTALL-APP helloworld
  71     INSTALL-MAP helloworld.map
  72     user@host:~/DPDK/examples/helloworld$ ls build/app
  73     helloworld helloworld.map
  74
  75 .. note::
  76
  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
  81     point.
  82
  83 .. code-block:: console
  84
  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
  90     CC main.o
  91     LD helloworld
  92     INSTALL-APP helloworld
  93     INSTALL-MAP helloworld.map
  94
  95 Running a Sample Application
  96 ----------------------------
  97
  98 #.  The contigmem and nic_uio modules must be set up prior to running an application.
  99
 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.
 105
 106 The following is the list of options that can be given to the EAL:
 107
 108 .. code-block:: console
 109
 110     ./rte-app -c COREMASK -n NUM [-b <domain:bus:devid.func>] [-m MB] [-r NUM] [-v] [--file-prefix] [--proc-type <primary|secondary|auto>]
 111
 112 .. note::
 113
 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.
 118
 119 The EAL options for FreeBSD* are as follows:
 120
 121 *   -c COREMASK
 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.
 124
 125 *   -n NUM
 126     : Number of memory channels per processor socket.
 127
 128 *   -b <domain:bus:devid.func>
 129     : blacklisting of ports; prevent EAL from using specified PCI device
 130     (multiple -b options are allowed).
 131
 132 *   --use-device
 133     : use the specified ethernet device(s) only.  Use comma-separate
 134     <[domain:]bus:devid.func> values. Cannot be used with -b option.
 135
 136 *   -r NUM
 137     : Number of memory ranks.
 138
 139 *   -v
 140     : Display version information on startup.
 141
 142 *   --proc-type
 143     : The type of process instance.
 144
 145 Other options, specific to Linux* and are not supported under FreeBSD* are as follows:
 146
 147 *   socket-mem
 148     : Memory to allocate from hugepages on specific sockets.
 149
 150 *   --huge-dir
 151     : The directory where hugetlbfs is mounted.
 152
 153 *   --file-prefix
 154     : The prefix text used for hugepage filenames.
 155
 156 *   -m MB
 157     : Memory to allocate from hugepages, regardless of processor socket.
 158     It is recommended that --socket-mem be used instead of this option.
 159
 160 The -c and the -n options are mandatory; the others are optional.
 161
 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):
 165
 166 .. code-block:: console
 167
 168     root@target:~$ ./helloworld -c f -n 4
 169
 170 .. note::
 171
 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.
 176
 177 Running Intel®DPDK Applications Without Root Privileges
 178 -------------------------------------------------------
 179
 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
 185 to them:
 186
 187 *   The userspace-io device files in /dev, for example, /dev/uio0, /dev/uio1, and so on
 188
 189 *   The userspace contiguous memory device:  /dev/contigmem
 190
 191 .. note::
 192
 193     Please refer to the Intel® DPDK Release Notes for supported applications.