doc/guides/sample_app_ug/vhost_crypto.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017-2018 Intel Corporation.
   3
   4 Vhost_Crypto Sample Application
   5 ===============================
   6
   7 The vhost_crypto sample application implemented a simple Crypto device,
   8 which used as the  backend of Qemu vhost-user-crypto device. Similar with
   9 vhost-user-net and vhost-user-scsi device, the sample application used
  10 domain socket to communicate with Qemu, and the virtio ring was processed
  11 by vhost_crypto sample application.
  12
  13 Testing steps
  14 -------------
  15
  16 This section shows the steps how to start a VM with the crypto device as
  17 fast data path for critical application.
  18
  19 Compiling the Application
  20 -------------------------
  21
  22 To compile the sample application see :doc:`compiling`.
  23
  24 The application is located in the ``examples`` sub-directory.
  25
  26 Start the vhost_crypto example
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28
  29 .. code-block:: console
  30
  31     ./vhost_crypto [EAL options] -- [--socket-file PATH]
  32         [--cdev-id ID] [--cdev-queue-id ID] [--zero-copy] [--guest-polling]
  33
  34 where,
  35
  36 * socket-file PATH: the path of UNIX socket file to be created, multiple
  37   instances of this config item is supported. Upon absence of this item,
  38   the default socket-file `/tmp/vhost_crypto1.socket` is used.
  39
  40 * cdev-id ID: the target DPDK Cryptodev's ID to process the actual crypto
  41   workload. Upon absence of this item the default value of `0` will be used.
  42   For details of DPDK Cryptodev, please refer to DPDK Cryptodev Library
  43   Programmers' Guide.
  44
  45 * cdev-queue-id ID: the target DPDK Cryptodev's queue ID to process the
  46   actual crypto workload. Upon absence of this item the default value of `0`
  47   will be used. For details of DPDK Cryptodev, please refer to DPDK Cryptodev
  48   Library Programmers' Guide.
  49
  50 * zero-copy: the presence of this item means the ZERO-COPY feature will be
  51   enabled. Otherwise it is disabled. PLEASE NOTE the ZERO-COPY feature is still
  52   in experimental stage and may cause the problem like segmentation fault. If
  53   the user wants to use LKCF in the guest, this feature shall be turned off.
  54
  55 * guest-polling: the presence of this item means the application assumes the
  56   guest works in polling mode, thus will NOT notify the guest completion of
  57   processing.
  58
  59 The application requires that crypto devices capable of performing
  60 the specified crypto operation are available on application initialization.
  61 This means that HW crypto device/s must be bound to a DPDK driver or
  62 a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
  63
  64 .. _vhost_crypto_app_run_vm:
  65
  66 Start the VM
  67 ~~~~~~~~~~~~
  68
  69 .. code-block:: console
  70
  71     qemu-system-x86_64 -machine accel=kvm \
  72         -m $mem -object memory-backend-file,id=mem,size=$mem,\
  73         mem-path=/dev/hugepages,share=on -numa node,memdev=mem \
  74         -drive file=os.img,if=none,id=disk \
  75         -device ide-hd,drive=disk,bootindex=0 \
  76         -chardev socket,id={chardev_id},path={PATH} \
  77         -object cryptodev-vhost-user,id={obj_id},chardev={chardev_id} \
  78         -device virtio-crypto-pci,id={dev_id},cryptodev={obj_id} \
  79         ...
  80
  81 .. note::
  82     You must check whether your Qemu can support "vhost-user-crypto" or not.