doc/guides/nics/build_and_test.rst

   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
  32 Compiling and testing a PMD for a NIC
  33 =====================================
  34
  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.
  37
  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.
  41
  42 Refer to the :ref:`testpmd application user guide <testpmd_ug>` for detailed
  43 information on how to build and run testpmd.
  44
  45 Driver Compilation
  46 ------------------
  47
  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.
  50
  51 To check available targets:
  52
  53 .. code-block:: console
  54
  55    cd <DPDK-source-directory>
  56    make showconfigs
  57
  58 Example 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
  77 To 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
  83 Use ARM (ThunderX, DPAA, X-Gene) or PowerPC target for respective platform.
  84
  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.
  87
  88 Running testpmd in Linux
  89 ------------------------
  90
  91 This 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.