doc/guides/freebsd_gsg/build_sample_apps.rst

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