doc: fix references in sample apps guide
[dpdk.git] / doc / guides / sample_app_ug / vhost.rst
1
2 ..  BSD LICENSE
3     Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
4     All rights reserved.
5
6     Redistribution and use in source and binary forms, with or without
7     modification, are permitted provided that the following conditions
8     are met:
9
10     * Redistributions of source code must retain the above copyright
11     notice, this list of conditions and the following disclaimer.
12     * Redistributions in binary form must reproduce the above copyright
13     notice, this list of conditions and the following disclaimer in
14     the documentation and/or other materials provided with the
15     distribution.
16     * Neither the name of Intel Corporation nor the names of its
17     contributors may be used to endorse or promote products derived
18     from this software without specific prior written permission.
19
20     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31
32
33 Vhost Sample Application
34 ========================
35
36 The vhost sample application demonstrates integration of the Data Plane Development Kit (DPDK)
37 with the Linux* KVM hypervisor by implementing the vhost-net offload API.
38 The sample application performs simple packet switching between virtual machines based on Media Access Control
39 (MAC) address or Virtual Local Area Network (VLAN) tag.
40 The splitting of Ethernet traffic from an external switch is performed in hardware by the Virtual Machine Device Queues
41 (VMDQ) and Data Center Bridging (DCB) features of the IntelĀ® 82599 10 Gigabit Ethernet Controller.
42
43 Background
44 ----------
45
46 Virtio networking (virtio-net) was developed as the Linux* KVM para-virtualized method for communicating network packets
47 between host and guest.
48 It was found that virtio-net performance was poor due to context switching and packet copying between host, guest, and QEMU.
49 The following figure shows the system architecture for a virtio-based networking (virtio-net).
50
51 .. _figure_qemu_virtio_net:
52
53 .. figure:: img/qemu_virtio_net.*
54
55    System Architecture for Virtio-based Networking (virtio-net).
56
57
58 The Linux* Kernel vhost-net module was developed as an offload mechanism for virtio-net.
59 The vhost-net module enables KVM (QEMU) to offload the servicing of virtio-net devices to the vhost-net kernel module,
60 reducing the context switching and packet copies in the virtual dataplane.
61
62 This is achieved by QEMU sharing the following information with the vhost-net module through the vhost-net API:
63
64 *   The layout of the guest memory space, to enable the vhost-net module to translate addresses.
65
66 *   The locations of virtual queues in QEMU virtual address space,
67     to enable the vhost module to read/write directly to and from the virtqueues.
68
69 *   An event file descriptor (eventfd) configured in KVM to send interrupts to the virtio- net device driver in the guest.
70     This enables the vhost-net module to notify (call) the guest.
71
72 *   An eventfd configured in KVM to be triggered on writes to the virtio-net device's
73     Peripheral Component Interconnect (PCI) config space.
74     This enables the vhost-net module to receive notifications (kicks) from the guest.
75
76 The following figure shows the system architecture for virtio-net networking with vhost-net offload.
77
78 .. _figure_virtio_linux_vhost:
79
80 .. figure:: img/virtio_linux_vhost.*
81
82    Virtio with Linux
83
84
85 Sample Code Overview
86 --------------------
87
88 The DPDK vhost-net sample code demonstrates KVM (QEMU) offloading the servicing of a Virtual Machine's (VM's)
89 virtio-net devices to a DPDK-based application in place of the kernel's vhost-net module.
90
91 The DPDK vhost-net sample code is based on vhost library. Vhost library is developed for user space Ethernet switch to
92 easily integrate with vhost functionality.
93
94 The vhost library implements the following features:
95
96 *   Management of virtio-net device creation/destruction events.
97
98 *   Mapping of the VM's physical memory into the DPDK vhost-net's address space.
99
100 *   Triggering/receiving notifications to/from VMs via eventfds.
101
102 *   A virtio-net back-end implementation providing a subset of virtio-net features.
103
104 There are two vhost implementations in vhost library, vhost cuse and vhost user. In vhost cuse, a character device driver is implemented to
105 receive and process vhost requests through ioctl messages. In vhost user, a socket server is created to received vhost requests through
106 socket messages. Most of the messages share the same handler routine.
107
108 .. note::
109     **Any vhost cuse specific requirement in the following sections will be emphasized**.
110
111 Two implementations are turned on and off statically through configure file. Only one implementation could be turned on. They don't co-exist in current implementation.
112
113 The vhost sample code application is a simple packet switching application with the following feature:
114
115 *   Packet switching between virtio-net devices and the network interface card,
116     including using VMDQs to reduce the switching that needs to be performed in software.
117
118 The following figure shows the architecture of the Vhost sample application based on vhost-cuse.
119
120 .. _figure_vhost_net_arch:
121
122 .. figure:: img/vhost_net_arch.*
123
124    Vhost-net Architectural Overview
125
126
127 The following figure shows the flow of packets through the vhost-net sample application.
128
129 .. _figure_vhost_net_sample_app:
130
131 .. figure:: img/vhost_net_sample_app.*
132
133    Packet Flow Through the vhost-net Sample Application
134
135
136 Supported Distributions
137 -----------------------
138
139 The example in this section have been validated with the following distributions:
140
141 *   Fedora* 18
142
143 *   Fedora* 19
144
145 *   Fedora* 20
146
147 .. _vhost_app_prerequisites:
148
149 Prerequisites
150 -------------
151
152 This section lists prerequisite packages that must be installed.
153
154 Installing Packages on the Host(vhost cuse required)
155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156
157 The vhost cuse code uses the following packages; fuse, fuse-devel, and kernel-modules-extra.
158 The vhost user code don't rely on those modules as eventfds are already installed into vhost process through
159 Unix domain socket.
160
161 #.  Install Fuse Development Libraries and headers:
162
163     .. code-block:: console
164
165         yum -y install fuse fuse-devel
166
167 #.  Install the Cuse Kernel Module:
168
169     .. code-block:: console
170
171         yum -y install kernel-modules-extra
172
173 QEMU simulator
174 ~~~~~~~~~~~~~~
175
176 For vhost user, qemu 2.2 is required.
177
178 Setting up the Execution Environment
179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
180
181 The vhost sample code requires that QEMU allocates a VM's memory on the hugetlbfs file system.
182 As the vhost sample code requires hugepages,
183 the best practice is to partition the system into separate hugepage mount points for the VMs and the vhost sample code.
184
185 .. note::
186
187     This is best-practice only and is not mandatory.
188     For systems that only support 2 MB page sizes,
189     both QEMU and vhost sample code can use the same hugetlbfs mount point without issue.
190
191 **QEMU**
192
193 VMs with gigabytes of memory can benefit from having QEMU allocate their memory from 1 GB huge pages.
194 1 GB huge pages must be allocated at boot time by passing kernel parameters through the grub boot loader.
195
196 #.  Calculate the maximum memory usage of all VMs to be run on the system.
197     Then, round this value up to the nearest Gigabyte the execution environment will require.
198
199 #.  Edit the /etc/default/grub file, and add the following to the GRUB_CMDLINE_LINUX entry:
200
201     .. code-block:: console
202
203         GRUB_CMDLINE_LINUX="... hugepagesz=1G hugepages=<Number of hugepages required> default_hugepagesz=1G"
204
205 #.  Update the grub boot loader:
206
207     .. code-block:: console
208
209         grub2-mkconfig -o /boot/grub2/grub.cfg
210
211 #.  Reboot the system.
212
213 #.  The hugetlbfs mount point (/dev/hugepages) should now default to allocating gigabyte pages.
214
215 .. note::
216
217     Making the above modification will change the system default hugepage size to 1 GB for all applications.
218
219 **Vhost Sample Code**
220
221 In this section, we create a second hugetlbs mount point to allocate hugepages for the DPDK vhost sample code.
222
223 #.  Allocate sufficient 2 MB pages for the DPDK vhost sample code:
224
225     .. code-block:: console
226
227         echo 256 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
228
229 #.  Mount hugetlbs at a separate mount point for 2 MB pages:
230
231     .. code-block:: console
232
233         mount -t hugetlbfs nodev /mnt/huge -o pagesize=2M
234
235 The above steps can be automated by doing the following:
236
237 #.  Edit /etc/fstab to add an entry to automatically mount the second hugetlbfs mount point:
238
239     ::
240
241         hugetlbfs <tab> /mnt/huge <tab> hugetlbfs defaults,pagesize=1G 0 0
242
243 #.  Edit the /etc/default/grub file, and add the following to the GRUB_CMDLINE_LINUX entry:
244
245     ::
246
247         GRUB_CMDLINE_LINUX="... hugepagesz=2M hugepages=256 ... default_hugepagesz=1G"
248
249 #.  Update the grub bootloader:
250
251     .. code-block:: console
252
253         grub2-mkconfig -o /boot/grub2/grub.cfg
254
255 #.  Reboot the system.
256
257 .. note::
258
259     Ensure that the default hugepage size after this setup is 1 GB.
260
261 Setting up the Guest Execution Environment
262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263
264 It is recommended for testing purposes that the DPDK testpmd sample application is used in the guest to forward packets,
265 the reasons for this are discussed in `Running the Virtual Machine (QEMU)`_.
266
267 The testpmd application forwards packets between pairs of Ethernet devices,
268 it requires an even number of Ethernet devices (virtio or otherwise) to execute.
269 It is therefore recommended to create multiples of two virtio-net devices for each Virtual Machine either through libvirt or
270 at the command line as follows.
271
272 .. note::
273
274     Observe that in the example, "-device" and "-netdev" are repeated for two virtio-net devices.
275
276 For vhost cuse:
277
278 .. code-block:: console
279
280     qemu-system-x86_64 ... \
281     -netdev tap,id=hostnet1,vhost=on,vhostfd=<open fd> \
282     -device virtio-net-pci, netdev=hostnet1,id=net1 \
283     -netdev tap,id=hostnet2,vhost=on,vhostfd=<open fd> \
284     -device virtio-net-pci, netdev=hostnet2,id=net1
285
286 For vhost user:
287
288 .. code-block:: console
289
290     qemu-system-x86_64 ... \
291     -chardev socket,id=char1,path=<sock_path> \
292     -netdev type=vhost-user,id=hostnet1,chardev=char1 \
293     -device virtio-net-pci,netdev=hostnet1,id=net1 \
294     -chardev socket,id=char2,path=<sock_path> \
295     -netdev type=vhost-user,id=hostnet2,chardev=char2 \
296     -device virtio-net-pci,netdev=hostnet2,id=net2
297
298 sock_path is the path for the socket file created by vhost.
299
300 Compiling the Sample Code
301 -------------------------
302 #.  Compile vhost lib:
303
304     To enable vhost, turn on vhost library in the configure file config/common_linuxapp.
305
306     .. code-block:: console
307
308         CONFIG_RTE_LIBRTE_VHOST=n
309
310     vhost user is turned on by default in the configure file config/common_linuxapp.
311     To enable vhost cuse, disable vhost user.
312
313     .. code-block:: console
314
315         CONFIG_RTE_LIBRTE_VHOST_USER=y
316
317      After vhost is enabled and the implementation is selected, build the vhost library.
318
319 #.  Go to the examples directory:
320
321     .. code-block:: console
322
323         export RTE_SDK=/path/to/rte_sdk
324         cd ${RTE_SDK}/examples/vhost
325
326 #.  Set the target (a default target is used if not specified). For example:
327
328     .. code-block:: console
329
330         export RTE_TARGET=x86_64-native-linuxapp-gcc
331
332     See the DPDK Getting Started Guide for possible RTE_TARGET values.
333
334 #.  Build the application:
335
336     .. code-block:: console
337
338         cd ${RTE_SDK}
339         make config ${RTE_TARGET}
340         make install ${RTE_TARGET}
341         cd ${RTE_SDK}/examples/vhost
342         make
343
344 #.  Go to the eventfd_link directory(vhost cuse required):
345
346     .. code-block:: console
347
348         cd ${RTE_SDK}/lib/librte_vhost/eventfd_link
349
350 #.  Build the eventfd_link kernel module(vhost cuse required):
351
352     .. code-block:: console
353
354         make
355
356 Running the Sample Code
357 -----------------------
358
359 #.  Install the cuse kernel module(vhost cuse required):
360
361     .. code-block:: console
362
363         modprobe cuse
364
365 #.  Go to the eventfd_link directory(vhost cuse required):
366
367     .. code-block:: console
368
369         export RTE_SDK=/path/to/rte_sdk
370         cd ${RTE_SDK}/lib/librte_vhost/eventfd_link
371
372 #.  Install the eventfd_link module(vhost cuse required):
373
374     .. code-block:: console
375
376         insmod ./eventfd_link.ko
377
378 #.  Go to the examples directory:
379
380     .. code-block:: console
381
382         export RTE_SDK=/path/to/rte_sdk
383         cd ${RTE_SDK}/examples/vhost/build/app
384
385 #.  Run the vhost-switch sample code:
386
387     vhost cuse:
388
389     .. code-block:: console
390
391         ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
392          -- -p 0x1 --dev-basename usvhost
393
394     vhost user: a socket file named usvhost will be created under current directory. Use its path as the socket path in guest's qemu commandline.
395
396     .. code-block:: console
397
398         ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
399          -- -p 0x1 --dev-basename usvhost
400
401 .. note::
402
403     Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.
404
405 .. note::
406
407     The number used with the --socket-mem parameter may need to be more than 1024.
408     The number required depends on the number of mbufs allocated by vhost-switch.
409
410 .. _vhost_app_parameters:
411
412 Parameters
413 ~~~~~~~~~~
414
415 **Basename.**
416 vhost cuse uses a Linux* character device to communicate with QEMU.
417 The basename is used to generate the character devices name.
418
419     /dev/<basename>
420
421 For compatibility with the QEMU wrapper script, a base name of "usvhost" should be used:
422
423 .. code-block:: console
424
425     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
426      -- -p 0x1 --dev-basename usvhost
427
428 **vm2vm.**
429 The vm2vm parameter disable/set mode of packet switching between guests in the host.
430 Value of "0" means disabling vm2vm implies that on virtual machine packet transmission will always go to the Ethernet port;
431 Value of "1" means software mode packet forwarding between guests, it needs packets copy in vHOST,
432 so valid only in one-copy implementation, and invalid for zero copy implementation;
433 value of "2" means hardware mode packet forwarding between guests, it allows packets go to the Ethernet port,
434 hardware L2 switch will determine which guest the packet should forward to or need send to external,
435 which bases on the packet destination MAC address and VLAN tag.
436
437 .. code-block:: console
438
439     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
440      -- --vm2vm [0,1,2]
441
442 **Mergeable Buffers.**
443 The mergeable buffers parameter controls how virtio-net descriptors are used for virtio-net headers.
444 In a disabled state, one virtio-net header is used per packet buffer;
445 in an enabled state one virtio-net header is used for multiple packets.
446 The default value is 0 or disabled since recent kernels virtio-net drivers show performance degradation with this feature is enabled.
447
448 .. code-block:: console
449
450     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
451      -- --mergeable [0,1]
452
453 **Stats.**
454 The stats parameter controls the printing of virtio-net device statistics.
455 The parameter specifies an interval second to print statistics, with an interval of 0 seconds disabling statistics.
456
457 .. code-block:: console
458
459     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
460     -- --stats [0,n]
461
462 **RX Retry.**
463 The rx-retry option enables/disables enqueue retries when the guests RX queue is full.
464 This feature resolves a packet loss that is observed at high data-rates,
465 by allowing it to delay and retry in the receive path.
466 This option is enabled by default.
467
468 .. code-block:: console
469
470     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
471      -- --rx-retry [0,1]
472
473 **RX Retry Number.**
474 The rx-retry-num option specifies the number of retries on an RX burst,
475 it takes effect only when rx retry is enabled.
476 The default value is 4.
477
478 .. code-block:: console
479
480     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
481      -- --rx-retry 1 --rx-retry-num 5
482
483 **RX Retry Delay Time.**
484 The rx-retry-delay option specifies the timeout (in micro seconds) between retries on an RX burst,
485 it takes effect only when rx retry is enabled.
486 The default value is 15.
487
488 .. code-block:: console
489
490     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
491      -- --rx-retry 1 --rx-retry-delay 20
492
493 **Zero copy.**
494 The zero copy option enables/disables the zero copy mode for RX/TX packet,
495 in the zero copy mode the packet buffer address from guest translate into host physical address
496 and then set directly as DMA address.
497 If the zero copy mode is disabled, then one copy mode is utilized in the sample.
498 This option is disabled by default.
499
500 .. code-block:: console
501
502     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
503      -- --zero-copy [0,1]
504
505 **RX descriptor number.**
506 The RX descriptor number option specify the Ethernet RX descriptor number,
507 Linux legacy virtio-net has different behavior in how to use the vring descriptor from DPDK based virtio-net PMD,
508 the former likely allocate half for virtio header, another half for frame buffer,
509 while the latter allocate all for frame buffer,
510 this lead to different number for available frame buffer in vring,
511 and then lead to different Ethernet RX descriptor number could be used in zero copy mode.
512 So it is valid only in zero copy mode is enabled. The value is 32 by default.
513
514 .. code-block:: console
515
516     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
517      -- --zero-copy 1 --rx-desc-num [0, n]
518
519 **TX descriptor number.**
520 The TX descriptor number option specify the Ethernet TX descriptor number, it is valid only in zero copy mode is enabled.
521 The value is 64 by default.
522
523 .. code-block:: console
524
525     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
526      -- --zero-copy 1 --tx-desc-num [0, n]
527
528 **VLAN strip.**
529 The VLAN strip option enable/disable the VLAN strip on host, if disabled, the guest will receive the packets with VLAN tag.
530 It is enabled by default.
531
532 .. code-block:: console
533
534     ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \
535      -- --vlan-strip [0, 1]
536
537 .. _vhost_app_running:
538
539 Running the Virtual Machine (QEMU)
540 ----------------------------------
541
542 QEMU must be executed with specific parameters to:
543
544 *   Ensure the guest is configured to use virtio-net network adapters.
545
546     .. code-block:: console
547
548         qemu-system-x86_64 ... -device virtio-net-pci,netdev=hostnet1, \
549         id=net1 ...
550
551 *   Ensure the guest's virtio-net network adapter is configured with offloads disabled.
552
553     .. code-block:: console
554
555         qemu-system-x86_64 ... -device virtio-net-pci,netdev=hostnet1, \
556         id=net1, csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off
557
558 *   Redirect QEMU to communicate with the DPDK vhost-net sample code in place of the vhost-net kernel module(vhost cuse).
559
560     .. code-block:: console
561
562         qemu-system-x86_64 ... -netdev tap,id=hostnet1,vhost=on, \
563         vhostfd=<open fd> ...
564
565 *   Enable the vhost-net sample code to map the VM's memory into its own process address space.
566
567     .. code-block:: console
568
569         qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ...
570
571 .. note::
572
573     The QEMU wrapper (qemu-wrap.py) is a Python script designed to automate the QEMU configuration described above.
574     It also facilitates integration with libvirt, although the script may also be used standalone without libvirt.
575
576 Redirecting QEMU to vhost-net Sample Code(vhost cuse)
577 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
578
579 To redirect QEMU to the vhost-net sample code implementation of the vhost-net API,
580 an open file descriptor must be passed to QEMU running as a child process.
581
582 .. code-block:: python
583
584     #!/usr/bin/python
585     fd = os.open("/dev/usvhost-1", os.O_RDWR)
586     subprocess.call
587     ("qemu-system-x86_64 ... -netdev tap,id=vhostnet0,vhost=on,vhostfd="
588       + fd +"...", shell=True)
589
590 .. note::
591
592     This process is automated in the `QEMU Wrapper Script`_.
593
594 Mapping the Virtual Machine's Memory
595 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
596
597 For the DPDK vhost-net sample code to be run correctly, QEMU must allocate the VM's memory on hugetlbfs.
598 This is done by specifying mem-prealloc and mem-path when executing QEMU.
599 The vhost-net sample code accesses the virtio-net device's virtual rings and packet buffers
600 by finding and mapping the VM's physical memory on hugetlbfs.
601 In this case, the path passed to the guest should be that of the 1 GB page hugetlbfs:
602
603 .. code-block:: console
604
605     qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ...
606
607 .. note::
608
609     This process is automated in the `QEMU Wrapper Script`_.
610     The following two sections only applies to vhost cuse.
611     For vhost-user, please make corresponding changes to qemu-wrapper script and guest XML file.
612
613 QEMU Wrapper Script
614 ~~~~~~~~~~~~~~~~~~~
615
616 The QEMU wrapper script automatically detects and calls QEMU with the necessary parameters required
617 to integrate with the vhost sample code.
618 It performs the following actions:
619
620 *   Automatically detects the location of the hugetlbfs and inserts this into the command line parameters.
621
622 *   Automatically open file descriptors for each virtio-net device and inserts this into the command line parameters.
623
624 *   Disables offloads on each virtio-net device.
625
626 *   Calls Qemu passing both the command line parameters passed to the script itself and those it has auto-detected.
627
628 The QEMU wrapper script will automatically configure calls to QEMU:
629
630 .. code-block:: console
631
632     qemu-wrap.py -machine pc-i440fx-1.4,accel=kvm,usb=off \
633     -cpu SandyBridge -smp 4,sockets=4,cores=1,threads=1 \
634     -netdev tap,id=hostnet1,vhost=on \
635     -device virtio-net-pci,netdev=hostnet1,id=net1 \
636     -hda <disk img> -m 4096
637
638 which will become the following call to QEMU:
639
640 .. code-block:: console
641
642     qemu-system-x86_64 -machine pc-i440fx-1.4,accel=kvm,usb=off \
643     -cpu SandyBridge -smp 4,sockets=4,cores=1,threads=1 \
644     -netdev tap,id=hostnet1,vhost=on,vhostfd=<open fd> \
645     -device virtio-net-pci,netdev=hostnet1,id=net1, \
646     csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off \
647     -hda <disk img> -m 4096 -mem-path /dev/hugepages -mem-prealloc
648
649 Libvirt Integration
650 ~~~~~~~~~~~~~~~~~~~
651
652 The QEMU wrapper script (qemu-wrap.py) "wraps" libvirt calls to QEMU,
653 such that QEMU is called with the correct parameters described above.
654 To call the QEMU wrapper automatically from libvirt, the following configuration changes must be made:
655
656 *   Place the QEMU wrapper script in libvirt's binary search PATH ($PATH).
657     A good location is in the directory that contains the QEMU binary.
658
659 *   Ensure that the script has the same owner/group and file permissions as the QEMU binary.
660
661 *   Update the VM xml file using virsh edit <vm name>:
662
663     *   Set the VM to use the launch script
664
665     *   Set the emulator path contained in the #<emulator><emulator/> tags For example,
666         replace <emulator>/usr/bin/qemu-kvm<emulator/> with  <emulator>/usr/bin/qemu-wrap.py<emulator/>
667
668     *   Set the VM's virtio-net device's to use vhost-net offload:
669
670         .. code-block:: xml
671
672             <interface type="network">
673             <model type="virtio"/>
674             <driver name="vhost"/>
675             <interface/>
676
677     *   Enable libvirt to access the DPDK Vhost sample code's character device file by adding it
678         to controllers cgroup for libvirtd using the following steps:
679
680         .. code-block:: xml
681
682             cgroup_controllers = [ ... "devices", ... ] clear_emulator_capabilities = 0
683             user = "root" group = "root"
684             cgroup_device_acl = [
685                 "/dev/null", "/dev/full", "/dev/zero",
686                 "/dev/random", "/dev/urandom",
687                 "/dev/ptmx", "/dev/kvm", "/dev/kqemu",
688                 "/dev/rtc", "/dev/hpet", "/dev/net/tun",
689                 "/dev/<devbase-name>-<index>",
690             ]
691
692 *   Disable SELinux  or set to permissive mode.
693
694
695 *   Mount cgroup device controller:
696
697     .. code-block:: console
698
699         mkdir /dev/cgroup
700         mount -t cgroup none /dev/cgroup -o devices
701
702 *   Restart the libvirtd system process
703
704     For example, on Fedora* "systemctl restart libvirtd.service"
705
706 *   Edit the configuration parameters section of the script:
707
708     *   Configure the "emul_path" variable to point to the QEMU emulator.
709
710         .. code-block:: xml
711
712             emul_path = "/usr/local/bin/qemu-system-x86_64"
713
714     *   Configure the "us_vhost_path" variable to point to the DPDK vhost-net sample code's character devices name.
715         DPDK vhost-net sample code's character device will be in the format "/dev/<basename>".
716
717         .. code-block:: xml
718
719             us_vhost_path = "/dev/usvhost"
720
721 Common Issues
722 ~~~~~~~~~~~~~
723
724 *   QEMU failing to allocate memory on hugetlbfs, with an error like the following::
725
726        file_ram_alloc: can't mmap RAM pages: Cannot allocate memory
727
728     When running QEMU the above error indicates that it has failed to allocate memory for the Virtual Machine on
729     the hugetlbfs. This is typically due to insufficient hugepages being free to support the allocation request.
730     The number of free hugepages can be checked as follows:
731
732     .. code-block:: console
733
734         cat /sys/kernel/mm/hugepages/hugepages-<pagesize>/nr_hugepages
735
736     The command above indicates how many hugepages are free to support QEMU's allocation request.
737
738 *   User space VHOST when the guest has 2MB sized huge pages:
739
740     The guest may have 2MB or 1GB sized huge pages. The user space VHOST should work properly in both cases.
741
742 *   User space VHOST will not work with QEMU without the ``-mem-prealloc`` option:
743
744     The current implementation works properly only when the guest memory is pre-allocated, so it is required to
745     use a QEMU version (e.g. 1.6) which supports ``-mem-prealloc``. The ``-mem-prealloc`` option must be
746     specified explicitly in the QEMU command line.
747
748 *   User space VHOST will not work with a QEMU version without shared memory mapping:
749
750     As shared memory mapping is mandatory for user space VHOST to work properly with the guest, user space VHOST
751     needs access to the shared memory from the guest to receive and transmit packets. It is important to make sure
752     the QEMU version supports shared memory mapping.
753
754 *   In an Ubuntu environment, QEMU fails to start a new guest normally with user space VHOST due to not being able
755     to allocate huge pages for the new guest:
756
757     The solution for this issue is to add ``-boot c`` into the QEMU command line to make sure the huge pages are
758     allocated properly and then the guest should start normally.
759
760     Use ``cat /proc/meminfo`` to check if there is any changes in the value of ``HugePages_Total`` and ``HugePages_Free``
761     after the guest startup.
762
763 *   Log message: ``eventfd_link: module verification failed: signature and/or required key missing - tainting kernel``:
764
765     This log message may be ignored. The message occurs due to the kernel module ``eventfd_link``, which is not a standard
766     Linux module but which is necessary for the user space VHOST current implementation (CUSE-based) to communicate with
767     the guest.
768
769 .. _vhost_app_running_dpdk:
770
771 Running DPDK in the Virtual Machine
772 -----------------------------------
773
774 For the DPDK vhost-net sample code to switch packets into the VM,
775 the sample code must first learn the MAC address of the VM's virtio-net device.
776 The sample code detects the address from packets being transmitted from the VM, similar to a learning switch.
777
778 This behavior requires no special action or configuration with the Linux* virtio-net driver in the VM
779 as the Linux* Kernel will automatically transmit packets during device initialization.
780 However, DPDK-based applications must be modified to automatically transmit packets during initialization
781 to facilitate the DPDK vhost- net sample code's MAC learning.
782
783 The DPDK testpmd application can be configured to automatically transmit packets during initialization
784 and to act as an L2 forwarding switch.
785
786 Testpmd MAC Forwarding
787 ~~~~~~~~~~~~~~~~~~~~~~
788
789 At high packet rates, a minor packet loss may be observed.
790 To resolve this issue, a "wait and retry" mode is implemented in the testpmd and vhost sample code.
791 In the "wait and retry" mode if the virtqueue is found to be full, then testpmd waits for a period of time before retrying to enqueue packets.
792
793 The "wait and retry" algorithm is implemented in DPDK testpmd as a forwarding method call "mac_retry".
794 The following sequence diagram describes the algorithm in detail.
795
796 .. _figure_tx_dpdk_testpmd:
797
798 .. figure:: img/tx_dpdk_testpmd.*
799
800    Packet Flow on TX in DPDK-testpmd
801
802
803 Running Testpmd
804 ~~~~~~~~~~~~~~~
805
806 The testpmd application is automatically built when DPDK is installed.
807 Run the testpmd application as follows:
808
809 .. code-block:: console
810
811     cd ${RTE_SDK}/x86_64-native-linuxapp-gcc/app
812     ./testpmd -c 0x3 -n 4 --socket-mem 512 \
813     -- --burst=64 --i --disable-hw-vlan-filter
814
815 The destination MAC address for packets transmitted on each port can be set at the command line:
816
817 .. code-block:: console
818
819     ./testpmd -c 0x3 -n 4 --socket-mem 512 \
820     -- --burst=64 --i --disable-hw-vlan-filter \
821     --eth-peer=0,aa:bb:cc:dd:ee:ff --eth-peer=1,ff:ee:dd:cc:bb:aa
822
823 *   Packets received on port 1 will be forwarded on port 0 to MAC address
824
825     aa:bb:cc:dd:ee:ff
826
827 *   Packets received on port 0 will be forwarded on port 1 to MAC address
828
829     ff:ee:dd:cc:bb:aa
830
831 The testpmd application can then be configured to act as an L2 forwarding application:
832
833 .. code-block:: console
834
835     testpmd> set fwd mac_retry
836
837 The testpmd can then be configured to start processing packets,
838 transmitting packets first so the DPDK vhost sample code on the host can learn the MAC address:
839
840 .. code-block:: console
841
842     testpmd> start tx_first
843
844 .. note::
845
846     Please note "set fwd mac_retry" is used in place of "set fwd mac_fwd" to ensure the retry feature is activated.
847
848 Passing Traffic to the Virtual Machine Device
849 ---------------------------------------------
850
851 For a virtio-net device to receive traffic,
852 the traffic's Layer 2 header must include both the virtio-net device's MAC address and VLAN tag.
853 The DPDK sample code behaves in a similar manner to a learning switch in that
854 it learns the MAC address of the virtio-net devices from the first transmitted packet.
855 On learning the MAC address,
856 the DPDK vhost sample code prints a message with the MAC address and VLAN tag virtio-net device.
857 For example:
858
859 .. code-block:: console
860
861     DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VLAN_TAG 1000 registered
862
863 The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VLAN tag 1000.
864 Any packets received on the NIC with these values is placed on the devices receive queue.
865 When a virtio-net device transmits packets, the VLAN tag is added to the packet by the DPDK vhost sample code.