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 The ethdev layer supports below build options for debug purpose:
  30
  31 - ``RTE_ETHDEV_DEBUG_RX`` (default **disabled**)
  32
  33   Build with debug code on Rx path.
  34
  35 - ``RTE_ETHDEV_DEBUG_TX`` (default **disabled**)
  36
  37   Build with debug code on Tx path.
  38
  39 .. Note::
  40
  41    The ethdev library use above options to wrap debug code to trace invalid parameters
  42    on data path APIs, so performance downgrade is expected when enabling those options.
  43    Each PMD can decide to reuse them to wrap their own debug code in the Rx/Tx path.
  44
  45 Running testpmd in Linux
  46 ------------------------
  47
  48 This section demonstrates how to setup and run ``testpmd`` in Linux.
  49
  50 #. Mount huge pages:
  51
  52    .. code-block:: console
  53
  54       mkdir /mnt/huge
  55       mount -t hugetlbfs nodev /mnt/huge
  56
  57 #. Request huge pages:
  58
  59    Hugepage memory should be reserved as per application requirement. Check
  60    hugepage size configured in the system and calculate the number of pages
  61    required.
  62
  63    To reserve 1024 pages of 2MB:
  64
  65    .. code-block:: console
  66
  67       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
  68
  69    .. note::
  70
  71       Check ``/proc/meminfo`` to find system hugepage size:
  72
  73       .. code-block:: console
  74
  75          grep "Hugepagesize:" /proc/meminfo
  76
  77       Example output:
  78
  79       .. code-block:: console
  80
  81          Hugepagesize:       2048 kB
  82
  83    Mount and request above can be achieved simply with this tool:
  84
  85    .. code-block:: console
  86
  87       dpdk-hugepages.py --setup 2G
  88
  89 #. Load ``igb_uio`` or ``vfio-pci`` driver:
  90
  91    .. code-block:: console
  92
  93       modprobe uio
  94       insmod igb_uio.ko
  95
  96    or
  97
  98    .. code-block:: console
  99
 100       modprobe vfio-pci
 101
 102 #. Setup VFIO permissions for regular users before binding to ``vfio-pci``:
 103
 104    .. code-block:: console
 105
 106       sudo chmod a+x /dev/vfio
 107
 108       sudo chmod 0666 /dev/vfio/*
 109
 110 #. Bind the adapters to ``igb_uio`` or ``vfio-pci`` loaded in the previous step:
 111
 112    .. code-block:: console
 113
 114       ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ...
 115
 116    Or setup VFIO permissions for regular users and then bind to ``vfio-pci``:
 117
 118    .. code-block:: console
 119
 120       ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ...
 121
 122    .. note::
 123
 124       DEVICE1, DEVICE2 are specified via PCI "domain:bus:slot.func" syntax or
 125       "bus:slot.func" syntax.
 126
 127 #. Start ``testpmd`` with basic parameters:
 128
 129    .. code-block:: console
 130
 131       ./<build_dir>/app/dpdk-testpmd -l 0-3 -n 4 -- -i
 132
 133    Successful execution will show initialization messages from EAL, PMD and
 134    testpmd application. A prompt will be displayed at the end for user commands
 135    as interactive mode (``-i``) is on.
 136
 137    .. code-block:: console
 138
 139       testpmd>
 140
 141    Refer to the :ref:`testpmd runtime functions <testpmd_runtime>` for a list
 142    of available commands.
 143
 144    .. note::
 145       When ``testpmd`` is built with shared library, use option ``-d`` to load
 146       the dynamic PMD for ``rte_eal_init``.