doc/guides/sample_app_ug/vhost_blk.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2017 Intel Corporation.
   3
   4 Vhost_blk Sample Application
   5 =============================
   6
   7 The vhost_blk sample application implemented a simple block device,
   8 which used as the  backend of Qemu vhost-user-blk device. Users can extend
   9 the exist example to use other type of block device(e.g. AIO) besides
  10 memory based block device. Similar with vhost-user-net device, the sample
  11 application used domain socket to communicate with Qemu, and the virtio
  12 ring (split or packed format) was processed by vhost_blk sample application.
  13
  14 The sample application reuse lots codes from SPDK(Storage Performance
  15 Development Kit, https://github.com/spdk/spdk) vhost-user-blk target,
  16 for DPDK vhost library used in storage area, user can take SPDK as
  17 reference as well.
  18
  19 Testing steps
  20 -------------
  21
  22 This section shows the steps how to start a VM with the block device as
  23 fast data path for critical application.
  24
  25 Compiling the Application
  26 -------------------------
  27
  28 To compile the sample application see :doc:`compiling`.
  29
  30 The application is located in the ``examples`` sub-directory.
  31
  32 You will also need to build DPDK both on the host and inside the guest
  33
  34 Start the vhost_blk example
  35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  36
  37 .. code-block:: console
  38
  39         ./vhost_blk -m 1024
  40
  41 .. _vhost_blk_app_run_vm:
  42
  43 Start the VM
  44 ~~~~~~~~~~~~
  45
  46 .. code-block:: console
  47
  48     qemu-system-x86_64 -machine accel=kvm \
  49         -m $mem -object memory-backend-file,id=mem,size=$mem,\
  50         mem-path=/dev/hugepages,share=on -numa node,memdev=mem \
  51         -drive file=os.img,if=none,id=disk \
  52         -device ide-hd,drive=disk,bootindex=0 \
  53         -chardev socket,id=char0,reconnect=1,path=/tmp/vhost.socket \
  54         -device vhost-user-blk-pci,packed=on,chardev=char0,num-queues=1 \
  55         ...
  56
  57 .. note::
  58     You must check whether your Qemu can support "vhost-user-blk" or not,
  59     Qemu v4.0 or newer version is required.
  60     reconnect=1 means live recovery support that qemu can reconnect vhost_blk
  61     after we restart vhost_blk example.
  62     packed=on means the device support packed ring but need the guest kernel
  63     version >= 5.0.
  64     Now Qemu commit 9bb73502321d46f4d320fa17aa38201445783fc4 both support the
  65     vhost-blk reconnect and packed ring.