xref: /dpdk/doc/guides/nics/build_and_test.rst (revision 8809f78c7dd9f33a44a4f89c58fc91ded34296ed) 
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#. 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``.
125