3. Compiling and testing a PMD for a NIC

This section demonstrates how to compile and run a Poll Mode Driver (PMD) for the available Network Interface Cards in DPDK using TestPMD.

TestPMD is one of the reference applications distributed with the DPDK. Its main purpose is to forward packets between Ethernet ports on a network interface and as such is the best way to test a PMD.

Refer to the testpmd application user guide for detailed information on how to build and run testpmd.

3.1. Driver Compilation

To compile a PMD for a platform, build DPDK as described in the “Getting Started Guide” for your platform. This will also build testpmd.

Detailed instructions are available in the meson build guide.

The ethdev layer supports below build options for debug purpose:

  • RTE_ETHDEV_DEBUG_RX (default disabled)

    Build with debug code on Rx path.

  • RTE_ETHDEV_DEBUG_TX (default disabled)

    Build with debug code on Tx path.

  • RTE_FLOW_DEBUG (default disabled; enabled automatically on debug builds)

    Build with debug code in asynchronous flow API.

Note

The ethdev library uses above options to wrap debug code to trace invalid parameters on data path APIs, so performance downgrade is expected when enabling those options. Each PMD can decide to reuse them to wrap their own debug code in the Rx/Tx path and in asynchronous flow API implementation.

3.2. Running testpmd in Linux

This section demonstrates how to setup and run testpmd in Linux.

  1. Mount huge pages:

    mkdir /mnt/huge
    mount -t hugetlbfs nodev /mnt/huge
    
  2. Request huge pages:

    Hugepage memory should be reserved as per application requirement. Check hugepage size configured in the system and calculate the number of pages required.

    To reserve 1024 pages of 2MB:

    echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
    

    Note

    Check /proc/meminfo to find system hugepage size:

    grep "Hugepagesize:" /proc/meminfo
    

    Example output:

    Hugepagesize:       2048 kB
    

    Mount and request above can be achieved simply with this tool:

    dpdk-hugepages.py --setup 2G
    
  3. Load igb_uio or vfio-pci driver:

    modprobe uio
    insmod igb_uio.ko
    

    or

    modprobe vfio-pci
    
  4. Setup VFIO permissions for regular users before binding to vfio-pci:

    sudo chmod a+x /dev/vfio
    
    sudo chmod 0666 /dev/vfio/*
    
  5. Bind the adapters to igb_uio or vfio-pci loaded in the previous step:

    ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ...
    

    Or setup VFIO permissions for regular users and then bind to vfio-pci:

    ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ...
    

    Note

    DEVICE1, DEVICE2 are specified via PCI “domain:bus:slot.func” syntax or “bus:slot.func” syntax.

  6. Start testpmd with basic parameters:

    ./<build_dir>/app/dpdk-testpmd -l 0-3 -n 4 -- -i
    

    Successful execution will show initialization messages from EAL, PMD and testpmd application. A prompt will be displayed at the end for user commands as interactive mode (-i) is on.

    testpmd>
    

    Refer to the testpmd runtime functions for a list of available commands.

    Note

    When testpmd is built with shared library, use option -d to load the dynamic PMD for rte_eal_init.