From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id E3D371C0DF for ; Wed, 4 Apr 2018 12:16:41 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 04 Apr 2018 03:16:41 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.48,405,1517904000"; d="scan'208";a="213819473" Received: from silpixa00398673.ir.intel.com (HELO silpixa00398673.ger.corp.intel.com) ([10.237.223.54]) by orsmga005.jf.intel.com with ESMTP; 04 Apr 2018 03:16:39 -0700 From: Fan Zhang To: dev@dpdk.org Cc: jianjay.zhou@huawei.com, roy.fan.zhang@intel.com, maxime.coquelin@redhat.com, jianfeng.tan@intel.com, pawelx.wodkowski@intel.com Date: Wed, 4 Apr 2018 11:09:02 +0100 Message-Id: <20180404100902.27637-9-roy.fan.zhang@intel.com> X-Mailer: git-send-email 2.13.6 In-Reply-To: <20180404100902.27637-1-roy.fan.zhang@intel.com> References: <1522327975-28769-1-git-send-email-roy.fan.zhang@intel.com> <20180404100902.27637-1-roy.fan.zhang@intel.com> Subject: [dpdk-dev] [PATCH v5 8/8] doc: update for vhost crypto support X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 04 Apr 2018 10:16:43 -0000 Signed-off-by: Fan Zhang --- doc/guides/prog_guide/vhost_lib.rst | 25 ++++++++++ doc/guides/rel_notes/release_18_05.rst | 5 ++ doc/guides/sample_app_ug/index.rst | 1 + doc/guides/sample_app_ug/vhost_crypto.rst | 83 +++++++++++++++++++++++++++++++ 4 files changed, 114 insertions(+) create mode 100644 doc/guides/sample_app_ug/vhost_crypto.rst diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst index f47473609..04ab1eeb4 100644 --- a/doc/guides/prog_guide/vhost_lib.rst +++ b/doc/guides/prog_guide/vhost_lib.rst @@ -160,6 +160,31 @@ The following is an overview of some key Vhost API functions: Receives (dequeues) ``count`` packets from guest, and stored them at ``pkts``. +* ``rte_vhost_crypto_create(vid, cryptodev_id, sess_mempool, socket_id)`` + + As an extension of new_device(), this function adds virtio-crypto workload + acceleration capability to the device. All crypto workload is processed by + DPDK cryptodev with the device ID of ``cryptodev_id``. + +* ``rte_vhost_crypto_free(vid)`` + + Frees the memory and vhost-user message handlers created in + rte_vhost_crypto_create(). + +* ``rte_vhost_crypto_fetch_requests(vid, queue_id, ops, nb_ops)`` + + Receives (dequeues) ``nb_ops`` virtio-crypto requests from guest, parses + them to DPDK Crypto Operations, and fills the ``ops`` with parsing results. + +* ``rte_vhost_crypto_finalize_requests(queue_id, ops, nb_ops)`` + + After the ``ops`` are dequeued from Cryptodev, finalizes the jobs and + notifies the guest(s). + +* ``rte_vhost_crypto_set_zero_copy(vid, option)`` + + Enable or disable zero copy feature of the vhost crypto backend. + Vhost-user Implementations -------------------------- diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst index 9cc77f893..6451f8ea0 100644 --- a/doc/guides/rel_notes/release_18_05.rst +++ b/doc/guides/rel_notes/release_18_05.rst @@ -58,6 +58,11 @@ New Features * Added support for NVGRE, VXLAN and GENEVE filters in flow API. * Added support for DROP action in flow API. +* **Added crypto workload support to vhost library + + New APIs are introduced in vhost library to enable virtio crypto support + including session creation/deletion handling and translating virito-crypto + request into DPDK crypto operations. A sample application is also introduced. API Changes ----------- diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index e87afda80..57e8354d4 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -44,6 +44,7 @@ Sample Applications User Guides vmdq_dcb_forwarding vhost vhost_scsi + vhost_crypto netmap_compatibility ip_pipeline test_pipeline diff --git a/doc/guides/sample_app_ug/vhost_crypto.rst b/doc/guides/sample_app_ug/vhost_crypto.rst new file mode 100644 index 000000000..316988738 --- /dev/null +++ b/doc/guides/sample_app_ug/vhost_crypto.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017-2018 Intel Corporation. + +Vhost_Crypto Sample Application +=============================== + +The vhost_crypto sample application implemented a simple Crypto device, +which used as the backend of Qemu vhost-user-crypto device. Similar with +vhost-user-net and vhost-user-scsi device, the sample application used +domain socket to communicate with Qemu, and the virtio ring was processed +by vhost_crypto sample application. + +Testing steps +------------- + +This section shows the steps how to start a VM with the crypto device as +fast data path for critical application. + +Compiling the Application +------------------------- + +To compile the sample application see :doc:`compiling`. + +The application is located in the ``examples`` sub-directory. + +Start the vhost_crypto example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + ./vhost_crypto [EAL options] -- [--socket-file PATH] + [--cdev-id ID] [--cdev-queue-id ID] [--zero-copy] [--guest-polling] + +where, + +* socket-file PATH: the path of UNIX socket file to be created, multiple + instances of this config item is supported. Upon absence of this item, + the default socket-file `/tmp/vhost_crypto1.socket` is used. + +* cdev-id ID: the target DPDK Cryptodev's ID to process the actual crypto + workload. Upon absence of this item the default value of `0` will be used. + For details of DPDK Cryptodev, please refer to DPDK Cryptodev Library + Programmers' Guide. + +* cdev-queue-id ID: the target DPDK Cryptodev's queue ID to process the + actual crypto workload. Upon absence of this item the default value of `0` + will be used. For details of DPDK Cryptodev, please refer to DPDK Cryptodev + Library Programmers' Guide. + +* zero-copy: the presence of this item means the ZERO-COPY feature will be + enabled. Otherwise it is disabled. PLEASE NOTE the ZERO-COPY feature is still + in experimental stage and may cause the problem like segmentation fault. If + the user wants to use LKCF in the guest, this feature shall be turned off. + +* guest-polling: the presence of this item means the application assumes the + guest works in polling mode, thus will NOT notify the guest completion of + processing. + +The application requires that crypto devices capable of performing +the specified crypto operation are available on application initialization. +This means that HW crypto device/s must be bound to a DPDK driver or +a SW crypto device/s (virtual crypto PMD) must be created (using --vdev). + +.. _vhost_crypto_app_run_vm: + +Start the VM +~~~~~~~~~~~~ + +.. code-block:: console + + qemu-system-x86_64 -machine accel=kvm \ + -m $mem -object memory-backend-file,id=mem,size=$mem,\ + mem-path=/dev/hugepages,share=on -numa node,memdev=mem \ + -drive file=os.img,if=none,id=disk \ + -device ide-hd,drive=disk,bootindex=0 \ + -chardev socket,id={chardev_id},path={PATH} \ + -object cryptodev-vhost-user,id={obj_id},chardev={chardev_id} \ + -device virtio-crypto-pci,id={dev_id},cryptodev={obj_id} \ + ... + +.. note:: + You must check whether your Qemu can support "vhost-user-crypto" or not. + -- 2.13.6