2 Copyright(c) 2017 Cavium, Inc.
4 Redistribution and use in source and binary forms, with or without
5 modification, are permitted provided that the following conditions
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
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.
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.
30 .. _pmd_build_and_test:
32 Compiling and testing a PMD for a NIC
33 =====================================
35 This section demonstrates how to compile and run a Poll Mode Driver (PMD) for
36 the available Network Interface Cards in DPDK using TestPMD.
38 TestPMD is one of the reference applications distributed with the DPDK. Its main
39 purpose is to forward packets between Ethernet ports on a network interface and
40 as such is the best way to test a PMD.
42 Refer to the :ref:`testpmd application user guide <testpmd_ug>` for detailed
43 information on how to build and run testpmd.
48 To compile a PMD for a platform, run make with appropriate target as shown below.
49 Use "make" command in Linux and "gmake" in FreeBSD. This will also build testpmd.
51 To check available targets:
53 .. code-block:: console
55 cd <DPDK-source-directory>
60 .. code-block:: console
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
77 To compile a PMD for Linux x86_64 gcc target, run the following "make" command:
79 .. code-block:: console
81 make install T=x86_64-native-linuxapp-gcc
83 Use ARM (ThunderX, DPAA, X-Gene) or PowerPC target for respective platform.
85 For more information, refer to the :ref:`Getting Started Guide for Linux <linux_gsg>`
86 or :ref:`Getting Started Guide for FreeBSD <freebsd_gsg>` depending on your platform.
88 Running testpmd in Linux
89 ------------------------
91 This section demonstrates how to setup and run ``testpmd`` in Linux.
95 .. code-block:: console
98 mount -t hugetlbfs nodev /mnt/huge
100 #. Request huge pages:
102 Hugepage memory should be reserved as per application requirement. Check
103 hugepage size configured in the system and calculate the number of pages
106 To reserve 1024 pages of 2MB:
108 .. code-block:: console
110 echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
114 Check ``/proc/meminfo`` to find system hugepage size:
116 .. code-block:: console
118 grep "Hugepagesize:" /proc/meminfo
122 .. code-block:: console
124 Hugepagesize: 2048 kB
126 #. Load ``igb_uio`` or ``vfio-pci`` driver:
128 .. code-block:: console
131 insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
135 .. code-block:: console
139 #. Setup VFIO permissions for regular users before binding to ``vfio-pci``:
141 .. code-block:: console
143 sudo chmod a+x /dev/vfio
145 sudo chmod 0666 /dev/vfio/*
147 #. Bind the adapters to ``igb_uio`` or ``vfio-pci`` loaded in the previous step:
149 .. code-block:: console
151 ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ...
153 Or setup VFIO permissions for regular users and then bind to ``vfio-pci``:
155 .. code-block:: console
157 ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ...
161 DEVICE1, DEVICE2 are specified via PCI "domain:bus:slot.func" syntax or
162 "bus:slot.func" syntax.
164 #. Start ``testpmd`` with basic parameters:
166 .. code-block:: console
168 ./x86_64-native-linuxapp-gcc/app/testpmd -l 0-3 -n 4 -- -i
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.
174 .. code-block:: console
178 Refer to the :ref:`testpmd runtime functions <testpmd_runtime>` for a list
179 of available commands.