1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017-2018 Intel Corporation. 3 4Vhost_Crypto Sample Application 5=============================== 6 7The vhost_crypto sample application implemented a simple Crypto device, 8which used as the backend of Qemu vhost-user-crypto device. Similar with 9vhost-user-net and vhost-user-scsi device, the sample application used 10domain socket to communicate with Qemu, and the virtio ring was processed 11by vhost_crypto sample application. 12 13Testing steps 14------------- 15 16This section shows the steps how to start a VM with the crypto device as 17fast data path for critical application. 18 19Compiling the Application 20------------------------- 21 22To compile the sample application see :doc:`compiling`. 23 24The application is located in the ``examples`` sub-directory. 25 26Start 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 34where, 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 59The application requires that crypto devices capable of performing 60the specified crypto operation are available on application initialization. 61This means that HW crypto device/s must be bound to a DPDK driver or 62a SW crypto device/s (virtual crypto PMD) must be created (using --vdev). 63 64.. _vhost_crypto_app_run_vm: 65 66Start 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. 83