-.. _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>: