doc/guides/sample_app_ug/vhost_scsi.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2017 Intel Corporation.
   3
   4 Vhost_scsi Sample Application
   5 =============================
   6
   7 The vhost_scsi sample application implemented a simple SCSI block device,
   8 which used as the  backend of Qemu vhost-user-scsi 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 was processed by vhost_scsi sample application.
  13
  14 The sample application reuse lots codes from SPDK(Storage Performance
  15 Development Kit, https://github.com/spdk/spdk) vhost-user-scsi 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_scsi example
  35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  36
  37 .. code-block:: console
  38
  39         ./vhost_scsi -m 1024
  40
  41 .. _vhost_scsi_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,path=/tmp/vhost.socket \
  54         -device vhost-user-scsi-pci,chardev=char0,bootindex=2 \
  55         ...
  56
  57 .. note::
  58     You must check whether your Qemu can support "vhost-user-scsi" or not,
  59     Qemu v2.10 or newer version is required.
  60
  61 Vhost_scsi Common Issues
  62 ------------------------
  63
  64 * vhost_scsi can not start with block size 512 Bytes:
  65
  66   Currently DPDK vhost library was designed for NET device(althrough the APIs
  67   are generic now), for 512 Bytes block device, Qemu BIOS(x86 BIOS Enhanced
  68   Disk Device) will enumerate all block device and do some IOs to those block
  69   devices with 512 Bytes sector size. DPDK vhost library can not process such
  70   scenarios(both BIOS and OS will enumerate the block device), so as a
  71   workaround, the vhost_scsi example application hardcoded the block size
  72   with 4096 Bytes.
  73
  74 * vhost_scsi can only support the block device as fast data disk(non OS image):
  75
  76   Make sure ``bootindex=2`` Qemu option is given to vhost-user-scsi-pci device.
  77