doc/guides/sample_app_ug/vdpa.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 Vdpa Sample Application
   5 =======================
   6
   7 The vdpa sample application creates vhost-user sockets by using the
   8 vDPA backend. vDPA stands for vhost Data Path Acceleration which utilizes
   9 virtio ring compatible devices to serve virtio driver directly to enable
  10 datapath acceleration. As vDPA driver can help to set up vhost datapath,
  11 this application doesn't need to launch dedicated worker threads for vhost
  12 enqueue/dequeue operations.
  13
  14 Testing steps
  15 -------------
  16
  17 This section shows the steps of how to start VMs with vDPA vhost-user
  18 backend and verify network connection & live migration.
  19
  20 Build
  21 ~~~~~
  22
  23 To compile the sample application see :doc:`compiling`.
  24
  25 The application is located in the ``vdpa`` sub-directory.
  26
  27 Start the vdpa example
  28 ~~~~~~~~~~~~~~~~~~~~~~
  29
  30 .. code-block:: console
  31
  32         ./vdpa [EAL options]  -- [--client] [--interactive|-i] or [--iface SOCKET_PATH]
  33
  34 where
  35
  36 * --client means running vdpa app in client mode, in the client mode, QEMU needs
  37   to run as the server mode and take charge of socket file creation.
  38 * --iface specifies the path prefix of the UNIX domain socket file, e.g.
  39   /tmp/vhost-user-, then the socket files will be named as /tmp/vhost-user-<n>
  40   (n starts from 0).
  41 * --interactive means run the vdpa sample in interactive mode, currently 4
  42   internal cmds are supported:
  43
  44   1. help: show help message
  45   2. list: list all available vdpa devices
  46   3. create: create a new vdpa port with socket file and vdpa device address
  47   4. quit: unregister vhost driver and exit the application
  48
  49 Take IFCVF driver for example:
  50
  51 .. code-block:: console
  52
  53         ./vdpa -c 0x2 -n 4 --socket-mem 1024,1024 \
  54                 -w 0000:06:00.3,vdpa=1 -w 0000:06:00.4,vdpa=1 \
  55                 -- --interactive
  56
  57 .. note::
  58     Here 0000:06:00.3 and 0000:06:00.4 refer to virtio ring compatible devices,
  59     and we need to bind vfio-pci to them before running vdpa sample.
  60
  61     * modprobe vfio-pci
  62     * ./usertools/dpdk-devbind.py -b vfio-pci 06:00.3 06:00.4
  63
  64 Then we can create 2 vdpa ports in interactive cmdline.
  65
  66 .. code-block:: console
  67
  68         vdpa> list
  69         device id       device address  queue num       supported features
  70         0               0000:06:00.3    1               0x14c238020
  71         1               0000:06:00.4    1               0x14c238020
  72         2               0000:06:00.5    1               0x14c238020
  73
  74         vdpa> create /tmp/vdpa-socket0 0000:06:00.3
  75         vdpa> create /tmp/vdpa-socket1 0000:06:00.4
  76
  77 .. _vdpa_app_run_vm:
  78
  79 Start the VMs
  80 ~~~~~~~~~~~~~
  81
  82 .. code-block:: console
  83
  84        qemu-system-x86_64 -cpu host -enable-kvm \
  85        <snip>
  86        -mem-prealloc \
  87        -chardev socket,id=char0,path=<socket_file created in above steps> \
  88        -netdev type=vhost-user,id=vdpa,chardev=char0 \
  89        -device virtio-net-pci,netdev=vdpa,mac=00:aa:bb:cc:dd:ee,page-per-vq=on \
  90
  91 After the VMs launches, we can login the VMs and configure the ip, verify the
  92 network connection via ping or netperf.
  93
  94 .. note::
  95     Suggest to use QEMU 3.0.0 which extends vhost-user for vDPA.
  96
  97 Live Migration
  98 ~~~~~~~~~~~~~~
  99 vDPA supports cross-backend live migration, user can migrate SW vhost backend
 100 VM to vDPA backend VM and vice versa. Here are the detailed steps. Assume A is
 101 the source host with SW vhost VM and B is the destination host with vDPA.
 102
 103 1. Start vdpa sample and launch a VM with exact same parameters as the VM on A,
 104    in migration-listen mode:
 105
 106 .. code-block:: console
 107
 108         B: <qemu-command-line> -incoming tcp:0:4444 (or other PORT))
 109
 110 2. Start the migration (on source host):
 111
 112 .. code-block:: console
 113
 114         A: (qemu) migrate -d tcp:<B ip>:4444 (or other PORT)
 115
 116 3. Check the status (on source host):
 117
 118 .. code-block:: console
 119
 120         A: (qemu) info migrate