doc/guides/nics/build_and_test.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Cavium, Inc
   3
   4 .. _pmd_build_and_test:
   5
   6 Compiling and testing a PMD for a NIC
   7 =====================================
   8
   9 This section demonstrates how to compile and run a Poll Mode Driver (PMD) for
  10 the available Network Interface Cards in DPDK using TestPMD.
  11
  12 TestPMD is one of the reference applications distributed with the DPDK. Its main
  13 purpose is to forward packets between Ethernet ports on a network interface and
  14 as such is the best way to test a PMD.
  15
  16 Refer to the :ref:`testpmd application user guide <testpmd_ug>` for detailed
  17 information on how to build and run testpmd.
  18
  19 Driver Compilation
  20 ------------------
  21
  22 To compile a PMD for a platform, run make with appropriate target as shown below.
  23 Use "make" command in Linux and "gmake" in FreeBSD. This will also build testpmd.
  24
  25 To check available targets:
  26
  27 .. code-block:: console
  28
  29    cd <DPDK-source-directory>
  30    make showconfigs
  31
  32 Example output:
  33
  34 .. code-block:: console
  35
  36    arm-armv7a-linuxapp-gcc
  37    arm64-armv8a-linuxapp-gcc
  38    arm64-dpaa2-linuxapp-gcc
  39    arm64-thunderx-linuxapp-gcc
  40    arm64-xgene1-linuxapp-gcc
  41    i686-native-linuxapp-gcc
  42    i686-native-linuxapp-icc
  43    ppc_64-power8-linuxapp-gcc
  44    x86_64-native-bsdapp-clang
  45    x86_64-native-bsdapp-gcc
  46    x86_64-native-linuxapp-clang
  47    x86_64-native-linuxapp-gcc
  48    x86_64-native-linuxapp-icc
  49    x86_x32-native-linuxapp-gcc
  50
  51 To compile a PMD for Linux x86_64 gcc target, run the following "make" command:
  52
  53 .. code-block:: console
  54
  55    make install T=x86_64-native-linuxapp-gcc
  56
  57 Use ARM (ThunderX, DPAA, X-Gene) or PowerPC target for respective platform.
  58
  59 For more information, refer to the :ref:`Getting Started Guide for Linux <linux_gsg>`
  60 or :ref:`Getting Started Guide for FreeBSD <freebsd_gsg>` depending on your platform.
  61
  62 Running testpmd in Linux
  63 ------------------------
  64
  65 This section demonstrates how to setup and run ``testpmd`` in Linux.
  66
  67 #. Mount huge pages:
  68
  69    .. code-block:: console
  70
  71       mkdir /mnt/huge
  72       mount -t hugetlbfs nodev /mnt/huge
  73
  74 #. Request huge pages:
  75
  76    Hugepage memory should be reserved as per application requirement. Check
  77    hugepage size configured in the system and calculate the number of pages
  78    required.
  79
  80    To reserve 1024 pages of 2MB:
  81
  82    .. code-block:: console
  83
  84       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
  85
  86    .. note::
  87
  88       Check ``/proc/meminfo`` to find system hugepage size:
  89
  90       .. code-block:: console
  91
  92          grep "Hugepagesize:" /proc/meminfo
  93
  94       Example output:
  95
  96       .. code-block:: console
  97
  98          Hugepagesize:       2048 kB
  99
 100 #. Load ``igb_uio`` or ``vfio-pci`` driver:
 101
 102    .. code-block:: console
 103
 104       modprobe uio
 105       insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 106
 107    or
 108
 109    .. code-block:: console
 110
 111       modprobe vfio-pci
 112
 113 #. Setup VFIO permissions for regular users before binding to ``vfio-pci``:
 114
 115    .. code-block:: console
 116
 117       sudo chmod a+x /dev/vfio
 118
 119       sudo chmod 0666 /dev/vfio/*
 120
 121 #. Bind the adapters to ``igb_uio`` or ``vfio-pci`` loaded in the previous step:
 122
 123    .. code-block:: console
 124
 125       ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ...
 126
 127    Or setup VFIO permissions for regular users and then bind to ``vfio-pci``:
 128
 129    .. code-block:: console
 130
 131       ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ...
 132
 133    .. note::
 134
 135       DEVICE1, DEVICE2 are specified via PCI "domain:bus:slot.func" syntax or
 136       "bus:slot.func" syntax.
 137
 138 #. Start ``testpmd`` with basic parameters:
 139
 140    .. code-block:: console
 141
 142       ./x86_64-native-linuxapp-gcc/app/testpmd -l 0-3 -n 4 -- -i
 143
 144    Successful execution will show initialization messages from EAL, PMD and
 145    testpmd application. A prompt will be displayed at the end for user commands
 146    as interactive mode (``-i``) is on.
 147
 148    .. code-block:: console
 149
 150       testpmd>
 151
 152    Refer to the :ref:`testpmd runtime functions <testpmd_runtime>` for a list
 153    of available commands.
 154
 155    .. note::
 156       When ``testpmd`` is built with shared library, use option ``-d`` to load
 157       the dynamic PMD for ``rte_eal_init``.