xref: /dpdk/doc/guides/nics/build_and_test.rst (revision 3bb3ebb51b789d4ecb417cbdb1dce5c7211f6f18) 
1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2017 Cavium, Inc
3
4.. _pmd_build_and_test:
5
6Compiling and testing a PMD for a NIC
7=====================================
8
9This section demonstrates how to compile and run a Poll Mode Driver (PMD) for
10the available Network Interface Cards in DPDK using TestPMD.
11
12TestPMD is one of the reference applications distributed with the DPDK. Its main
13purpose is to forward packets between Ethernet ports on a network interface and
14as such is the best way to test a PMD.
15
16Refer to the :ref:`testpmd application user guide <testpmd_ug>` for detailed
17information on how to build and run testpmd.
18
19Driver Compilation
20------------------
21
22To compile a PMD for a platform, build DPDK
23as described in the "Getting Started Guide" for your platform.
24This will also build testpmd.
25
26Detailed instructions are available
27in the :doc:`meson build guide <../prog_guide/build-sdk-meson>`.
28
29Running testpmd in Linux
30------------------------
31
32This 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``.
131