[dpdk-dev] [PATCH 5/5] doc: update documentation on build and running FreeBSD apps

[Bruce Richardson <bruce.richardson@intel.com>]

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>
---
 doc/guides/freebsd_gsg/build_sample_apps.rst | 118 +++++--------------
 1 file changed, 27 insertions(+), 91 deletions(-)

diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst
index 0c1b9cb79..2a68f5fc3 100644
--- 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
-- 
2.24.1