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] --
  32                 --config (lcore,cdev-id,queue-id)[,(lcore,cdev-id,queue-id)]
  33                 --socket-file lcore,PATH
  34                 [--zero-copy]
  35                 [--guest-polling]
  36
  37 where,
  38
  39 * config (lcore,cdev-id,queue-id): build the lcore-cryptodev id-queue id
  40   connection. Once specified, the specified lcore will only work with
  41   specified cryptodev's queue.
  42
  43 * socket-file lcore,PATH: the path of UNIX socket file to be created and
  44   the lcore id that will deal with the all workloads of the socket. Multiple
  45   instances of this config item is supported and one lcore supports processing
  46   multiple sockets.
  47
  48 * zero-copy: the presence of this item means the ZERO-COPY feature will be
  49   enabled. Otherwise it is disabled. PLEASE NOTE the ZERO-COPY feature is still
  50   in experimental stage and may cause the problem like segmentation fault. If
  51   the user wants to use LKCF in the guest, this feature shall be turned off.
  52
  53 * guest-polling: the presence of this item means the application assumes the
  54   guest works in polling mode, thus will NOT notify the guest completion of
  55   processing.
  56
  57 The application requires that crypto devices capable of performing
  58 the specified crypto operation are available on application initialization.
  59 This means that HW crypto device/s must be bound to a DPDK driver or
  60 a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
  61
  62 .. _vhost_crypto_app_run_vm:
  63
  64 Start the VM
  65 ~~~~~~~~~~~~
  66
  67 .. code-block:: console
  68
  69     qemu-system-x86_64 -machine accel=kvm \
  70         -m $mem -object memory-backend-file,id=mem,size=$mem,\
  71         mem-path=/dev/hugepages,share=on -numa node,memdev=mem \
  72         -drive file=os.img,if=none,id=disk \
  73         -device ide-hd,drive=disk,bootindex=0 \
  74         -chardev socket,id={chardev_id},path={PATH} \
  75         -object cryptodev-vhost-user,id={obj_id},chardev={chardev_id} \
  76         -device virtio-crypto-pci,id={dev_id},cryptodev={obj_id} \
  77         ...
  78
  79 .. note::
  80     You must check whether your Qemu can support "vhost-user-crypto" or not.