virtio.rst revision 7b53c036
1..  BSD LICENSE
2    Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
3    All rights reserved.
4
5    Redistribution and use in source and binary forms, with or without
6    modification, are permitted provided that the following conditions
7    are met:
8
9    * Redistributions of source code must retain the above copyright
10    notice, this list of conditions and the following disclaimer.
11    * Redistributions in binary form must reproduce the above copyright
12    notice, this list of conditions and the following disclaimer in
13    the documentation and/or other materials provided with the
14    distribution.
15    * Neither the name of Intel Corporation nor the names of its
16    contributors may be used to endorse or promote products derived
17    from this software without specific prior written permission.
18
19    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31Poll Mode Driver for Emulated Virtio NIC
32========================================
33
34Virtio is a para-virtualization framework initiated by IBM, and supported by KVM hypervisor.
35In the Data Plane Development Kit (DPDK),
36we provide a virtio Poll Mode Driver (PMD) as a software solution, comparing to SRIOV hardware solution,
37for fast guest VM to guest VM communication and guest VM to host communication.
38
39Vhost is a kernel acceleration module for virtio qemu backend.
40The DPDK extends kni to support vhost raw socket interface,
41which enables vhost to directly read/ write packets from/to a physical port.
42With this enhancement, virtio could achieve quite promising performance.
43
44In future release, we will also make enhancement to vhost backend,
45releasing peak performance of virtio PMD driver.
46
47For basic qemu-KVM installation and other Intel EM poll mode driver in guest VM,
48please refer to Chapter "Driver for VM Emulated Devices".
49
50In this chapter, we will demonstrate usage of virtio PMD driver with two backends,
51standard qemu vhost back end and vhost kni back end.
52
53Virtio Implementation in DPDK
54-----------------------------
55
56For details about the virtio spec, refer to Virtio PCI Card Specification written by Rusty Russell.
57
58As a PMD, virtio provides packet reception and transmission callbacks virtio_recv_pkts and virtio_xmit_pkts.
59
60In virtio_recv_pkts, index in range [vq->vq_used_cons_idx , vq->vq_ring.used->idx) in vring is available for virtio to burst out.
61
62In virtio_xmit_pkts, same index range in vring is available for virtio to clean.
63Virtio will enqueue to be transmitted packets into vring, advance the vq->vq_ring.avail->idx,
64and then notify the host back end if necessary.
65
66Features and Limitations of virtio PMD
67--------------------------------------
68
69In this release, the virtio PMD driver provides the basic functionality of packet reception and transmission.
70
71*   It supports merge-able buffers per packet when receiving packets and scattered buffer per packet
72    when transmitting packets. The packet size supported is from 64 to 1518.
73
74*   It supports multicast packets and promiscuous mode.
75
76*   The descriptor number for the Rx/Tx queue is hard-coded to be 256 by qemu.
77    If given a different descriptor number by the upper application,
78    the virtio PMD generates a warning and fall back to the hard-coded value.
79
80*   Features of mac/vlan filter are supported, negotiation with vhost/backend are needed to support them.
81    When backend can't support vlan filter, virtio app on guest should disable vlan filter to make sure
82    the virtio port is configured correctly. E.g. specify '--disable-hw-vlan' in testpmd command line.
83
84*   RTE_PKTMBUF_HEADROOM should be defined larger than sizeof(struct virtio_net_hdr), which is 10 bytes.
85
86*   Virtio does not support runtime configuration.
87
88*   Virtio supports Link State interrupt.
89
90*   Virtio supports software vlan stripping and inserting.
91
92*   Virtio supports using port IO to get PCI resource when uio/igb_uio module is not available.
93
94Prerequisites
95-------------
96
97The following prerequisites apply:
98
99*   In the BIOS, turn VT-x and VT-d on
100
101*   Linux kernel with KVM module; vhost module loaded and ioeventfd supported.
102    Qemu standard backend without vhost support isn't tested, and probably isn't supported.
103
104Virtio with kni vhost Back End
105------------------------------
106
107This section demonstrates kni vhost back end example setup for Phy-VM Communication.
108
109.. _figure_host_vm_comms:
110
111.. figure:: img/host_vm_comms.*
112
113   Host2VM Communication Example Using kni vhost Back End
114
115
116Host2VM communication example
117
118#.  Load the kni kernel module:
119
120    .. code-block:: console
121
122        insmod rte_kni.ko
123
124    Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
125    Please refer to the *DPDK Getting Started Guide* for detailed instructions.
126
127#.  Launch the kni user application:
128
129    .. code-block:: console
130
131        examples/kni/build/app/kni -c 0xf -n 4 -- -p 0x1 -P --config="(0,1,3)"
132
133    This command generates one network device vEth0 for physical port.
134    If specify more physical ports, the generated network device will be vEth1, vEth2, and so on.
135
136    For each physical port, kni creates two user threads.
137    One thread loops to fetch packets from the physical NIC port into the kni receive queue.
138    The other user thread loops to send packets in the kni transmit queue.
139
140    For each physical port, kni also creates a kernel thread that retrieves packets from the kni receive queue,
141    place them onto kni's raw socket's queue and wake up the vhost kernel thread to exchange packets with the virtio virt queue.
142
143    For more details about kni, please refer to :ref:`kni`.
144
145#.  Enable the kni raw socket functionality for the specified physical NIC port,
146    get the generated file descriptor and set it in the qemu command line parameter.
147    Always remember to set ioeventfd_on and vhost_on.
148
149    Example:
150
151    .. code-block:: console
152
153        echo 1 > /sys/class/net/vEth0/sock_en
154        fd=`cat /sys/class/net/vEth0/sock_fd`
155        exec qemu-system-x86_64 -enable-kvm -cpu host \
156        -m 2048 -smp 4 -name dpdk-test1-vm1 \
157        -drive file=/data/DPDKVMS/dpdk-vm.img \
158        -netdev tap, fd=$fd,id=mynet_kni, script=no,vhost=on \
159        -device virtio-net-pci,netdev=mynet_kni,bus=pci.0,addr=0x3,ioeventfd=on \
160        -vnc:1 -daemonize
161
162    In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns corresponds to a physical port,
163    which means received packets come from vEth0, and transmitted packets is sent to vEth0.
164
165#.  In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
166    When the virtio port in guest bursts Rx, it is getting packets from the
167    raw socket's receive queue.
168    When the virtio port bursts Tx, it is sending packet to the tx_q.
169
170    .. code-block:: console
171
172        modprobe uio
173        echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
174        modprobe uio_pci_generic
175        python tools/dpdk-devbind.py -b uio_pci_generic 00:03.0
176
177    We use testpmd as the forwarding application in this example.
178
179    .. figure:: img/console.*
180
181       Running testpmd
182
183#.  Use IXIA packet generator to inject a packet stream into the KNI physical port.
184
185    The packet reception and transmission flow path is:
186
187    IXIA packet generator->82599 PF->KNI Rx queue->KNI raw socket queue->Guest
188    VM virtio port 0 Rx burst->Guest VM virtio port 0 Tx burst-> KNI Tx queue
189    ->82599 PF-> IXIA packet generator
190
191Virtio with qemu virtio Back End
192--------------------------------
193
194.. _figure_host_vm_comms_qemu:
195
196.. figure:: img/host_vm_comms_qemu.*
197
198   Host2VM Communication Example Using qemu vhost Back End
199
200
201.. code-block:: console
202
203    qemu-system-x86_64 -enable-kvm -cpu host -m 2048 -smp 2 -mem-path /dev/
204    hugepages -mem-prealloc
205    -drive file=/data/DPDKVMS/dpdk-vm1
206    -netdev tap,id=vm1_p1,ifname=tap0,script=no,vhost=on
207    -device virtio-net-pci,netdev=vm1_p1,bus=pci.0,addr=0x3,ioeventfd=on
208    -device pci-assign,host=04:10.1 \
209
210In this example, the packet reception flow path is:
211
212    IXIA packet generator->82599 PF->Linux Bridge->TAP0's socket queue-> Guest
213    VM virtio port 0 Rx burst-> Guest VM 82599 VF port1 Tx burst-> IXIA packet
214    generator
215
216The packet transmission flow is:
217
218    IXIA packet generator-> Guest VM 82599 VF port1 Rx burst-> Guest VM virtio
219    port 0 Tx burst-> tap -> Linux Bridge->82599 PF-> IXIA packet generator
220
221
222Virtio PMD Rx/Tx Callbacks
223--------------------------
224
225Virtio driver has 3 Rx callbacks and 2 Tx callbacks.
226
227Rx callbacks:
228
229#. ``virtio_recv_pkts``:
230   Regular version without mergeable Rx buffer support.
231
232#. ``virtio_recv_mergeable_pkts``:
233   Regular version with mergeable Rx buffer support.
234
235#. ``virtio_recv_pkts_vec``:
236   Vector version without mergeable Rx buffer support, also fixes the available
237   ring indexes and uses vector instructions to optimize performance.
238
239Tx callbacks:
240
241#. ``virtio_xmit_pkts``:
242   Regular version.
243
244#. ``virtio_xmit_pkts_simple``:
245   Vector version fixes the available ring indexes to optimize performance.
246
247
248By default, the non-vector callbacks are used:
249
250*   For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts`` is
251    used; otherwise ``virtio_recv_mergeable_pkts``.
252
253*   For Tx: ``virtio_xmit_pkts``.
254
255
256Vector callbacks will be used when:
257
258*   ``txq_flags`` is set to ``VIRTIO_SIMPLE_FLAGS`` (0xF01), which implies:
259
260    *   Single segment is specified.
261
262    *   No offload support is needed.
263
264*   Mergeable Rx buffers is disabled.
265
266The corresponding callbacks are:
267
268*   For Rx: ``virtio_recv_pkts_vec``.
269
270*   For Tx: ``virtio_xmit_pkts_simple``.
271
272
273Example of using the vector version of the virtio poll mode driver in
274``testpmd``::
275
276   testpmd -c 0x7 -n 4 -- -i --txqflags=0xF01 --rxq=1 --txq=1 --nb-cores=1
277