doc: add installing from FreeBSD package
authorBruce Richardson <bruce.richardson@intel.com>
Fri, 3 Jan 2020 15:32:53 +0000 (15:32 +0000)
committerThomas Monjalon <thomas@monjalon.net>
Sun, 16 Feb 2020 10:10:51 +0000 (11:10 +0100)
Update the FreeBSD GSG to cover installing from the pre-built package as
well as installing from a port.

Also, since the port is now based on meson, update the instructions for
compiling and running the example applications.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
doc/guides/freebsd_gsg/install_from_ports.rst

index 29f16cc..36dc4a4 100644 (file)
@@ -7,29 +7,31 @@ Installing DPDK from the Ports Collection
 =========================================
 
 The easiest way to get up and running with the DPDK on FreeBSD is to
-install it from the ports collection. Details of getting and using the ports
-collection are documented in the
-`FreeBSD Handbook <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html>`_.
+install it using the FreeBSD `pkg` utility or from the ports collection.
+Details of installing applications from packages or the ports collection are documented in the
+`FreeBSD Handbook <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html>`_,
+chapter `Installing Applications: Packages and Ports <https://www.freebsd.org/doc/handbook/ports.html>`_.
 
-Installing the DPDK FreeBSD Port
---------------------------------
+.. note::
 
-On a system with the ports collection installed in ``/usr/ports``, the DPDK
-can be installed using the commands:
+   Please ensure that the latest patches are applied to third party libraries
+   and software to avoid any known vulnerabilities.
 
-.. code-block:: console
 
-    cd /usr/ports/net/dpdk
+Installing the DPDK Package for FreeBSD
+---------------------------------------
 
-    make install
+DPDK can be installed on FreeBSD using the command::
+
+       pkg install dpdk
 
-After the installation of the DPDK port, instructions will be printed on
+After the installation of the DPDK package, instructions will be printed on
 how to install the kernel modules required to use the DPDK. A more
 complete version of these instructions can be found in the sections
 :ref:`loading_contigmem` and :ref:`loading_nic_uio`. Normally, lines like
 those below would be added to the file ``/boot/loader.conf``.
 
-.. code-block:: console
+.. code-block:: shell
 
     # Reserve 2 x 1G blocks of contiguous memory using contigmem driver:
     hw.contigmem.num_buffers=2
@@ -40,24 +42,32 @@ those below would be added to the file ``/boot/loader.conf``.
     hw.nic_uio.bdfs="2:0:0,2:0:1"
     nic_uio_load="YES"
 
-.. note::
 
-   Please ensure that the latest patches are applied to third party libraries
-   and software to avoid any known vulnerabilities.
+Installing the DPDK FreeBSD Port
+--------------------------------
+
+If so desired, the user can install DPDK using the ports collection rather than from
+a pre-compiled binary package.
+On a system with the ports collection installed in ``/usr/ports``, the DPDK
+can be installed using the commands::
+
+    cd /usr/ports/net/dpdk
+
+    make install
 
 
 Compiling and Running the Example Applications
 ----------------------------------------------
 
 When the DPDK has been installed from the ports collection it installs
-its example applications in ``/usr/local/share/dpdk/examples`` - also accessible via
-symlink as ``/usr/local/share/examples/dpdk``. These examples can be compiled and
-run as described in :ref:`compiling_sample_apps`. In this case, the required
-environmental variables should be set as below:
+its example applications in ``/usr/local/share/dpdk/examples``.
+These examples can be compiled and run as described in :ref:`compiling_sample_apps`.
 
-* ``RTE_SDK=/usr/local/share/dpdk``
+.. note::
 
-* ``RTE_TARGET=x86_64-native-freebsd-clang``
+   DPDK example applications must be complied using `gmake` rather than
+   BSD `make`. To detect the installed DPDK libraries, `pkg-config` should
+   also be installed on the system.
 
 .. note::
 
@@ -66,25 +76,18 @@ environmental variables should be set as below:
    the instructions given in the next chapter, :ref:`building_from_source`
 
 An example application can therefore be copied to a user's home directory and
-compiled and run as below:
-
-.. code-block:: console
-
-    export RTE_SDK=/usr/local/share/dpdk
-
-    export RTE_TARGET=x86_64-native-freebsd-clang
+compiled and run as below, where we have 2 memory blocks of size 1G reserved
+via the contigmem module, and 4 NIC ports bound to the nic_uio module::
 
     cp -r /usr/local/share/dpdk/examples/helloworld .
 
     cd helloworld/
 
     gmake
-      CC main.o
-      LD helloworld
-      INSTALL-APP helloworld
-      INSTALL-MAP helloworld.map
+    cc -O3 -I/usr/local/include -include rte_config.h -march=corei7 -D__BSD_VISIBLE  main.c -o build/helloworld-shared  -L/usr/local/lib -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
 
-    sudo ./build//helloworld -l 0-3
+    sudo ./build/helloworld -l 0-3
     EAL: Sysctl reports 8 cpus
     EAL: Detected 8 lcore(s)
     EAL: Detected 1 NUMA nodes
@@ -98,16 +101,12 @@ compiled and run as below:
     EAL:   0000:00:19.0 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.0 on NUMA socket 0
     EAL:   probe driver: 8086:1572 net_i40e
-    EAL:   0000:01:00.0 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.1 on NUMA socket 0
     EAL:   probe driver: 8086:1572 net_i40e
-    EAL:   0000:01:00.1 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.2 on NUMA socket 0
     EAL:   probe driver: 8086:1572 net_i40e
-    EAL:   0000:01:00.2 not managed by UIO driver, skipping
     EAL: PCI device 0000:01:00.3 on NUMA socket 0
     EAL:   probe driver: 8086:1572 net_i40e
-    EAL:   0000:01:00.3 not managed by UIO driver, skipping
     hello from core 1
     hello from core 2
     hello from core 3