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 The DPDK example applications make use of the pkg-config file installed on
  16 the system when DPDK is installed, and so can be built using GNU make.
  17
  18 .. note::
  19
  20    BSD make cannot be used to compile the DPDK example applications. GNU
  21    make can be installed using `pkg install gmake` if not already installed
  22    on the FreeBSD system.
  23
  24 The following shows how to compile the helloworld example app, following
  25 the installation of DPDK using `ninja install` as described previously::
  26
  27         $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
  28
  29         $ cd examples/helloworld/
  30
  31         $ gmake
  32         cc -O3 -I/usr/local/include -include rte_config.h -march=native
  33         -D__BSD_VISIBLE  main.c -o build/helloworld-shared
  34         -L/usr/local/lib -lrte_telemetry -lrte_bpf -lrte_flow_classify
  35         -lrte_pipeline -lrte_table -lrte_port -lrte_fib -lrte_ipsec
  36         -lrte_stack -lrte_security -lrte_sched -lrte_reorder -lrte_rib
  37         -lrte_rcu -lrte_rawdev -lrte_pdump -lrte_member -lrte_lpm
  38         -lrte_latencystats -lrte_jobstats -lrte_ip_frag -lrte_gso -lrte_gro
  39         -lrte_eventdev -lrte_efd -lrte_distributor -lrte_cryptodev
  40         -lrte_compressdev -lrte_cfgfile -lrte_bitratestats -lrte_bbdev
  41         -lrte_acl -lrte_timer -lrte_hash -lrte_metrics -lrte_cmdline
  42         -lrte_pci -lrte_ethdev -lrte_meter -lrte_net -lrte_mbuf
  43         -lrte_mempool -lrte_ring -lrte_eal -lrte_kvargs
  44         ln -sf helloworld-shared build/helloworld
  45
  46
  47 .. _running_sample_app:
  48
  49 Running a Sample Application
  50 ----------------------------
  51
  52 #.  The ``contigmem`` and ``nic_uio`` modules must be set up prior to running an application.
  53
  54 #.  Any ports to be used by the application must be already bound to the ``nic_uio`` module,
  55     as described in section :ref:`binding_network_ports`, prior to running the application.
  56     The application is linked with the DPDK target environment's Environment
  57     Abstraction Layer (EAL) library, which provides some options that are generic
  58     to every DPDK application.
  59
  60 A large number of options can be given to the EAL when running an
  61 application. A full list of options can be got by passing `--help` to a
  62 DPDK application. Some of the EAL options for FreeBSD are as follows:
  63
  64 *   ``-c COREMASK`` or ``-l CORELIST``:
  65     A hexadecimal bit mask of the cores to run on.  Note that core numbering
  66     can change between platforms and should be determined beforehand. The corelist
  67     is a list of cores to use instead of a core mask.
  68
  69 *   ``-b <domain:bus:devid.func>``:
  70     Blacklisting of ports; prevent EAL from using specified PCI device
  71     (multiple ``-b`` options are allowed).
  72
  73 *   ``--use-device``:
  74     Use the specified Ethernet device(s) only.  Use comma-separate
  75     ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option.
  76
  77 *   ``-v``:
  78     Display version information on startup.
  79
  80 *   ``-m MB``:
  81     Memory to allocate from hugepages, regardless of processor socket.
  82
  83 Other options, specific to Linux and are not supported under FreeBSD are as follows:
  84
  85 *   ``socket-mem``:
  86     Memory to allocate from hugepages on specific sockets.
  87
  88 *   ``--huge-dir``:
  89     The directory where hugetlbfs is mounted.
  90
  91 *   ``mbuf-pool-ops-name``:
  92     Pool ops name for mbuf to use.
  93
  94 *   ``--file-prefix``:
  95     The prefix text used for hugepage filenames.
  96
  97 The ``-c`` or ``-l`` option is mandatory; the others are optional.
  98
  99 .. _running_non_root:
 100
 101 Running DPDK Applications Without Root Privileges
 102 -------------------------------------------------
 103
 104 Although applications using the DPDK use network ports and other hardware
 105 resources directly, with a number of small permission adjustments, it is possible
 106 to run these applications as a user other than "root".  To do so, the ownership,
 107 or permissions, on the following file system objects should be adjusted to ensure
 108 that the user account being used to run the DPDK application has access
 109 to them:
 110
 111 *   The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on
 112
 113 *   The userspace contiguous memory device: ``/dev/contigmem``
 114
 115 .. note::
 116
 117     Please refer to the DPDK Release Notes for supported applications.