31. Vhost Sample Application

31.4.1. Installing Packages on the Host(vhost cuse required)

The vhost cuse code uses the following packages; fuse, fuse-devel, and kernel-modules-extra. The vhost user code don’t rely on those modules as eventfds are already installed into vhost process through Unix domain socket.

1. Install Fuse Development Libraries and headers:

   yum -y install fuse fuse-devel
   

2. Install the Cuse Kernel Module:

   yum -y install kernel-modules-extra
   

31.4.2. QEMU simulator

For vhost user, qemu 2.2 is required.

31.4.3. Setting up the Execution Environment

The vhost sample code requires that QEMU allocates a VM’s memory on the hugetlbfs file system. As the vhost sample code requires hugepages, the best practice is to partition the system into separate hugepage mount points for the VMs and the vhost sample code.

QEMU

VMs with gigabytes of memory can benefit from having QEMU allocate their memory from 1 GB huge pages. 1 GB huge pages must be allocated at boot time by passing kernel parameters through the grub boot loader.

1. Calculate the maximum memory usage of all VMs to be run on the system. Then, round this value up to the nearest Gigabyte the execution environment will require.

2. Edit the /etc/default/grub file, and add the following to the GRUB_CMDLINE_LINUX entry:

   GRUB_CMDLINE_LINUX="... hugepagesz=1G hugepages=<Number of hugepages required> default_hugepagesz=1G"
   

3. Update the grub boot loader:

   grub2-mkconfig -o /boot/grub2/grub.cfg
   

4. Reboot the system.

5. The hugetlbfs mount point (/dev/hugepages) should now default to allocating gigabyte pages.

Vhost Sample Code

In this section, we create a second hugetlbs mount point to allocate hugepages for the DPDK vhost sample code.

1. Allocate sufficient 2 MB pages for the DPDK vhost sample code:

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

2. Mount hugetlbs at a separate mount point for 2 MB pages:

   mount -t hugetlbfs nodev /mnt/huge -o pagesize=2M
   

The above steps can be automated by doing the following:

1. Edit /etc/fstab to add an entry to automatically mount the second hugetlbfs mount point:

   hugetlbfs <tab> /mnt/huge <tab> hugetlbfs defaults,pagesize=1G 0 0
   

2. Edit the /etc/default/grub file, and add the following to the GRUB_CMDLINE_LINUX entry:

   GRUB_CMDLINE_LINUX="... hugepagesz=2M hugepages=256 ... default_hugepagesz=1G"
   

3. Update the grub bootloader:

   grub2-mkconfig -o /boot/grub2/grub.cfg
   

4. Reboot the system.

31.4.4. Setting up the Guest Execution Environment

It is recommended for testing purposes that the DPDK testpmd sample application is used in the guest to forward packets, the reasons for this are discussed in Running the Virtual Machine (QEMU).

The testpmd application forwards packets between pairs of Ethernet devices, it requires an even number of Ethernet devices (virtio or otherwise) to execute. It is therefore recommended to create multiples of two virtio-net devices for each Virtual Machine either through libvirt or at the command line as follows.

For vhost cuse:

qemu-system-x86_64 ... \
-netdev tap,id=hostnet1,vhost=on,vhostfd=<open fd> \
-device virtio-net-pci, netdev=hostnet1,id=net1 \
-netdev tap,id=hostnet2,vhost=on,vhostfd=<open fd> \
-device virtio-net-pci, netdev=hostnet2,id=net1

For vhost user:

qemu-system-x86_64 ... \
-chardev socket,id=char1,path=<sock_path> \
-netdev type=vhost-user,id=hostnet1,chardev=char1 \
-device virtio-net-pci,netdev=hostnet1,id=net1 \
-chardev socket,id=char2,path=<sock_path> \
-netdev type=vhost-user,id=hostnet2,chardev=char2 \
-device virtio-net-pci,netdev=hostnet2,id=net2

sock_path is the path for the socket file created by vhost.

31.6.1. Parameters

Basename. vhost cuse uses a Linux* character device to communicate with QEMU. The basename is used to generate the character devices name.

/dev/<basename>

For compatibility with the QEMU wrapper script, a base name of “usvhost” should be used:

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- -p 0x1 --dev-basename usvhost

vm2vm. The vm2vm parameter disable/set mode of packet switching between guests in the host. Value of “0” means disabling vm2vm implies that on virtual machine packet transmission will always go to the Ethernet port; Value of “1” means software mode packet forwarding between guests, it needs packets copy in vHOST, so valid only in one-copy implementation, and invalid for zero copy implementation; value of “2” means hardware mode packet forwarding between guests, it allows packets go to the Ethernet port, hardware L2 switch will determine which guest the packet should forward to or need send to external, which bases on the packet destination MAC address and VLAN tag.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --vm2vm [0,1,2]

Mergeable Buffers. The mergeable buffers parameter controls how virtio-net descriptors are used for virtio-net headers. In a disabled state, one virtio-net header is used per packet buffer; in an enabled state one virtio-net header is used for multiple packets. The default value is 0 or disabled since recent kernels virtio-net drivers show performance degradation with this feature is enabled.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --mergeable [0,1]

Stats. The stats parameter controls the printing of virtio-net device statistics. The parameter specifies an interval second to print statistics, with an interval of 0 seconds disabling statistics.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
-- --stats [0,n]

RX Retry. The rx-retry option enables/disables enqueue retries when the guests RX queue is full. This feature resolves a packet loss that is observed at high data-rates, by allowing it to delay and retry in the receive path. This option is enabled by default.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --rx-retry [0,1]

RX Retry Number. The rx-retry-num option specifies the number of retries on an RX burst, it takes effect only when rx retry is enabled. The default value is 4.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --rx-retry 1 --rx-retry-num 5

RX Retry Delay Time. The rx-retry-delay option specifies the timeout (in micro seconds) between retries on an RX burst, it takes effect only when rx retry is enabled. The default value is 15.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --rx-retry 1 --rx-retry-delay 20

Zero copy. The zero copy option enables/disables the zero copy mode for RX/TX packet, in the zero copy mode the packet buffer address from guest translate into host physical address and then set directly as DMA address. If the zero copy mode is disabled, then one copy mode is utilized in the sample. This option is disabled by default.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --zero-copy [0,1]

RX descriptor number. The RX descriptor number option specify the Ethernet RX descriptor number, Linux legacy virtio-net has different behavior in how to use the vring descriptor from DPDK based virtio-net PMD, the former likely allocate half for virtio header, another half for frame buffer, while the latter allocate all for frame buffer, this lead to different number for available frame buffer in vring, and then lead to different Ethernet RX descriptor number could be used in zero copy mode. So it is valid only in zero copy mode is enabled. The value is 32 by default.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --zero-copy 1 --rx-desc-num [0, n]

TX descriptor number. The TX descriptor number option specify the Ethernet TX descriptor number, it is valid only in zero copy mode is enabled. The value is 64 by default.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --zero-copy 1 --tx-desc-num [0, n]

VLAN strip. The VLAN strip option enable/disable the VLAN strip on host, if disabled, the guest will receive the packets with VLAN tag. It is enabled by default.

./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
 -- --vlan-strip [0, 1]

31.7.1. Redirecting QEMU to vhost-net Sample Code(vhost cuse)

To redirect QEMU to the vhost-net sample code implementation of the vhost-net API, an open file descriptor must be passed to QEMU running as a child process.

#!/usr/bin/python
fd = os.open("/dev/usvhost-1", os.O_RDWR)
subprocess.call
("qemu-system-x86_64 ... -netdev tap,id=vhostnet0,vhost=on,vhostfd="
  + fd +"...", shell=True)

31.7.2. Mapping the Virtual Machine’s Memory

For the DPDK vhost-net sample code to be run correctly, QEMU must allocate the VM’s memory on hugetlbfs. This is done by specifying mem-prealloc and mem-path when executing QEMU. The vhost-net sample code accesses the virtio-net device’s virtual rings and packet buffers by finding and mapping the VM’s physical memory on hugetlbfs. In this case, the path passed to the guest should be that of the 1 GB page hugetlbfs:

qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ...

31.7.3. QEMU Wrapper Script

The QEMU wrapper script automatically detects and calls QEMU with the necessary parameters required to integrate with the vhost sample code. It performs the following actions:

• Automatically detects the location of the hugetlbfs and inserts this into the command line parameters.
• Automatically open file descriptors for each virtio-net device and inserts this into the command line parameters.
• Disables offloads on each virtio-net device.
• Calls Qemu passing both the command line parameters passed to the script itself and those it has auto-detected.

The QEMU wrapper script will automatically configure calls to QEMU:

qemu-wrap.py -machine pc-i440fx-1.4,accel=kvm,usb=off \
-cpu SandyBridge -smp 4,sockets=4,cores=1,threads=1 \
-netdev tap,id=hostnet1,vhost=on \
-device virtio-net-pci,netdev=hostnet1,id=net1 \
-hda <disk img> -m 4096

which will become the following call to QEMU:

qemu-system-x86_64 -machine pc-i440fx-1.4,accel=kvm,usb=off \
-cpu SandyBridge -smp 4,sockets=4,cores=1,threads=1 \
-netdev tap,id=hostnet1,vhost=on,vhostfd=<open fd> \
-device virtio-net-pci,netdev=hostnet1,id=net1, \
csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off \
-hda <disk img> -m 4096 -mem-path /dev/hugepages -mem-prealloc

31.7.4. Libvirt Integration

The QEMU wrapper script (qemu-wrap.py) “wraps” libvirt calls to QEMU, such that QEMU is called with the correct parameters described above. To call the QEMU wrapper automatically from libvirt, the following configuration changes must be made:

• Place the QEMU wrapper script in libvirt’s binary search PATH ($PATH). A good location is in the directory that contains the QEMU binary.

• Ensure that the script has the same owner/group and file permissions as the QEMU binary.

• Update the VM xml file using virsh edit <vm name>:

  • Set the VM to use the launch script

  • Set the emulator path contained in the #<emulator><emulator/> tags For example, replace <emulator>/usr/bin/qemu-kvm<emulator/> with <emulator>/usr/bin/qemu-wrap.py<emulator/>

  • Set the VM’s virtio-net device’s to use vhost-net offload:

    <interface type="network">
    <model type="virtio"/>
    <driver name="vhost"/>
    <interface/>
    

  • Enable libvirt to access the DPDK Vhost sample code’s character device file by adding it to controllers cgroup for libvirtd using the following steps:

    cgroup_controllers = [ ... "devices", ... ] clear_emulator_capabilities = 0
    user = "root" group = "root"
    cgroup_device_acl = [
        "/dev/null", "/dev/full", "/dev/zero",
        "/dev/random", "/dev/urandom",
        "/dev/ptmx", "/dev/kvm", "/dev/kqemu",
        "/dev/rtc", "/dev/hpet", "/dev/net/tun",
        "/dev/<devbase-name>-<index>",
    ]
    

• Disable SELinux or set to permissive mode.

• Mount cgroup device controller:

  mkdir /dev/cgroup
  mount -t cgroup none /dev/cgroup -o devices
  

• Restart the libvirtd system process

  For example, on Fedora* “systemctl restart libvirtd.service”

• Edit the configuration parameters section of the script:

  • Configure the “emul_path” variable to point to the QEMU emulator.

    emul_path = "/usr/local/bin/qemu-system-x86_64"
    

  • Configure the “us_vhost_path” variable to point to the DPDK vhost-net sample code’s character devices name. DPDK vhost-net sample code’s character device will be in the format “/dev/<basename>”.

    us_vhost_path = "/dev/usvhost"
    

31.7.5. Common Issues

• QEMU failing to allocate memory on hugetlbfs, with an error like the following:

  file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
  

  When running QEMU the above error indicates that it has failed to allocate memory for the Virtual Machine on the hugetlbfs. This is typically due to insufficient hugepages being free to support the allocation request. The number of free hugepages can be checked as follows:

  cat /sys/kernel/mm/hugepages/hugepages-<pagesize>/nr_hugepages
  

  The command above indicates how many hugepages are free to support QEMU’s allocation request.

• User space VHOST when the guest has 2MB sized huge pages:

  The guest may have 2MB or 1GB sized huge pages. The user space VHOST should work properly in both cases.

• User space VHOST will not work with QEMU without the -mem-prealloc option:

  The current implementation works properly only when the guest memory is pre-allocated, so it is required to use a QEMU version (e.g. 1.6) which supports -mem-prealloc. The -mem-prealloc option must be specified explicitly in the QEMU command line.

• User space VHOST will not work with a QEMU version without shared memory mapping:

  As shared memory mapping is mandatory for user space VHOST to work properly with the guest, user space VHOST needs access to the shared memory from the guest to receive and transmit packets. It is important to make sure the QEMU version supports shared memory mapping.

• In an Ubuntu environment, QEMU fails to start a new guest normally with user space VHOST due to not being able to allocate huge pages for the new guest:

  The solution for this issue is to add -boot c into the QEMU command line to make sure the huge pages are allocated properly and then the guest should start normally.

  Use cat /proc/meminfo to check if there is any changes in the value of HugePages_Total and HugePages_Free after the guest startup.

• Log message: eventfd_link: module verification failed: signature and/or required key missing - tainting kernel:

  This log message may be ignored. The message occurs due to the kernel module eventfd_link, which is not a standard Linux module but which is necessary for the user space VHOST current implementation (CUSE-based) to communicate with the guest.

31.8.1. Testpmd MAC Forwarding

At high packet rates, a minor packet loss may be observed. To resolve this issue, a “wait and retry” mode is implemented in the testpmd and vhost sample code. In the “wait and retry” mode if the virtqueue is found to be full, then testpmd waits for a period of time before retrying to enqueue packets.

The “wait and retry” algorithm is implemented in DPDK testpmd as a forwarding method call “mac_retry”. The following sequence diagram describes the algorithm in detail.

Fig. 31.5 Packet Flow on TX in DPDK-testpmd

31.8.2. Running Testpmd

The testpmd application is automatically built when DPDK is installed. Run the testpmd application as follows:

cd ${RTE_SDK}/x86_64-native-linuxapp-gcc/app
./testpmd -c 0x3 -n 4 --socket-mem 512 \
-- --burst=64 --i --disable-hw-vlan-filter

The destination MAC address for packets transmitted on each port can be set at the command line:

./testpmd -c 0x3 -n 4 --socket-mem 512 \
-- --burst=64 --i --disable-hw-vlan-filter \
--eth-peer=0,aa:bb:cc:dd:ee:ff --eth-peer=1,ff:ee:dd:cc:bb:aa

• Packets received on port 1 will be forwarded on port 0 to MAC address

  aa:bb:cc:dd:ee:ff

• Packets received on port 0 will be forwarded on port 1 to MAC address

  ff:ee:dd:cc:bb:aa

The testpmd application can then be configured to act as an L2 forwarding application:

testpmd> set fwd mac_retry

The testpmd can then be configured to start processing packets, transmitting packets first so the DPDK vhost sample code on the host can learn the MAC address:

testpmd> start tx_first