doc/guides/freebsd_gsg/install_from_ports.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2014 Intel Corporation.
   3
   4 .. _install_from_ports:
   5
   6 Installing DPDK from the Ports Collection
   7 =========================================
   8
   9 The easiest way to get up and running with the DPDK on FreeBSD is to
  10 install it using the FreeBSD `pkg` utility or from the ports collection.
  11 Details of installing applications from packages or the ports collection are documented in the
  12 `FreeBSD Handbook <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html>`_,
  13 chapter `Installing Applications: Packages and Ports <https://www.freebsd.org/doc/handbook/ports.html>`_.
  14
  15 .. note::
  16
  17    Please ensure that the latest patches are applied to third party libraries
  18    and software to avoid any known vulnerabilities.
  19
  20
  21 Installing the DPDK Package for FreeBSD
  22 ---------------------------------------
  23
  24 DPDK can be installed on FreeBSD using the command::
  25
  26         pkg install dpdk
  27
  28 After the installation of the DPDK package, instructions will be printed on
  29 how to install the kernel modules required to use the DPDK. A more
  30 complete version of these instructions can be found in the sections
  31 :ref:`loading_contigmem` and :ref:`loading_nic_uio`. Normally, lines like
  32 those below would be added to the file ``/boot/loader.conf``.
  33
  34 .. code-block:: shell
  35
  36     # Reserve 2 x 1G blocks of contiguous memory using contigmem driver:
  37     hw.contigmem.num_buffers=2
  38     hw.contigmem.buffer_size=1073741824
  39     contigmem_load="YES"
  40
  41     # Identify NIC devices for DPDK apps to use and load nic_uio driver:
  42     hw.nic_uio.bdfs="2:0:0,2:0:1"
  43     nic_uio_load="YES"
  44
  45
  46 Installing the DPDK FreeBSD Port
  47 --------------------------------
  48
  49 If so desired, the user can install DPDK using the ports collection rather than from
  50 a pre-compiled binary package.
  51 On a system with the ports collection installed in ``/usr/ports``, the DPDK
  52 can be installed using the commands::
  53
  54     cd /usr/ports/net/dpdk
  55
  56     make install
  57
  58
  59 Compiling and Running the Example Applications
  60 ----------------------------------------------
  61
  62 When the DPDK has been installed from the ports collection it installs
  63 its example applications in ``/usr/local/share/dpdk/examples``.
  64 These examples can be compiled and run as described in :ref:`compiling_sample_apps`.
  65
  66 .. note::
  67
  68    DPDK example applications must be complied using `gmake` rather than
  69    BSD `make`. To detect the installed DPDK libraries, `pkg-config` should
  70    also be installed on the system.
  71
  72 .. note::
  73
  74    To install a copy of the DPDK compiled using gcc, please download the
  75    official DPDK package from https://core.dpdk.org/download/ and install manually using
  76    the instructions given in the next chapter, :ref:`building_from_source`
  77
  78 An example application can therefore be copied to a user's home directory and
  79 compiled and run as below, where we have 2 memory blocks of size 1G reserved
  80 via the contigmem module, and 4 NIC ports bound to the nic_uio module::
  81
  82     cp -r /usr/local/share/dpdk/examples/helloworld .
  83
  84     cd helloworld/
  85
  86     gmake
  87     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
  88     ln -sf helloworld-shared build/helloworld
  89
  90     sudo ./build/helloworld -l 0-3
  91     EAL: Sysctl reports 8 cpus
  92     EAL: Detected 8 lcore(s)
  93     EAL: Detected 1 NUMA nodes
  94     EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
  95     EAL: Selected IOVA mode 'PA'
  96     EAL: Contigmem driver has 2 buffers, each of size 1GB
  97     EAL: Mapped memory segment 0 @ 0x1040000000: physaddr:0x180000000, len 1073741824
  98     EAL: Mapped memory segment 1 @ 0x1080000000: physaddr:0x1c0000000, len 1073741824
  99     EAL: PCI device 0000:00:19.0 on NUMA socket 0
 100     EAL:   probe driver: 8086:153b net_e1000_em
 101     EAL:   0000:00:19.0 not managed by UIO driver, skipping
 102     EAL: PCI device 0000:01:00.0 on NUMA socket 0
 103     EAL:   probe driver: 8086:1572 net_i40e
 104     EAL: PCI device 0000:01:00.1 on NUMA socket 0
 105     EAL:   probe driver: 8086:1572 net_i40e
 106     EAL: PCI device 0000:01:00.2 on NUMA socket 0
 107     EAL:   probe driver: 8086:1572 net_i40e
 108     EAL: PCI device 0000:01:00.3 on NUMA socket 0
 109     EAL:   probe driver: 8086:1572 net_i40e
 110     hello from core 1
 111     hello from core 2
 112     hello from core 3
 113     hello from core 0
 114
 115
 116 .. note::
 117
 118    To run a DPDK process as a non-root user, adjust the permissions on
 119    the ``/dev/contigmem`` and ``/dev/uio device`` nodes as described in section
 120    :ref:`running_non_root`
 121
 122 .. note::
 123
 124    For an explanation of the command-line parameters that can be passed to an
 125    DPDK application, see section :ref:`running_sample_app`.