X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Ffreebsd_gsg%2Fbuild_sample_apps.rst;h=2a68f5fc3820d1b617bb51d699dc95238e165cc0;hb=614af75489682e39bb005d80173434588e9490a6;hp=7e8546780537d7042a41b89392a53860493bd842;hpb=dacdbfa457525ef5cabdd1db9854310da8f37a6b;p=dpdk.git diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst index 7e85467805..2a68f5fc38 100644 --- a/doc/guides/freebsd_gsg/build_sample_apps.rst +++ b/doc/guides/freebsd_gsg/build_sample_apps.rst @@ -1,185 +1,117 @@ -.. BSD LICENSE - Copyright(c) 2010-2014 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. + +.. _compiling_sample_apps: Compiling and Running Sample Applications ========================================= -The chapter describes how to compile and run applications in an Intel® DPDK environment. -It also provides a pointer to where sample applications are stored. +The chapter describes how to compile and run applications in a DPDK +environment. It also provides a pointer to where sample applications are stored. Compiling a Sample Application ------------------------------ -Once an Intel® DPDK target environment directory has been created (such as x86_64-native-bsdapp-gcc), -it contains all libraries and header files required to build an application. - -When compiling an application in the FreeBSD* environment on the Intel® DPDK, -the following variables must be exported: - -* RTE_SDK - Points to the Intel® DPDK installation directory. +The DPDK example applications make use of the pkg-config file installed on +the system when DPDK is installed, and so can be built using GNU make. -* RTE_TARGET - Points to the Intel® DPDK target environment directory. - For FreeBSD*, this is the x86_64-native-bsdapp-gcc directory. - -The following is an example of creating the helloworld application, -which runs in the Intel® DPDK FreeBSD* environment. -This example may be found in the ${RTE_SDK}/examples directory. +.. note:: -The directory contains the main.c file. -This file, when combined with the libraries in the Intel® DPDK target environment, -calls the various functions to initialize the Intel® DPDK environment, -then launches an entry point (dispatch application) for each core to be utilized. -By default, the binary is generated in the build directory. + BSD make cannot be used to compile the DPDK example applications. GNU + make can be installed using `pkg install gmake` if not already installed + on the FreeBSD system. -.. code-block:: console +The following shows how to compile the helloworld example app, following +the installation of DPDK using `ninja install` as described previously:: - user@host:~/DPDK$ cd examples/helloworld/ - user@host:~/DPDK/examples/helloworld$ setenv RTE_SDK $HOME/DPDK - user@host:~/DPDK/examples/helloworld$ setenv RTE_TARGET x86_64-native-bsdapp-gcc - user@host:~/DPDK/examples/helloworld$ gmake CC=gcc48 - CC main.o - LD helloworld - INSTALL-APP helloworld - INSTALL-MAP helloworld.map - user@host:~/DPDK/examples/helloworld$ ls build/app - helloworld helloworld.map + $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig -.. note:: + $ cd examples/helloworld/ - In the above example, helloworld was in the directory structure of the Intel® DPDK. - However, it could have been located outside the directory structure to keep the Intel® DPDK structure intact. - In the following case, the helloworld application is copied to a new directory as a new starting point. + $ gmake + cc -O3 -I/usr/local/include -include rte_config.h -march=native + -D__BSD_VISIBLE main.c -o build/helloworld-shared + -L/usr/local/lib -lrte_telemetry -lrte_bpf -lrte_flow_classify + -lrte_pipeline -lrte_table -lrte_port -lrte_fib -lrte_ipsec + -lrte_stack -lrte_security -lrte_sched -lrte_reorder -lrte_rib + -lrte_rcu -lrte_rawdev -lrte_pdump -lrte_member -lrte_lpm + -lrte_latencystats -lrte_jobstats -lrte_ip_frag -lrte_gso -lrte_gro + -lrte_eventdev -lrte_efd -lrte_distributor -lrte_cryptodev + -lrte_compressdev -lrte_cfgfile -lrte_bitratestats -lrte_bbdev + -lrte_acl -lrte_timer -lrte_hash -lrte_metrics -lrte_cmdline + -lrte_pci -lrte_ethdev -lrte_meter -lrte_net -lrte_mbuf + -lrte_mempool -lrte_ring -lrte_eal -lrte_kvargs + ln -sf helloworld-shared build/helloworld -.. code-block:: console - user@host:~$ setenv RTE_SDK /home/user/DPDK - user@host:~$ cp -r $(RTE_SDK)/examples/helloworld my_rte_app - user@host:~$ cd my_rte_app/ - user@host:~$ setenv RTE_TARGET x86_64-native-bsdapp-gcc - user@host:~/my_rte_app$ gmake CC=gcc48 - CC main.o - LD helloworld - INSTALL-APP helloworld - INSTALL-MAP helloworld.map +.. _running_sample_app: Running a Sample Application ---------------------------- -#. The contigmem and nic_uio modules must be set up prior to running an application. - -#. Any ports to be used by the application must be already bound to the nic_uio module, - as described in section Section 3.6, “ , ” prior to running the application. - The application is linked with the Intel® DPDK target environment's Environment Abstraction Layer (EAL) library, - which provides some options that are generic to every Intel® DPDK application. - -The following is the list of options that can be given to the EAL: +#. The ``contigmem`` and ``nic_uio`` modules must be set up prior to running an application. -.. code-block:: console +#. Any ports to be used by the application must be already bound to the ``nic_uio`` module, + as described in section :ref:`binding_network_ports`, prior to running the application. + The application is linked with the DPDK target environment's Environment + Abstraction Layer (EAL) library, which provides some options that are generic + to every DPDK application. - ./rte-app -c COREMASK -n NUM [-b ] [-m MB] [-r NUM] [-v] [--file-prefix] [--proc-type ] - -.. note:: +A large number of options can be given to the EAL when running an +application. A full list of options can be got by passing `--help` to a +DPDK application. Some of the EAL options for FreeBSD are as follows: - EAL has a common interface between all operating systems and is based on the Linux* notation for PCI devices. - The device and function separator used is a ":" rather than "." as seen with pciconf on FreeBSD*. - For example, a FreeBSD* device selector of pci0:2:0:1 is referred to as 02:00.1 in EAL. +* ``-c COREMASK`` or ``-l CORELIST``: + A hexadecimal bit mask of the cores to run on. Note that core numbering + can change between platforms and should be determined beforehand. The corelist + is a list of cores to use instead of a core mask. -The EAL options for FreeBSD* are as follows: +* ``-b ``: + Blacklisting of ports; prevent EAL from using specified PCI device + (multiple ``-b`` options are allowed). -* -c COREMASK - : A hexadecimal bit mask of the cores to run on. - Note that core numbering can change between platforms and should be determined beforehand. +* ``--use-device``: + Use the specified Ethernet device(s) only. Use comma-separate + ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option. -* -n NUM - : Number of memory channels per processor socket. +* ``-v``: + Display version information on startup. -* -b - : blacklisting of ports; prevent EAL from using specified PCI device (multiple -b options are allowed). +* ``-m MB``: + Memory to allocate from hugepages, regardless of processor socket. -* --use-device - : use the specified ethernet device(s) only. - Use comma-separate <[domain:]bus:devid.func> values. Cannot be used with -b option. +Other options, specific to Linux and are not supported under FreeBSD are as follows: -* -r NUM - : Number of memory ranks. +* ``socket-mem``: + Memory to allocate from hugepages on specific sockets. -* -v - : Display version information on startup. +* ``--huge-dir``: + The directory where hugetlbfs is mounted. -* --proc-type - : The type of process instance. +* ``mbuf-pool-ops-name``: + Pool ops name for mbuf to use. -Other options, specific to Linux* and are not supported under FreeBSD* are as follows: +* ``--file-prefix``: + The prefix text used for hugepage filenames. -* socket-mem - : Memory to allocate from hugepages on specific sockets. - -* --huge-dir - : The directory where hugetlbfs is mounted. - -* --file-prefix - : The prefix text used for hugepage filenames. - -* -m MB - : Memory to allocate from hugepages, regardless of processor socket. - It is recommended that --socket-mem be used instead of this option. - -The -c and the -n options are mandatory; the others are optional. - -Copy the Intel® DPDK application binary to your target, -then run the application as follows (assuming the platform has four memory channels, -and that cores 0-3 are present and are to be used for running the application): - -.. code-block:: console - - root@target:~$ ./helloworld -c f -n 4 - -.. note:: +The ``-c`` or ``-l`` option is mandatory; the others are optional. - The --proc-type and --file-prefix EAL options are used for running multiple Intel® DPDK processes. - See the “Multi-process Sample Application” chapter in the - *Intel® DPDK Sample Applications User Guide and the Intel® DPDK Programmers Guide* for more details. +.. _running_non_root: -Running Intel®DPDK Applications Without Root Privileges -------------------------------------------------------- +Running DPDK Applications Without Root Privileges +------------------------------------------------- -Although applications using the Intel® DPDK use network ports and other hardware resources directly, -with a number of small permission adjustments, -it is possible to run these applications as a user other than “root”. -To do so, the ownership, or permissions, on the following file system objects should be adjusted to ensure -that the user account being used to run the Intel® DPDK application has access to them: +Although applications using the DPDK use network ports and other hardware +resources directly, with a number of small permission adjustments, it is possible +to run these applications as a user other than "root". To do so, the ownership, +or permissions, on the following file system objects should be adjusted to ensure +that the user account being used to run the DPDK application has access +to them: -* The userspace-io device files in /dev, for example, /dev/uio0, /dev/uio1, and so on +* The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on -* The userspace contiguous memory device: /dev/contigmem +* The userspace contiguous memory device: ``/dev/contigmem`` .. note:: - Please refer to the Intel® DPDK Release Notes for supported applications. + Please refer to the DPDK Release Notes for supported applications.