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, build DPDK
  23 as described in the "Getting Started Guide" for your platform.
  24 This will also build testpmd.
  25
  26 Detailed instructions are available
  27 in the :doc:`meson build guide <../prog_guide/build-sdk-meson>`.
  28
  29 Running testpmd in Linux
  30 ------------------------
  31
  32 This section demonstrates how to setup and run ``testpmd`` in Linux.
  33
  34 #. Mount huge pages:
  35
  36    .. code-block:: console
  37
  38       mkdir /mnt/huge
  39       mount -t hugetlbfs nodev /mnt/huge
  40
  41 #. Request huge pages:
  42
  43    Hugepage memory should be reserved as per application requirement. Check
  44    hugepage size configured in the system and calculate the number of pages
  45    required.
  46
  47    To reserve 1024 pages of 2MB:
  48
  49    .. code-block:: console
  50
  51       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
  52
  53    .. note::
  54
  55       Check ``/proc/meminfo`` to find system hugepage size:
  56
  57       .. code-block:: console
  58
  59          grep "Hugepagesize:" /proc/meminfo
  60
  61       Example output:
  62
  63       .. code-block:: console
  64
  65          Hugepagesize:       2048 kB
  66
  67    Mount and request above can be achieved simply with this tool:
  68
  69    .. code-block:: console
  70
  71       dpdk-hugepages.py --setup 2G
  72
  73 #. Load ``igb_uio`` or ``vfio-pci`` driver:
  74
  75    .. code-block:: console
  76
  77       modprobe uio
  78       insmod igb_uio.ko
  79
  80    or
  81
  82    .. code-block:: console
  83
  84       modprobe vfio-pci
  85
  86 #. Setup VFIO permissions for regular users before binding to ``vfio-pci``:
  87
  88    .. code-block:: console
  89
  90       sudo chmod a+x /dev/vfio
  91
  92       sudo chmod 0666 /dev/vfio/*
  93
  94 #. Bind the adapters to ``igb_uio`` or ``vfio-pci`` loaded in the previous step:
  95
  96    .. code-block:: console
  97
  98       ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ...
  99
 100    Or setup VFIO permissions for regular users and then bind to ``vfio-pci``:
 101
 102    .. code-block:: console
 103
 104       ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ...
 105
 106    .. note::
 107
 108       DEVICE1, DEVICE2 are specified via PCI "domain:bus:slot.func" syntax or
 109       "bus:slot.func" syntax.
 110
 111 #. Start ``testpmd`` with basic parameters:
 112
 113    .. code-block:: console
 114
 115       ./<build_dir>/app/dpdk-testpmd -l 0-3 -n 4 -- -i
 116
 117    Successful execution will show initialization messages from EAL, PMD and
 118    testpmd application. A prompt will be displayed at the end for user commands
 119    as interactive mode (``-i``) is on.
 120
 121    .. code-block:: console
 122
 123       testpmd>
 124
 125    Refer to the :ref:`testpmd runtime functions <testpmd_runtime>` for a list
 126    of available commands.
 127
 128    .. note::
 129       When ``testpmd`` is built with shared library, use option ``-d`` to load
 130       the dynamic PMD for ``rte_eal_init``.