doc: update building and running FreeBSD apps

Update the documentation on building and running apps on FreeBSD, taking
account of having used meson for building. We can also update the section
on the command-line parameters, rather than claiming to be a complete list
of parameters, it should describe how to get the complete list and only
cover a few important ones.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>

diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst
index 0c1b9cb..2a68f5f 100644 (file)
--- a/doc/guides/freebsd_gsg/build_sample_apps.rst
+++ b/doc/guides/freebsd_gsg/build_sample_apps.rst
@@ -12,68 +12,37 @@ environment. It also provides a pointer to where sample applications are stored.
 Compiling a Sample Application
 ------------------------------
 
-Once a DPDK target environment directory has been created (such as
-``x86_64-native-freebsd-clang``), it contains all libraries and header files required
-to build an application.
+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.
 
-When compiling an application in the FreeBSD environment on the DPDK,
-the following variables must be exported:
-
-*   ``RTE_SDK`` - Points to the DPDK installation directory.
-
-*   ``RTE_TARGET`` - Points to the DPDK target environment directory.
-    For FreeBSD, this is the ``x86_64-native-freebsd-clang`` or
-    ``x86_64-native-freebsd-gcc`` directory.
-
-The following is an example of creating the ``helloworld`` application, which runs
-in the DPDK FreeBSD environment. While the example demonstrates compiling
-using gcc version 4.9, compiling with clang will be similar, except that the ``CC=``
-parameter can probably be omitted. The ``helloworld`` example may be found in the
-``${RTE_SDK}/examples`` directory.
-
-The directory contains the ``main.c`` file. This file, when combined with the
-libraries in the DPDK target environment, calls the various functions to
-initialize the 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.
-
-.. code-block:: console
-
-    setenv RTE_SDK /home/user/DPDK
-    cd $(RTE_SDK)
-    cd examples/helloworld/
-    setenv RTE_SDK $HOME/DPDK
-    setenv RTE_TARGET x86_64-native-freebsd-gcc
-
-    gmake CC=gcc49
-      CC main.o
-      LD helloworld
-      INSTALL-APP helloworld
-      INSTALL-MAP helloworld.map
+.. note::
 
-    ls build/app
-      helloworld helloworld.map
+   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.
 
-.. note::
+The following shows how to compile the helloworld example app, following
+the installation of DPDK using `ninja install` as described previously::
 
-    In the above example, ``helloworld`` was in the directory structure of the
-    DPDK. However, it could have been located outside the directory
-    structure to keep the DPDK structure intact.  In the following case,
-    the ``helloworld`` application is copied to a new directory as a new starting
-    point.
+        $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
 
-.. code-block:: console
+        $ cd examples/helloworld/
 
-    setenv RTE_SDK /home/user/DPDK
-    cp -r $(RTE_SDK)/examples/helloworld my_rte_app
-    cd my_rte_app/
-    setenv RTE_TARGET x86_64-native-freebsd-gcc
+        $ 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
 
-    gmake CC=gcc49
-      CC main.o
-      LD helloworld
-      INSTALL-APP helloworld
-      INSTALL-MAP helloworld.map
 
 .. _running_sample_app:
 
@@ -88,29 +57,15 @@ Running a Sample Application
     Abstraction Layer (EAL) library, which provides some options that are generic
     to every DPDK application.
 
-The following is the list of options that can be given to the EAL:
-
-.. code-block:: console
-
-    ./rte-app -l CORELIST [-n NUM] [-b <domain:bus:devid.func>] \
-              [-r NUM] [-v] [--proc-type <primary|secondary|auto>]
-
-.. note::
-
-    EAL has a common interface between all operating systems and is based on the
-    Linux notation for PCI devices. For example, a FreeBSD device selector of
-    ``pci0:2:0:1`` is referred to as ``02:00.1`` in EAL.
-
-The EAL options for FreeBSD are as follows:
+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:
 
 *   ``-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.
 
-*   ``-n NUM``:
-    Number of memory channels per processor socket.
-
 *   ``-b <domain:bus:devid.func>``:
     Blacklisting of ports; prevent EAL from using specified PCI device
     (multiple ``-b`` options are allowed).
@@ -119,15 +74,9 @@ The EAL options for FreeBSD are as follows:
     Use the specified Ethernet device(s) only.  Use comma-separate
     ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option.
 
-*   ``-r NUM``:
-    Number of memory ranks.
-
 *   ``-v``:
     Display version information on startup.
 
-*   ``--proc-type``:
-    The type of process instance.
-
 *   ``-m MB``:
     Memory to allocate from hugepages, regardless of processor socket.
 
@@ -147,19 +96,6 @@ Other options, specific to Linux and are not supported under FreeBSD are as foll
 
 The ``-c`` or ``-l`` option is mandatory; the others are optional.
 
-Copy the 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)::
-
-    ./helloworld -l 0-3 -n 4
-
-.. note::
-
-    The ``--proc-type`` and ``--file-prefix`` EAL options are used for running multiple
-    DPDK processes.  See the "Multi-process Sample Application" chapter
-    in the *DPDK Sample Applications User Guide and the DPDK
-    Programmers Guide* for more details.
-
 .. _running_non_root:
 
 Running DPDK Applications Without Root Privileges