X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fsample_app_ug%2Fvhost.rst;h=a71ada6549fa94388205455f17c2785ad0e99719;hb=382f8922678992d19467e098df8e381c6a90486c;hp=95db98810ca8407ae4066fd7944833babcabd026;hpb=c6dab2a873f65c5a4ea9735aa24d9539426adba4;p=dpdk.git diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst index 95db98810c..a71ada6549 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 ======================== @@ -55,27 +26,19 @@ puts back to the same physical NIC port. Build ~~~~~ -Follow the *Getting Started Guide for Linux* on generic info about -environment setup and building DPDK from source. +To compile the sample application see :doc:`compiling`. -In this example, you need build DPDK both on the host and inside guest. -Also, you need build this example. - -.. code-block:: console - - export RTE_SDK=/path/to/dpdk_source - export RTE_TARGET=x86_64-native-linuxapp-gcc - - cd ${RTE_SDK}/examples/vhost - make +The application is located in the ``vhost`` sub-directory. +.. note:: + In this example, you need build DPDK both on the host and inside guest. Start the vswitch example ~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: console - ./vhost-switch -c f -n 4 --socket-mem 1024 \ + ./vhost-switch -l 0-3 -n 4 --socket-mem 1024 \ -- --socket-file /tmp/sock0 --client \ ... @@ -115,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 + $RTE_SDK/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 -c 0x3 -- -i + ./x86_64-native-gcc/app/testpmd -l 0-1 -- -i > start tx_first Inject packets @@ -153,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 @@ -184,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 @@ -192,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 ------------- @@ -212,15 +182,22 @@ 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 + Change the default number to make it work as below, just set the number + according to the NIC's property. :: - Make sure "-cpu host" QEMU option is given. + make EXTRA_CFLAGS="-DMAX_QUEUES=320" + +* Option "builtin-net-driver" is incompatible with QEMU + + QEMU vhost net device start will fail if protocol feature is not negotiated. + DPDK virtio-user pmd can be the replacement of QEMU.