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 #. Load ``igb_uio`` or ``vfio-pci`` driver:
  68
  69    .. code-block:: console
  70
  71       modprobe uio
  72       insmod igb_uio.ko
  73
  74    or
  75
  76    .. code-block:: console
  77
  78       modprobe vfio-pci
  79
  80 #. Setup VFIO permissions for regular users before binding to ``vfio-pci``:
  81
  82    .. code-block:: console
  83
  84       sudo chmod a+x /dev/vfio
  85
  86       sudo chmod 0666 /dev/vfio/*
  87
  88 #. Bind the adapters to ``igb_uio`` or ``vfio-pci`` loaded in the previous step:
  89
  90    .. code-block:: console
  91
  92       ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ...
  93
  94    Or setup VFIO permissions for regular users and then bind to ``vfio-pci``:
  95
  96    .. code-block:: console
  97
  98       ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ...
  99
 100    .. note::
 101
 102       DEVICE1, DEVICE2 are specified via PCI "domain:bus:slot.func" syntax or
 103       "bus:slot.func" syntax.
 104
 105 #. Start ``testpmd`` with basic parameters:
 106
 107    .. code-block:: console
 108
 109       ./<build_dir>/app/dpdk-testpmd -l 0-3 -n 4 -- -i
 110
 111    Successful execution will show initialization messages from EAL, PMD and
 112    testpmd application. A prompt will be displayed at the end for user commands
 113    as interactive mode (``-i``) is on.
 114
 115    .. code-block:: console
 116
 117       testpmd>
 118
 119    Refer to the :ref:`testpmd runtime functions <testpmd_runtime>` for a list
 120    of available commands.
 121
 122    .. note::
 123       When ``testpmd`` is built with shared library, use option ``-d`` to load
 124       the dynamic PMD for ``rte_eal_init``.