1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2017 Cavium, Inc
4 .. _pmd_build_and_test:
6 Compiling and testing a PMD for a NIC
7 =====================================
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.
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.
16 Refer to the :ref:`testpmd application user guide <testpmd_ug>` for detailed
17 information on how to build and run testpmd.
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.
26 Detailed instructions are available
27 in the :doc:`meson build guide <../prog_guide/build-sdk-meson>`.
29 The ethdev layer supports below build options for debug purpose:
31 - ``RTE_ETHDEV_DEBUG_RX`` (default **disabled**)
33 Build with debug code on Rx path.
35 - ``RTE_ETHDEV_DEBUG_TX`` (default **disabled**)
37 Build with debug code on Tx path.
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.
45 Running testpmd in Linux
46 ------------------------
48 This section demonstrates how to setup and run ``testpmd`` in Linux.
52 .. code-block:: console
55 mount -t hugetlbfs nodev /mnt/huge
57 #. Request huge pages:
59 Hugepage memory should be reserved as per application requirement. Check
60 hugepage size configured in the system and calculate the number of pages
63 To reserve 1024 pages of 2MB:
65 .. code-block:: console
67 echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
71 Check ``/proc/meminfo`` to find system hugepage size:
73 .. code-block:: console
75 grep "Hugepagesize:" /proc/meminfo
79 .. code-block:: console
83 Mount and request above can be achieved simply with this tool:
85 .. code-block:: console
87 dpdk-hugepages.py --setup 2G
89 #. Load ``igb_uio`` or ``vfio-pci`` driver:
91 .. code-block:: console
98 .. code-block:: console
102 #. Setup VFIO permissions for regular users before binding to ``vfio-pci``:
104 .. code-block:: console
106 sudo chmod a+x /dev/vfio
108 sudo chmod 0666 /dev/vfio/*
110 #. Bind the adapters to ``igb_uio`` or ``vfio-pci`` loaded in the previous step:
112 .. code-block:: console
114 ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ...
116 Or setup VFIO permissions for regular users and then bind to ``vfio-pci``:
118 .. code-block:: console
120 ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ...
124 DEVICE1, DEVICE2 are specified via PCI "domain:bus:slot.func" syntax or
125 "bus:slot.func" syntax.
127 #. Start ``testpmd`` with basic parameters:
129 .. code-block:: console
131 ./<build_dir>/app/dpdk-testpmd -l 0-3 -n 4 -- -i
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.
137 .. code-block:: console
141 Refer to the :ref:`testpmd runtime functions <testpmd_runtime>` for a list
142 of available commands.
145 When ``testpmd`` is built with shared library, use option ``-d`` to load
146 the dynamic PMD for ``rte_eal_init``.