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