-#. Go to the examples directory:
-
- .. code-block:: console
-
- export RTE_SDK=/path/to/rte_sdk
- cd ${RTE_SDK}/examples/vhost
-
-#. Set the target (a default target is used if not specified). For example:
-
- .. code-block:: console
-
- export RTE_TARGET=x86_64-native-linuxapp-gcc
-
- See the DPDK Getting Started Guide for possible RTE_TARGET values.
-
-#. Build the application:
-
- .. code-block:: console
-
- cd ${RTE_SDK}
- make config ${RTE_TARGET}
- make install ${RTE_TARGET}
- cd ${RTE_SDK}/examples/vhost
- make
-
-#. Go to the eventfd_link directory(vhost cuse required):
-
- .. code-block:: console
-
- cd ${RTE_SDK}/lib/librte_vhost/eventfd_link
-
-#. Build the eventfd_link kernel module(vhost cuse required):
-
- .. code-block:: console
-
- make
-
-Running the Sample Code
------------------------
-
-#. Install the cuse kernel module(vhost cuse required):
-
- .. code-block:: console
-
- modprobe cuse
-
-#. Go to the eventfd_link directory(vhost cuse required):
-
- .. code-block:: console
-
- export RTE_SDK=/path/to/rte_sdk
- cd ${RTE_SDK}/lib/librte_vhost/eventfd_link
-
-#. Install the eventfd_link module(vhost cuse required):
-
- .. code-block:: console
-
- insmod ./eventfd_link.ko
-
-#. Go to the examples directory:
-
- .. code-block:: console
-
- export RTE_SDK=/path/to/rte_sdk
- cd ${RTE_SDK}/examples/vhost
-
-#. Run the vhost-switch sample code:
-
- vhost cuse:
-
- .. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- -p 0x1 --dev-basename usvhost --dev-index 1
-
- vhost user: a socket file named usvhost will be created under current directory. Use its path as the socket path in guest's qemu commandline.
-
- .. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- -p 0x1 --dev-basename usvhost
-
-.. note::
-
- Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.
-
-Parameters
-~~~~~~~~~~
-
-**Basename and Index.**
-vhost cuse uses a Linux* character device to communicate with QEMU.
-The basename and the index are used to generate the character devices name.
-
- /dev/<basename>-<index>
-
-The index parameter is provided for a situation where multiple instances of the virtual switch is required.
-
-For compatibility with the QEMU wrapper script, a base name of "usvhost" and an index of "1" should be used:
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir / mnt/huge -- -p 0x1 --dev-basename usvhost --dev-index 1
-
-**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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --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.
-
-.. code-block:: console
-
- user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /mnt/huge -- --vlan-strip [0, 1]
-
-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
-
- user@target:~$ 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
-
- user@target:~$ 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
-
- user@target:~$ 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
-
- user@target:~$ 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 discussed in Section 24.7.3.
-
-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: