xref: /dpdk/doc/guides/sample_app_ug/vhost_blk.rst (revision e2a94f9ad3ef949c0df3e63699bd4e381b5003d9) 
1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2010-2017 Intel Corporation.
3
4Vhost_blk Sample Application
5=============================
6
7The vhost_blk sample application implemented a simple block device,
8which used as the  backend of Qemu vhost-user-blk device. Users can extend
9the exist example to use other type of block device(e.g. AIO) besides
10memory based block device. Similar with vhost-user-net device, the sample
11application used domain socket to communicate with Qemu, and the virtio
12ring (split or packed format) was processed by vhost_blk sample application.
13
14The sample application reuse lots codes from SPDK(Storage Performance
15Development Kit, https://github.com/spdk/spdk) vhost-user-blk target,
16for DPDK vhost library used in storage area, user can take SPDK as
17reference as well.
18
19Testing steps
20-------------
21
22This section shows the steps how to start a VM with the block device as
23fast data path for critical application.
24
25Compiling the Application
26-------------------------
27
28To compile the sample application see :doc:`compiling`.
29
30The application is located in the ``examples`` sub-directory.
31
32You will also need to build DPDK both on the host and inside the guest
33
34Start the vhost_blk example
35~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36
37.. code-block:: console
38
39        ./dpdk-vhost_blk -m 1024
40
41.. _vhost_blk_app_run_vm:
42
43Start 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.
66