X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fsample_app_ug%2Fvhost.rst;h=bacf7898f974bc506705d09f3818e1ddc2de9a50;hb=769b2de7fb528607bee5cc443dbcddb905a8f61e;hp=5735adbb13b1c82290fbe7b815dc4989c9e46941;hpb=7cacb05655397c0c50bcba89eb836d417bc78b69;p=dpdk.git diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst index 5735adbb13..bacf7898f9 100644 --- a/doc/guides/sample_app_ug/vhost.rst +++ b/doc/guides/sample_app_ug/vhost.rst @@ -1,34 +1,5 @@ - -.. BSD LICENSE - Copyright(c) 2010-2016 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2016 Intel Corporation. Vhost Sample Application ======================== @@ -67,7 +38,7 @@ Start the vswitch example .. code-block:: console - ./vhost-switch -l 0-3 -n 4 --socket-mem 1024 \ + ./dpdk-vhost-switch -l 0-3 -n 4 --socket-mem 1024 \ -- --socket-file /tmp/sock0 --client \ ... @@ -107,13 +78,13 @@ could be done by: .. code-block:: console modprobe uio_pci_generic - $RTE_SDK/usertools/dpdk-devbind.py -b=uio_pci_generic 0000:00:04.0 + dpdk/usertools/dpdk-devbind.py -b uio_pci_generic 0000:00:04.0 Then start testpmd for packet forwarding testing. .. code-block:: console - ./x86_64-native-gcc/app/testpmd -l 0-1 -- -i + .//app/dpdk-testpmd -l 0-1 -- -i > start tx_first Inject packets @@ -145,7 +116,7 @@ will create it. Put simply, it's the server to create the socket file. The vm2vm parameter sets the mode of packet switching between guests in the host. -- 0 disables vm2vm, impling that VM's packets will always go to the NIC port. +- 0 disables vm2vm, implying that VM's packets will always go to the NIC port. - 1 means a normal mac lookup packet routing. - 2 means hardware mode packet forwarding between guests, it allows packets go to the NIC port, hardware L2 switch will determine which guest the @@ -176,7 +147,10 @@ retries on an RX burst, it takes effect only when rx retry is enabled. The default value is 15. **--dequeue-zero-copy** -Dequeue zero copy will be enabled when this option is given. +Dequeue zero copy will be enabled when this option is given. it is worth to +note that if NIC is bound to driver with iommu enabled, dequeue zero copy +cannot work at VM2NIC mode (vm2vm=0) due to currently we don't setup iommu +dma mapping for guest memory. **--vlan-strip 0|1** VLAN strip option is removed, because different NICs have different behaviors @@ -184,6 +158,10 @@ when disabling VLAN strip. Such feature, which heavily depends on hardware, should be removed from this example to reduce confusion. Now, VLAN strip is enabled and cannot be disabled. +**--builtin-net-driver** +A very simple vhost-user net driver which demonstrates how to use the generic +vhost APIs will be used when this option is given. It is disabled by default. + Common Issues ------------- @@ -204,15 +182,24 @@ Common Issues The command above indicates how many hugepages are free to support QEMU's allocation request. -* vhost-user will not work with QEMU without the ``-mem-prealloc`` option +* Failed to build DPDK in VM - The current implementation works properly only when the guest memory is - pre-allocated. + Make sure "-cpu host" QEMU option is given. -* vhost-user will not work with a QEMU version without shared memory mapping: +* Device start fails if NIC's max queues > the default number of 128 - Make sure ``share=on`` QEMU option is given. + mbuf pool size is dependent on the MAX_QUEUES configuration, if NIC's + max queue number is larger than 128, device start will fail due to + insufficient mbuf. -* Failed to build DPDK in VM +* Option "builtin-net-driver" is incompatible with QEMU - Make sure "-cpu host" QEMU option is given. + QEMU vhost net device start will fail if protocol feature is not negotiated. + DPDK virtio-user pmd can be the replacement of QEMU. + +* Device start fails when enabling "builtin-net-driver" without memory + pre-allocation + + The builtin example doesn't support dynamic memory allocation. When vhost + backend enables "builtin-net-driver", "--socket-mem" option should be + added at virtio-user pmd side as a startup item.