net/virtio-user: add virtual device

[dpdk.git] / doc / guides / sample_app_ug / vhost.rst

diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst
index e5d1326..a93e54d 100644 (file)
--- a/doc/guides/sample_app_ug/vhost.rst
+++ b/doc/guides/sample_app_ug/vhost.rst
@@ -144,6 +144,8 @@ The example in this section have been validated with the following distributions
 
 *   Fedora* 20
 
+.. _vhost_app_prerequisites:
+
 Prerequisites
 -------------
 
@@ -260,7 +262,7 @@ 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 Section 22.7, "Running the Virtual Machine (QEMU)".
+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.
@@ -405,6 +407,8 @@ Running the Sample Code
     The number used with the --socket-mem parameter may need to be more than 1024.
     The number required depends on the number of mbufs allocated by vhost-switch.
 
+.. _vhost_app_parameters:
+
 Parameters
 ~~~~~~~~~~
 
@@ -487,39 +491,9 @@ The default value is 15.
      -- --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
-
-    ./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.
-
-.. code-block:: console
-
-    ./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.
-
-.. code-block:: console
-
-    ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
-     -- --zero-copy 1 --tx-desc-num [0, n]
+Zero copy mode is removed, due to it has not been working for a while. And
+due to the large and complex code, it's better to redesign it than fixing
+it to make it work again. Hence, zero copy may be added back later.
 
 **VLAN strip.**
 The VLAN strip option enable/disable the VLAN strip on host, if disabled, the guest will receive the packets with VLAN tag.
@@ -530,6 +504,8 @@ It is enabled by default.
     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
      -- --vlan-strip [0, 1]
 
+.. _vhost_app_running:
+
 Running the Virtual Machine (QEMU)
 ----------------------------------
 
@@ -583,7 +559,7 @@ an open file descriptor must be passed to QEMU running as a child process.
 
 .. note::
 
-    This process is automated in the QEMU wrapper script discussed in Section 24.7.3.
+    This process is automated in the `QEMU Wrapper Script`_.
 
 Mapping the Virtual Machine's Memory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -600,7 +576,7 @@ In this case, the path passed to the guest should be that of the 1 GB page huget
 
 .. note::
 
-    This process is automated in the QEMU wrapper script discussed in Section 24.7.3.
+    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.
 
@@ -760,6 +736,7 @@ Common Issues
     Linux module but which is necessary for the user space VHOST current implementation (CUSE-based) to communicate with
     the guest.
 
+.. _vhost_app_running_dpdk:
 
 Running DPDK in the Virtual Machine
 -----------------------------------
@@ -856,3 +833,20 @@ For example:
 The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VLAN tag 1000.
 Any packets received on the NIC with these values is placed on the devices receive queue.
 When a virtio-net device transmits packets, the VLAN tag is added to the packet by the DPDK vhost sample code.
+
+Running virtio-user with vhost-switch
+-------------------------------------
+
+We can also use virtio-user with vhost-switch now.
+Virtio-user is a virtual device that can be run in a application (container) parallelly with vhost in the same OS,
+aka, there is no need to start a VM. We just run it with a different --file-prefix to avoid startup failure.
+
+.. code-block:: console
+
+    cd ${RTE_SDK}/x86_64-native-linuxapp-gcc/app
+    ./testpmd -c 0x3 -n 4 --socket-mem 1024 --no-pci --file-prefix=virtio-user-testpmd \
+    --vdev=virtio-user0,mac=00:01:02:03:04:05,path=$path_vhost \
+    -- -i --txqflags=0xf01 --disable-hw-vlan
+
+There is no difference on the vhost side.
+Pleae note that there are some limitations (see release note for more information) in the usage of virtio-user.