net/virtio: fix incorrect cast of void *
[dpdk.git] / nics / virtio.rst
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
31 Poll Mode Driver for Emulated Virtio NIC
32 ========================================
33
34 Virtio is a para-virtualization framework initiated by IBM, and supported by KVM hypervisor.
35 In the Data Plane Development Kit (DPDK),
36 we provide a virtio Poll Mode Driver (PMD) as a software solution, comparing to SRIOV hardware solution,
37
38 for fast guest VM to guest VM communication and guest VM to host communication.
39
40 Vhost is a kernel acceleration module for virtio qemu backend.
41 The DPDK extends kni to support vhost raw socket interface,
42 which enables vhost to directly read/ write packets from/to a physical port.
43 With this enhancement, virtio could achieve quite promising performance.
44
45 For basic qemu-KVM installation and other Intel EM poll mode driver in guest VM,
46 please refer to Chapter "Driver for VM Emulated Devices".
47
48 In this chapter, we will demonstrate usage of virtio PMD driver with two backends,
49 standard qemu vhost back end and vhost kni back end.
50
51 Virtio Implementation in DPDK
52 -----------------------------
53
54 For details about the virtio spec, refer to Virtio PCI Card Specification written by Rusty Russell.
55
56 As a PMD, virtio provides packet reception and transmission callbacks virtio_recv_pkts and virtio_xmit_pkts.
57
58 In 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.
59
60 In virtio_xmit_pkts, same index range in vring is available for virtio to clean.
61 Virtio will enqueue to be transmitted packets into vring, advance the vq->vq_ring.avail->idx,
62 and then notify the host back end if necessary.
63
64 Features and Limitations of virtio PMD
65 --------------------------------------
66
67 In this release, the virtio PMD driver provides the basic functionality of packet reception and transmission.
68
69 *   It supports merge-able buffers per packet when receiving packets and scattered buffer per packet
70     when transmitting packets. The packet size supported is from 64 to 1518.
71
72 *   It supports multicast packets and promiscuous mode.
73
74 *   The descriptor number for the Rx/Tx queue is hard-coded to be 256 by qemu 2.7 and below.
75     If given a different descriptor number by the upper application,
76     the virtio PMD generates a warning and fall back to the hard-coded value.
77     Rx queue size can be configureable and up to 1024 since qemu 2.8 and above. Rx queue size is 256
78     by default. Tx queue size is still hard-coded to be 256.
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
85     no less than "sizeof(struct virtio_net_hdr_mrg_rxbuf)", which is 12 bytes when mergeable or
86     "VIRTIO_F_VERSION_1" is set.
87     no less than "sizeof(struct virtio_net_hdr)", which is 10 bytes, when using non-mergeable.
88
89 *   Virtio does not support runtime configuration.
90
91 *   Virtio supports Link State interrupt.
92
93 *   Virtio supports Rx interrupt (so far, only support 1:1 mapping for queue/interrupt).
94
95 *   Virtio supports software vlan stripping and inserting.
96
97 *   Virtio supports using port IO to get PCI resource when uio/igb_uio module is not available.
98
99 Prerequisites
100 -------------
101
102 The following prerequisites apply:
103
104 *   In the BIOS, turn VT-x and VT-d on
105
106 *   Linux kernel with KVM module; vhost module loaded and ioeventfd supported.
107     Qemu standard backend without vhost support isn't tested, and probably isn't supported.
108
109 Virtio with kni vhost Back End
110 ------------------------------
111
112 This section demonstrates kni vhost back end example setup for Phy-VM Communication.
113
114 .. _figure_host_vm_comms:
115
116 .. figure:: img/host_vm_comms.*
117
118    Host2VM Communication Example Using kni vhost Back End
119
120
121 Host2VM communication example
122
123 #.  Load the kni kernel module:
124
125     .. code-block:: console
126
127         insmod rte_kni.ko
128
129     Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
130     Please refer to the *DPDK Getting Started Guide* for detailed instructions.
131
132 #.  Launch the kni user application:
133
134     .. code-block:: console
135
136         examples/kni/build/app/kni -l 0-3 -n 4 -- -p 0x1 -P --config="(0,1,3)"
137
138     This command generates one network device vEth0 for physical port.
139     If specify more physical ports, the generated network device will be vEth1, vEth2, and so on.
140
141     For each physical port, kni creates two user threads.
142     One thread loops to fetch packets from the physical NIC port into the kni receive queue.
143     The other user thread loops to send packets in the kni transmit queue.
144
145     For each physical port, kni also creates a kernel thread that retrieves packets from the kni receive queue,
146     place them onto kni's raw socket's queue and wake up the vhost kernel thread to exchange packets with the virtio virt queue.
147
148     For more details about kni, please refer to :ref:`kni`.
149
150 #.  Enable the kni raw socket functionality for the specified physical NIC port,
151     get the generated file descriptor and set it in the qemu command line parameter.
152     Always remember to set ioeventfd_on and vhost_on.
153
154     Example:
155
156     .. code-block:: console
157
158         echo 1 > /sys/class/net/vEth0/sock_en
159         fd=`cat /sys/class/net/vEth0/sock_fd`
160         exec qemu-system-x86_64 -enable-kvm -cpu host \
161         -m 2048 -smp 4 -name dpdk-test1-vm1 \
162         -drive file=/data/DPDKVMS/dpdk-vm.img \
163         -netdev tap, fd=$fd,id=mynet_kni, script=no,vhost=on \
164         -device virtio-net-pci,netdev=mynet_kni,bus=pci.0,addr=0x3,ioeventfd=on \
165         -vnc:1 -daemonize
166
167     In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns corresponds to a physical port,
168     which means received packets come from vEth0, and transmitted packets is sent to vEth0.
169
170 #.  In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
171     When the virtio port in guest bursts Rx, it is getting packets from the
172     raw socket's receive queue.
173     When the virtio port bursts Tx, it is sending packet to the tx_q.
174
175     .. code-block:: console
176
177         modprobe uio
178         echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
179         modprobe uio_pci_generic
180         python usertools/dpdk-devbind.py -b uio_pci_generic 00:03.0
181
182     We use testpmd as the forwarding application in this example.
183
184     .. figure:: img/console.*
185
186        Running testpmd
187
188 #.  Use IXIA packet generator to inject a packet stream into the KNI physical port.
189
190     The packet reception and transmission flow path is:
191
192     IXIA packet generator->82599 PF->KNI Rx queue->KNI raw socket queue->Guest
193     VM virtio port 0 Rx burst->Guest VM virtio port 0 Tx burst-> KNI Tx queue
194     ->82599 PF-> IXIA packet generator
195
196 Virtio with qemu virtio Back End
197 --------------------------------
198
199 .. _figure_host_vm_comms_qemu:
200
201 .. figure:: img/host_vm_comms_qemu.*
202
203    Host2VM Communication Example Using qemu vhost Back End
204
205
206 .. code-block:: console
207
208     qemu-system-x86_64 -enable-kvm -cpu host -m 2048 -smp 2 -mem-path /dev/
209     hugepages -mem-prealloc
210     -drive file=/data/DPDKVMS/dpdk-vm1
211     -netdev tap,id=vm1_p1,ifname=tap0,script=no,vhost=on
212     -device virtio-net-pci,netdev=vm1_p1,bus=pci.0,addr=0x3,ioeventfd=on
213     -device pci-assign,host=04:10.1 \
214
215 In this example, the packet reception flow path is:
216
217     IXIA packet generator->82599 PF->Linux Bridge->TAP0's socket queue-> Guest
218     VM virtio port 0 Rx burst-> Guest VM 82599 VF port1 Tx burst-> IXIA packet
219     generator
220
221 The packet transmission flow is:
222
223     IXIA packet generator-> Guest VM 82599 VF port1 Rx burst-> Guest VM virtio
224     port 0 Tx burst-> tap -> Linux Bridge->82599 PF-> IXIA packet generator
225
226
227 Virtio PMD Rx/Tx Callbacks
228 --------------------------
229
230 Virtio driver has 3 Rx callbacks and 2 Tx callbacks.
231
232 Rx callbacks:
233
234 #. ``virtio_recv_pkts``:
235    Regular version without mergeable Rx buffer support.
236
237 #. ``virtio_recv_mergeable_pkts``:
238    Regular version with mergeable Rx buffer support.
239
240 #. ``virtio_recv_pkts_vec``:
241    Vector version without mergeable Rx buffer support, also fixes the available
242    ring indexes and uses vector instructions to optimize performance.
243
244 Tx callbacks:
245
246 #. ``virtio_xmit_pkts``:
247    Regular version.
248
249 #. ``virtio_xmit_pkts_simple``:
250    Vector version fixes the available ring indexes to optimize performance.
251
252
253 By default, the non-vector callbacks are used:
254
255 *   For Rx: If mergeable Rx buffers is disabled then ``virtio_recv_pkts`` is
256     used; otherwise ``virtio_recv_mergeable_pkts``.
257
258 *   For Tx: ``virtio_xmit_pkts``.
259
260
261 Vector callbacks will be used when:
262
263 *   ``txq_flags`` is set to ``VIRTIO_SIMPLE_FLAGS`` (0xF01), which implies:
264
265     *   Single segment is specified.
266
267     *   No offload support is needed.
268
269 *   Mergeable Rx buffers is disabled.
270
271 The corresponding callbacks are:
272
273 *   For Rx: ``virtio_recv_pkts_vec``.
274
275 *   For Tx: ``virtio_xmit_pkts_simple``.
276
277
278 Example of using the vector version of the virtio poll mode driver in
279 ``testpmd``::
280
281    testpmd -l 0-2 -n 4 -- -i --txqflags=0xF01 --rxq=1 --txq=1 --nb-cores=1
282
283
284 Interrupt mode
285 --------------
286
287 .. _virtio_interrupt_mode:
288
289 There are three kinds of interrupts from a virtio device over PCI bus: config
290 interrupt, Rx interrupts, and Tx interrupts. Config interrupt is used for
291 notification of device configuration changes, especially link status (lsc).
292 Interrupt mode is translated into Rx interrupts in the context of DPDK.
293
294 Prerequisites for Rx interrupts
295 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
296
297 To support Rx interrupts,
298 #. Check if guest kernel supports VFIO-NOIOMMU:
299
300     Linux started to support VFIO-NOIOMMU since 4.8.0. Make sure the guest
301     kernel is compiled with:
302
303     .. code-block:: console
304
305         CONFIG_VFIO_NOIOMMU=y
306
307 #. Properly set msix vectors when starting VM:
308
309     Enable multi-queue when starting VM, and specify msix vectors in qemu
310     cmdline. (N+1) is the minimum, and (2N+2) is mostly recommended.
311
312     .. code-block:: console
313
314         $(QEMU) ... -device virtio-net-pci,mq=on,vectors=2N+2 ...
315
316 #. In VM, insert vfio module in NOIOMMU mode:
317
318     .. code-block:: console
319
320         modprobe vfio enable_unsafe_noiommu_mode=1
321         modprobe vfio-pci
322
323 #. In VM, bind the virtio device with vfio-pci:
324
325     .. code-block:: console
326
327         python usertools/dpdk-devbind.py -b vfio-pci 00:03.0
328
329 Example
330 ~~~~~~~
331
332 Here we use l3fwd-power as an example to show how to get started.
333
334     Example:
335
336     .. code-block:: console
337
338         $ l3fwd-power -l 0-1 -- -p 1 -P --config="(0,0,1)" \
339                                                --no-numa --parse-ptype