-.. _vhost_app_running:
-
-Running the Virtual Machine (QEMU)
-----------------------------------
-
-QEMU must be executed with specific parameters to:
-
-* Ensure the guest is configured to use virtio-net network adapters.
-
- .. code-block:: console
-
- qemu-system-x86_64 ... -device virtio-net-pci,netdev=hostnet1, \
- id=net1 ...
-
-* Ensure the guest's virtio-net network adapter is configured with offloads disabled.
-
- .. code-block:: console
-
- qemu-system-x86_64 ... -device virtio-net-pci,netdev=hostnet1, \
- id=net1, csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off
-
-* Redirect QEMU to communicate with the DPDK vhost-net sample code in place of the vhost-net kernel module(vhost cuse).
-
- .. code-block:: console
-
- qemu-system-x86_64 ... -netdev tap,id=hostnet1,vhost=on, \
- vhostfd=<open fd> ...
-
-* Enable the vhost-net sample code to map the VM's memory into its own process address space.
-
- .. code-block:: console
-
- qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ...
-
-.. note::
-
- The QEMU wrapper (qemu-wrap.py) is a Python script designed to automate the QEMU configuration described above.
- It also facilitates integration with libvirt, although the script may also be used standalone without libvirt.
-
-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.
-
-.. code-block:: python
-
- #!/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)
-
-.. note::
-
- This process is automated in the `QEMU Wrapper Script`_.
-
-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:
-
-.. code-block:: console
-
- qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ...
-
-.. note::
-
- This process is automated in the `QEMU Wrapper Script`_.
- The following two sections only applies to vhost cuse.
- For vhost-user, please make corresponding changes to qemu-wrapper script and guest XML file.
-
-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:
-
-.. code-block:: console
-
- 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:
-
-.. code-block:: console
-
- 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
-
-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:
-
- .. code-block:: xml
-
- <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:
-
- .. code-block:: xml
-
- 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:
-
- .. code-block:: console
-
- 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.
-
- .. code-block:: xml
-
- 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>".
-
- .. code-block:: xml
-
- us_vhost_path = "/dev/usvhost"