1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4.. _compiling_sample_apps: 5 6Compiling and Running Sample Applications 7========================================= 8 9The chapter describes how to compile and run applications in a DPDK 10environment. It also provides a pointer to where sample applications are stored. 11 12Compiling a Sample Application 13------------------------------ 14 15The DPDK example applications make use of the pkg-config file installed on 16the 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 24The following shows how to compile the helloworld example app, following 25the installation of DPDK using `meson 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 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 49Running 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 60A large number of options can be given to the EAL when running an 61application. A full list of options can be got by passing `--help` to a 62DPDK 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 Blocklisting 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 83Other 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 97The ``-c`` or ``-l`` option is mandatory; the others are optional. 98 99.. _running_non_root: 100 101Running DPDK Applications Without Root Privileges 102------------------------------------------------- 103 104Although applications using the DPDK use network ports and other hardware 105resources directly, with a number of small permission adjustments, it is possible 106to run these applications as a user other than "root". To do so, the ownership, 107or permissions, on the following file system objects should be adjusted to ensure 108that the user account being used to run the DPDK application has access 109to 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. 118