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.. 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 45Running testpmd in Linux 46------------------------ 47 48This 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``. 147