1.. BSD LICENSE 2 Copyright(c) 2017 Cavium, Inc. 3 4 Redistribution and use in source and binary forms, with or without 5 modification, are permitted provided that the following conditions 6 are met: 7 8 * Redistributions of source code must retain the above copyright 9 notice, this list of conditions and the following disclaimer. 10 * Redistributions in binary form must reproduce the above copyright 11 notice, this list of conditions and the following disclaimer in 12 the documentation and/or other materials provided with the 13 distribution. 14 * Neither the name of Cavium, Inc. nor the names of its 15 contributors may be used to endorse or promote products derived 16 from this software without specific prior written permission. 17 18 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 OWNER(S) OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30.. _pmd_build_and_test: 31 32Compiling and testing a PMD for a NIC 33===================================== 34 35This section demonstrates how to compile and run a Poll Mode Driver (PMD) for 36the available Network Interface Cards in DPDK using TestPMD. 37 38TestPMD is one of the reference applications distributed with the DPDK. Its main 39purpose is to forward packets between Ethernet ports on a network interface and 40as such is the best way to test a PMD. 41 42Refer to the :ref:`testpmd application user guide <testpmd_ug>` for detailed 43information on how to build and run testpmd. 44 45Driver Compilation 46------------------ 47 48To compile a PMD for a platform, run make with appropriate target as shown below. 49Use "make" command in Linux and "gmake" in FreeBSD. This will also build testpmd. 50 51To check available targets: 52 53.. code-block:: console 54 55 cd <DPDK-source-directory> 56 make showconfigs 57 58Example output: 59 60.. code-block:: console 61 62 arm-armv7a-linuxapp-gcc 63 arm64-armv8a-linuxapp-gcc 64 arm64-dpaa2-linuxapp-gcc 65 arm64-thunderx-linuxapp-gcc 66 arm64-xgene1-linuxapp-gcc 67 i686-native-linuxapp-gcc 68 i686-native-linuxapp-icc 69 ppc_64-power8-linuxapp-gcc 70 x86_64-native-bsdapp-clang 71 x86_64-native-bsdapp-gcc 72 x86_64-native-linuxapp-clang 73 x86_64-native-linuxapp-gcc 74 x86_64-native-linuxapp-icc 75 x86_x32-native-linuxapp-gcc 76 77To compile a PMD for Linux x86_64 gcc target, run the following "make" command: 78 79.. code-block:: console 80 81 make install T=x86_64-native-linuxapp-gcc 82 83Use ARM (ThunderX, DPAA, X-Gene) or PowerPC target for respective platform. 84 85For more information, refer to the :ref:`Getting Started Guide for Linux <linux_gsg>` 86or :ref:`Getting Started Guide for FreeBSD <freebsd_gsg>` depending on your platform. 87 88Running testpmd in Linux 89------------------------ 90 91This section demonstrates how to setup and run ``testpmd`` in Linux. 92 93#. Mount huge pages: 94 95 .. code-block:: console 96 97 mkdir /mnt/huge 98 mount -t hugetlbfs nodev /mnt/huge 99 100#. Request huge pages: 101 102 Hugepage memory should be reserved as per application requirement. Check 103 hugepage size configured in the system and calculate the number of pages 104 required. 105 106 To reserve 1024 pages of 2MB: 107 108 .. code-block:: console 109 110 echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages 111 112 .. note:: 113 114 Check ``/proc/meminfo`` to find system hugepage size: 115 116 .. code-block:: console 117 118 grep "Hugepagesize:" /proc/meminfo 119 120 Example output: 121 122 .. code-block:: console 123 124 Hugepagesize: 2048 kB 125 126#. Load ``igb_uio`` or ``vfio-pci`` driver: 127 128 .. code-block:: console 129 130 modprobe uio 131 insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko 132 133 or 134 135 .. code-block:: console 136 137 modprobe vfio-pci 138 139#. Setup VFIO permissions for regular users before binding to ``vfio-pci``: 140 141 .. code-block:: console 142 143 sudo chmod a+x /dev/vfio 144 145 sudo chmod 0666 /dev/vfio/* 146 147#. Bind the adapters to ``igb_uio`` or ``vfio-pci`` loaded in the previous step: 148 149 .. code-block:: console 150 151 ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ... 152 153 Or setup VFIO permissions for regular users and then bind to ``vfio-pci``: 154 155 .. code-block:: console 156 157 ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ... 158 159 .. note:: 160 161 DEVICE1, DEVICE2 are specified via PCI "domain:bus:slot.func" syntax or 162 "bus:slot.func" syntax. 163 164#. Start ``testpmd`` with basic parameters: 165 166 .. code-block:: console 167 168 ./x86_64-native-linuxapp-gcc/app/testpmd -l 0-3 -n 4 -- -i 169 170 Successful execution will show initialization messages from EAL, PMD and 171 testpmd application. A prompt will be displayed at the end for user commands 172 as interactive mode (``-i``) is on. 173 174 .. code-block:: console 175 176 testpmd> 177 178 Refer to the :ref:`testpmd runtime functions <testpmd_runtime>` for a list 179 of available commands. 180