doc: add VF live migration howto with bonded virtio
[dpdk.git] / doc / guides / howto / lm_bond_virtio_sriov.rst
1 ..  BSD LICENSE
2     Copyright(c) 2016 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 Live Migration of VM with SR-IOV VF
32 ===================================
33
34 Overview
35 --------
36
37 It is not possible to migrate a Virtual Machine which has an SR-IOV Virtual Function (VF).
38
39 To get around this problem the bonding PMD is used.
40
41 The following sections show an example of how to do this.
42
43 Test Setup
44 ----------
45
46 A bonded device is created in the VM.
47 The virtio and VF PMD's are added as slaves to the bonded device.
48 The VF is set as the primary slave of the bonded device.
49
50 A bridge must be set up on the Host connecting the tap device, which is the
51 backend of the Virtio device and the Physical Function (PF) device.
52
53 To test the Live Migration two servers with identical operating systems installed are used.
54 KVM and Qemu 2.3 is also required on the servers.
55
56 In this example, the servers have Niantic and or Fortville NIC's installed.
57 The NIC's on both servers are connected to a switch
58 which is also connected to the traffic generator.
59
60 The switch is configured to broadcast traffic on all the NIC ports.
61 A :ref:`Sample switch configuration <lm_bond_virtio_sriov_switch_conf>`
62 can be found in this section.
63
64 The host is running the Kernel PF driver (ixgbe or i40e).
65
66 The ip address of host_server_1 is 10.237.212.46
67
68 The ip address of host_server_2 is 10.237.212.131
69
70 Live Migration steps
71 --------------------
72
73 The sample scripts mentioned in the steps below can be found in the
74 :ref:`Sample host scripts <lm_bond_virtio_sriov_host_scripts>` and
75 :ref:`Sample VM scripts <lm_bond_virtio_sriov_vm_scripts>` sections.
76
77 On host_server_1: Terminal 1
78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79
80 .. code-block:: console
81
82    cd /root/dpdk/host_scripts
83    ./setup_vf_on_212_46.sh
84
85 For Fortville NIC
86
87 .. code-block:: console
88
89    ./vm_virtio_vf_i40e_212_46.sh
90
91 For Niantic NIC
92
93 .. code-block:: console
94
95    ./vm_virtio_vf_one_212_46.sh
96
97 On host_server_1: Terminal 2
98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99
100 .. code-block:: console
101
102    cd /root/dpdk/host_scripts
103    ./setup_bridge_on_212_46.sh
104    ./connect_to_qemu_mon_on_host.sh
105    (qemu)
106
107 On host_server_1: Terminal 1
108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109
110 **In VM on host_server_1:**
111
112 .. code-block:: console
113
114    cd /root/dpdk/vm_scripts
115    ./setup_dpdk_in_vm.sh
116    ./run_testpmd_bonding_in_vm.sh
117
118    testpmd> show port info all
119
120 The ``mac_addr`` command only works with kernel PF for Niantic
121
122 .. code-block:: console
123
124    testpmd> mac_addr add port 1 vf 0 AA:BB:CC:DD:EE:FF
125
126 The syntax of the ``testpmd`` command is:
127
128 Create bonded device (mode) (socket).
129
130 Mode 1 is active backup.
131
132 Virtio is port 0 (P0).
133
134 VF is port 1 (P1).
135
136 Bonding is port 2 (P2).
137
138 .. code-block:: console
139
140    testpmd> create bonded device 1 0
141    Created new bonded device eth_bond_testpmd_0 on (port 2).
142    testpmd> add bonding slave 0 2
143    testpmd> add bonding slave 1 2
144    testpmd> show bonding config 2
145
146 The syntax of the ``testpmd`` command is:
147
148 set bonding primary (slave id) (port id)
149
150 Set primary to P1 before starting bonding port.
151
152 .. code-block:: console
153
154    testpmd> set bonding primary 1 2
155    testpmd> show bonding config 2
156    testpmd> port start 2
157    Port 2: 02:09:C0:68:99:A5
158    Checking link statuses...
159    Port 0 Link Up - speed 10000 Mbps - full-duplex
160    Port 1 Link Up - speed 10000 Mbps - full-duplex
161    Port 2 Link Up - speed 10000 Mbps - full-duplex
162
163    testpmd> show bonding config 2
164
165 Primary is now P1. There are 2 active slaves.
166
167 Use P2 only for forwarding.
168
169 .. code-block:: console
170
171    testpmd> set portlist 2
172    testpmd> show config fwd
173    testpmd> set fwd mac
174    testpmd> start
175    testpmd> show bonding config 2
176
177 Primary is now P1. There are 2 active slaves.
178
179 .. code-block:: console
180
181    testpmd> show port stats all
182
183 VF traffic is seen at P1 and P2.
184
185 .. code-block:: console
186
187    testpmd> clear port stats all
188    testpmd> set bonding primary 0 2
189    testpmd> remove bonding slave 1 2
190    testpmd> show bonding config 2
191
192 Primary is now P0. There is 1 active slave.
193
194 .. code-block:: console
195
196    testpmd> clear port stats all
197    testpmd> show port stats all
198
199 No VF traffic is seen at P0 and P2, VF MAC address still present.
200
201 .. code-block:: console
202
203    testpmd> port stop 1
204    testpmd> port close 1
205
206 Port close should remove VF MAC address, it does not remove perm_addr.
207
208 The ``mac_addr`` command only works with the kernel PF for Niantic.
209
210 .. code-block:: console
211
212    testpmd> mac_addr remove 1 AA:BB:CC:DD:EE:FF
213    testpmd> port detach 1
214    Port '0000:00:04.0' is detached. Now total ports is 2
215    testpmd> show port stats all
216
217 No VF traffic is seen at P0 and P2.
218
219 On host_server_1: Terminal 2
220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221
222 .. code-block:: console
223
224    (qemu) device_del vf1
225
226
227 On host_server_1: Terminal 1
228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229
230 **In VM on host_server_1:**
231
232 .. code-block:: console
233
234    testpmd> show bonding config 2
235
236 Primary is now P0. There is 1 active slave.
237
238 .. code-block:: console
239
240    testpmd> show port info all
241    testpmd> show port stats all
242
243 On host_server_2: Terminal 1
244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
245
246 .. code-block:: console
247
248    cd /root/dpdk/host_scripts
249    ./setup_vf_on_212_131.sh
250    ./vm_virtio_one_migrate.sh
251
252 On host_server_2: Terminal 2
253 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
254
255 .. code-block:: console
256
257    ./setup_bridge_on_212_131.sh
258    ./connect_to_qemu_mon_on_host.sh
259    (qemu) info status
260    VM status: paused (inmigrate)
261    (qemu)
262
263 On host_server_1: Terminal 2
264 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265
266 Check that the switch is up before migrating.
267
268 .. code-block:: console
269
270    (qemu) migrate tcp:10.237.212.131:5555
271    (qemu) info status
272    VM status: paused (postmigrate)
273
274 For the Niantic NIC.
275
276 .. code-block:: console
277
278    (qemu) info migrate
279    capabilities: xbzrle: off rdma-pin-all: off auto-converge: off zero-blocks: off
280    Migration status: completed
281    total time: 11834 milliseconds
282    downtime: 18 milliseconds
283    setup: 3 milliseconds
284    transferred ram: 389137 kbytes
285    throughput: 269.49 mbps
286    remaining ram: 0 kbytes
287    total ram: 1590088 kbytes
288    duplicate: 301620 pages
289    skipped: 0 pages
290    normal: 96433 pages
291    normal bytes: 385732 kbytes
292    dirty sync count: 2
293    (qemu) quit
294
295 For the Fortville NIC.
296
297 .. code-block:: console
298
299    (qemu) info migrate
300    capabilities: xbzrle: off rdma-pin-all: off auto-converge: off zero-blocks: off
301    Migration status: completed
302    total time: 11619 milliseconds
303    downtime: 5 milliseconds
304    setup: 7 milliseconds
305    transferred ram: 379699 kbytes
306    throughput: 267.82 mbps
307    remaining ram: 0 kbytes
308    total ram: 1590088 kbytes
309    duplicate: 303985 pages
310    skipped: 0 pages
311    normal: 94073 pages
312    normal bytes: 376292 kbytes
313    dirty sync count: 2
314    (qemu) quit
315
316 On host_server_2: Terminal 1
317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
318
319 **In VM on host_server_2:**
320
321    Hit Enter key. This brings the user to the testpmd prompt.
322
323 .. code-block:: console
324
325    testpmd>
326
327 On host_server_2: Terminal 2
328 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
329
330 .. code-block:: console
331
332    (qemu) info status
333    VM status: running
334
335 For the Niantic NIC.
336
337 .. code-block:: console
338
339    (qemu) device_add pci-assign,host=06:10.0,id=vf1
340
341 For the Fortville NIC.
342
343 .. code-block:: console
344
345    (qemu) device_add pci-assign,host=03:02.0,id=vf1
346
347 On host_server_2: Terminal 1
348 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
349
350 **In VM on host_server_2:**
351
352 .. code-block:: console
353
354    testomd> show port info all
355    testpmd> show port stats all
356    testpmd> show bonding config 2
357    testpmd> port attach 0000:00:04.0
358    Port 1 is attached.
359    Now total ports is 3
360    Done
361
362    testpmd> port start 1
363
364 The ``mac_addr`` command only works with the Kernel PF for Niantic.
365
366 .. code-block:: console
367
368    testpmd> mac_addr add port 1 vf 0 AA:BB:CC:DD:EE:FF
369    testpmd> show port stats all.
370    testpmd> show config fwd
371    testpmd> show bonding config 2
372    testpmd> add bonding slave 1 2
373    testpmd> set bonding primary 1 2
374    testpmd> show bonding config 2
375    testpmd> show port stats all
376
377 VF traffic is seen at P1 (VF) and P2 (Bonded device).
378
379 .. code-block:: console
380
381    testpmd> remove bonding slave 0 2
382    testpmd> show bonding config 2
383    testpmd> port stop 0
384    testpmd> port close 0
385    testpmd> port detach 0
386    Port '0000:00:03.0' is detached. Now total ports is 2
387
388    testpmd> show port info all
389    testpmd> show config fwd
390    testpmd> show port stats all
391
392 VF traffic is seen at P1 (VF) and P2 (Bonded device).
393
394 .. _lm_bond_virtio_sriov_host_scripts:
395
396 Sample host scripts
397 -------------------
398
399 setup_vf_on_212_46.sh
400 ~~~~~~~~~~~~~~~~~~~~~
401 Set up Virtual Functions on host_server_1
402
403 .. code-block:: sh
404
405    #!/bin/sh
406    # This script is run on the host 10.237.212.46 to setup the VF
407
408    # set up Niantic VF
409    cat /sys/bus/pci/devices/0000\:09\:00.0/sriov_numvfs
410    echo 1 > /sys/bus/pci/devices/0000\:09\:00.0/sriov_numvfs
411    cat /sys/bus/pci/devices/0000\:09\:00.0/sriov_numvfs
412    rmmod ixgbevf
413
414    # set up Fortville VF
415    cat /sys/bus/pci/devices/0000\:02\:00.0/sriov_numvfs
416    echo 1 > /sys/bus/pci/devices/0000\:02\:00.0/sriov_numvfs
417    cat /sys/bus/pci/devices/0000\:02\:00.0/sriov_numvfs
418    rmmod i40evf
419
420 vm_virtio_vf_one_212_46.sh
421 ~~~~~~~~~~~~~~~~~~~~~~~~~~
422
423 Setup Virtual Machine on host_server_1
424
425 .. code-block:: sh
426
427    #!/bin/sh
428
429    # Path to KVM tool
430    KVM_PATH="/usr/bin/qemu-system-x86_64"
431
432    # Guest Disk image
433    DISK_IMG="/home/username/disk_image/virt1_sml.disk"
434
435    # Number of guest cpus
436    VCPUS_NR="4"
437
438    # Memory
439    MEM=1536
440
441    taskset -c 1-5 $KVM_PATH \
442     -enable-kvm \
443     -m $MEM \
444     -smp $VCPUS_NR \
445     -cpu host \
446     -name VM1 \
447     -no-reboot \
448     -net none \
449     -vnc none -nographic \
450     -hda $DISK_IMG \
451     -netdev type=tap,id=net1,script=no,downscript=no,ifname=tap1 \
452     -device virtio-net-pci,netdev=net1,mac=CC:BB:BB:BB:BB:BB \
453     -device pci-assign,host=09:10.0,id=vf1 \
454     -monitor telnet::3333,server,nowait
455
456 setup_bridge_on_212_46.sh
457 ~~~~~~~~~~~~~~~~~~~~~~~~~
458
459 Setup bridge on host_server_1
460
461 .. code-block:: sh
462
463    #!/bin/sh
464    # This script is run on the host 10.237.212.46 to setup the bridge
465    # for the Tap device and the PF device.
466    # This enables traffic to go from the PF to the Tap to the Virtio PMD in the VM.
467
468    # ens3f0 is the Niantic NIC
469    # ens6f0 is the Fortville NIC
470
471    ifconfig ens3f0 down
472    ifconfig tap1 down
473    ifconfig ens6f0 down
474    ifconfig virbr0 down
475
476    brctl show virbr0
477    brctl addif virbr0 ens3f0
478    brctl addif virbr0 ens6f0
479    brctl addif virbr0 tap1
480    brctl show virbr0
481
482    ifconfig ens3f0 up
483    ifconfig tap1 up
484    ifconfig ens6f0 up
485    ifconfig virbr0 up
486
487 connect_to_qemu_mon_on_host.sh
488 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
489
490 .. code-block:: sh
491
492    #!/bin/sh
493    # This script is run on both hosts when the VM is up,
494    # to connect to the Qemu Monitor.
495
496    telnet 0 3333
497
498 setup_vf_on_212_131.sh
499 ~~~~~~~~~~~~~~~~~~~~~~
500
501 Set up Virtual Functions on host_server_2
502
503 .. code-block:: sh
504
505    #!/bin/sh
506    # This script is run on the host 10.237.212.131 to setup the VF
507
508    # set up Niantic VF
509    cat /sys/bus/pci/devices/0000\:06\:00.0/sriov_numvfs
510    echo 1 > /sys/bus/pci/devices/0000\:06\:00.0/sriov_numvfs
511    cat /sys/bus/pci/devices/0000\:06\:00.0/sriov_numvfs
512    rmmod ixgbevf
513
514    # set up Fortville VF
515    cat /sys/bus/pci/devices/0000\:03\:00.0/sriov_numvfs
516    echo 1 > /sys/bus/pci/devices/0000\:03\:00.0/sriov_numvfs
517    cat /sys/bus/pci/devices/0000\:03\:00.0/sriov_numvfs
518    rmmod i40evf
519
520 vm_virtio_one_migrate.sh
521 ~~~~~~~~~~~~~~~~~~~~~~~~
522
523 Setup Virtual Machine on host_server_2
524
525 .. code-block:: sh
526
527    #!/bin/sh
528    # Start the VM on host_server_2 with the same parameters except without the VF
529    # parameters, as the VM on host_server_1, in migration-listen mode
530    # (-incoming tcp:0:5555)
531
532    # Path to KVM tool
533    KVM_PATH="/usr/bin/qemu-system-x86_64"
534
535    # Guest Disk image
536    DISK_IMG="/home/username/disk_image/virt1_sml.disk"
537
538    # Number of guest cpus
539    VCPUS_NR="4"
540
541    # Memory
542    MEM=1536
543
544    taskset -c 1-5 $KVM_PATH \
545     -enable-kvm \
546     -m $MEM \
547     -smp $VCPUS_NR \
548     -cpu host \
549     -name VM1 \
550     -no-reboot \
551     -net none \
552     -vnc none -nographic \
553     -hda $DISK_IMG \
554     -netdev type=tap,id=net1,script=no,downscript=no,ifname=tap1 \
555     -device virtio-net-pci,netdev=net1,mac=CC:BB:BB:BB:BB:BB \
556     -incoming tcp:0:5555 \
557     -monitor telnet::3333,server,nowait
558
559 setup_bridge_on_212_131.sh
560 ~~~~~~~~~~~~~~~~~~~~~~~~~~
561
562 Setup bridge on host_server_2
563
564 .. code-block:: sh
565
566    #!/bin/sh
567    # This script is run on the host to setup the bridge
568    # for the Tap device and the PF device.
569    # This enables traffic to go from the PF to the Tap to the Virtio PMD in the VM.
570
571    # ens4f0 is the Niantic NIC
572    # ens5f0 is the Fortville NIC
573
574    ifconfig ens4f0 down
575    ifconfig tap1 down
576    ifconfig ens5f0 down
577    ifconfig virbr0 down
578
579    brctl show virbr0
580    brctl addif virbr0 ens4f0
581    brctl addif virbr0 ens5f0
582    brctl addif virbr0 tap1
583    brctl show virbr0
584
585    ifconfig ens4f0 up
586    ifconfig tap1 up
587    ifconfig ens5f0 up
588    ifconfig virbr0 up
589
590 .. _lm_bond_virtio_sriov_vm_scripts:
591
592 Sample VM scripts
593 -----------------
594
595 setup_dpdk_in_vm.sh
596 ~~~~~~~~~~~~~~~~~~~
597
598 Set up DPDK in the Virtual Machine
599
600 .. code-block:: sh
601
602    #!/bin/sh
603    # this script matches the vm_virtio_vf_one script
604    # virtio port is 03
605    # vf port is 04
606
607    cat  /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
608    echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
609    cat  /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
610
611    ifconfig -a
612    /root/dpdk/tools/dpdk_nic_bind.py --status
613
614    rmmod virtio-pci ixgbevf
615
616    modprobe uio
617    insmod /root/dpdk/x86_64-default-linuxapp-gcc/kmod/igb_uio.ko
618
619    /root/dpdk/tools/dpdk_nic_bind.py -b igb_uio 0000:00:03.0
620    /root/dpdk/tools/dpdk_nic_bind.py -b igb_uio 0000:00:04.0
621
622    /root/dpdk/tools/dpdk_nic_bind.py --status
623
624 run_testpmd_bonding_in_vm.sh
625 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
626
627 Run testpmd in the Virtual Machine.
628
629 .. code-block:: sh
630
631    #!/bin/sh
632    # Run testpmd in the VM
633
634    # The test system has 8 cpus (0-7), use cpus 2-7 for VM
635    # Use taskset -pc <core number> <thread_id>
636
637    # use for bonding of virtio and vf tests in VM
638
639    /root/dpdk/x86_64-default-linuxapp-gcc/app/testpmd \
640    -c f -n 4 --socket-mem 350 --  --i --port-topology=chained
641
642 .. _lm_bond_virtio_sriov_switch_conf:
643
644 Sample switch configuration
645 ---------------------------
646
647 The Intel switch is used to connect the traffic generator to the
648 NIC's on host_server_1 and host_server_2.
649
650 In order to run the switch configuration two console windows are required.
651
652 Log in as root in both windows.
653
654 TestPointShared, run_switch.sh and load /root/switch_config must be executed
655 in the sequence below.
656
657 On Switch: Terminal 1
658 ~~~~~~~~~~~~~~~~~~~~~
659
660 run TestPointShared
661
662 .. code-block:: console
663
664    /usr/bin/TestPointShared
665
666 On Switch: Terminal 2
667 ~~~~~~~~~~~~~~~~~~~~~
668
669 execute run_switch.sh
670
671 .. code-block:: console
672
673    /root/run_switch.sh
674
675 On Switch: Terminal 1
676 ~~~~~~~~~~~~~~~~~~~~~
677
678 load switch configuration
679
680 .. code-block:: console
681
682    load /root/switch_config
683
684 Sample switch configuration script
685 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
686
687 The ``/root/switch_config`` script:
688
689 .. code-block:: sh
690
691    # TestPoint History
692    show port 1,5,9,13,17,21,25
693    set port 1,5,9,13,17,21,25 up
694    show port 1,5,9,13,17,21,25
695    del acl 1
696    create acl 1
697    create acl-port-set
698    create acl-port-set
699    add port port-set 1 0
700    add port port-set 5,9,13,17,21,25 1
701    create acl-rule 1 1
702    add acl-rule condition 1 1 port-set 1
703    add acl-rule action 1 1 redirect 1
704    apply acl
705    create vlan 1000
706    add vlan port 1000 1,5,9,13,17,21,25
707    set vlan tagging 1000 1,5,9,13,17,21,25 tag
708    set switch config flood_ucast fwd
709    show port stats all 1,5,9,13,17,21,25