From patchwork Wed Apr 4 06:57:27 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Gujjar, Abhinandan S" X-Patchwork-Id: 37080 X-Patchwork-Delegate: jerinj@marvell.com Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 723211BC4D; Wed, 4 Apr 2018 08:57:13 +0200 (CEST) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by dpdk.org (Postfix) with ESMTP id 5A6A21BBB3 for ; Wed, 4 Apr 2018 08:57:11 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga105.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Apr 2018 23:57:10 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.48,405,1517904000"; d="scan'208";a="47818127" Received: from unknown (HELO localhost.localdomain) ([10.224.122.195]) by orsmga002.jf.intel.com with ESMTP; 03 Apr 2018 23:57:06 -0700 From: Abhinandan Gujjar To: jerin.jacob@caviumnetworks.com, hemant.agrawal@nxp.com, akhil.goyal@nxp.com, dev@dpdk.org Cc: pablo.de.lara.guarch@intel.com, declan.doherty@intel.com, narender.vangati@intel.com, abhinandan.gujjar@intel.com, nikhil.rao@intel.com Date: Wed, 4 Apr 2018 12:27:27 +0530 Message-Id: <1522825047-61743-1-git-send-email-abhinandan.gujjar@intel.com> X-Mailer: git-send-email 1.9.1 Subject: [dpdk-dev] [dpdk-dev, v1, 5/5] doc: add event crypto adapter documentation 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: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Add entries in the programmer's guide, API index, maintainer's file and release notes for the event crypto adapter. Signed-off-by: Abhinandan Gujjar --- MAINTAINERS | 7 + doc/api/doxy-api-index.md | 1 + doc/guides/prog_guide/event_crypto_adapter.rst | 216 +++++++++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + doc/guides/rel_notes/release_18_05.rst | 6 + 5 files changed, 231 insertions(+) create mode 100644 doc/guides/prog_guide/event_crypto_adapter.rst diff --git a/MAINTAINERS b/MAINTAINERS index d4c0cc1..eb6b5b7 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -317,6 +317,13 @@ F: lib/librte_eventdev/*eth_rx_adapter* F: test/test/test_event_eth_rx_adapter.c F: doc/guides/prog_guide/event_ethernet_rx_adapter.rst +Eventdev Crypto Adapter API - EXPERIMENTAL +M: Abhinandan Gujjar +T: git://dpdk.org/next/dpdk-next-eventdev +F: lib/librte_eventdev/*crypto_adapter* +F: test/test/test_event_crypto_adapter.c +F: doc/guides/prog_guide/event_crypto_adapter.rst + Raw device API - EXPERIMENTAL M: Shreyansh Jain M: Hemant Agrawal diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index d77f205..56ecdc1 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -47,6 +47,7 @@ The public API headers are grouped by topics: [security] (@ref rte_security.h), [eventdev] (@ref rte_eventdev.h), [event_eth_rx_adapter] (@ref rte_event_eth_rx_adapter.h), + [event_crypto_adapter] (@ref rte_event_crypto_adapter.h), [rawdev] (@ref rte_rawdev.h), [metrics] (@ref rte_metrics.h), [bitrate] (@ref rte_bitrate.h), diff --git a/doc/guides/prog_guide/event_crypto_adapter.rst b/doc/guides/prog_guide/event_crypto_adapter.rst new file mode 100644 index 0000000..facf5ae --- /dev/null +++ b/doc/guides/prog_guide/event_crypto_adapter.rst @@ -0,0 +1,216 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Intel Corporation. + +Event Crypto Adapter Library +============================ + +The DPDK Event device library '`_ +provides event driven programming model with features to schedule events. +The cryptodev library '`_ +provides interface to crypto poll mode drivers which supports different crypto operations. +The Event Crypto Adapter is one of the event adapter which is intended to bridge between +event devices and cryptodev. + +The packet flow from cryptodev to the event device can be accomplished +using both SW and HW based transfer mechanisms. +The Adapter queries an eventdev PMD to determine which mechanism to be used. +The adapter uses an EAL service core function for SW based packet transfer +and uses the eventdev PMD functions to configure HW based packet transfer +between the cryptodev and the event device. + +Crypto adapter uses a new event type called ``RTE_EVENT_TYPE_CRYPTODEV`` +to indicate the event source. + +API Overview +------------ + +This section has a brief introduction to the event crypto adapter APIs. +The application is expected to create an adapter which is associated with +a single eventdev, then add cryptodev and queue pair to the adapter instance. + +Adapter can be started in ``RTE_EVENT_CRYPTO_ADAPTER_DEQ_ONLY`` or +``RTE_EVENT_CRYPTO_ADAPTER_ENQ_DEQ`` mode. +In first mode, application will submit a crypto operation directly to cryptodev. +In the second mode, application will send a crypto ops to cryptodev adapter +via eventdev. The cryptodev adapter then submits the crypto operation to the +crypto device. + +Create an adapter instance +-------------------------- + +An adapter instance is created using ``rte_event_crypto_adapter_create()``. This +function is called with event device to be associated with the adapter and port +configuration for the adapter to setup an event port(if the adapter needs to use +a service function). + +.. code-block:: c + + int err; + uint8_t dev_id; + struct rte_event_dev_info dev_info; + struct rte_event_port_conf conf; + + err = rte_event_dev_info_get(id, &dev_info); + + conf.new_event_threshold = dev_info.max_num_events; + conf.dequeue_depth = dev_info.max_event_port_dequeue_depth; + conf.enqueue_depth = dev_info.max_event_port_enqueue_depth; + err = rte_event_crypto_adapter_create(id, dev_id, &conf); + +If the application desires to have finer control of eventdev port allocation +and setup, it can use the ``rte_event_crypto_adapter_create_ext()`` function. +The ``rte_event_crypto_adapter_create_ext()`` function is passed as a callback +function. The callback function is invoked if the adapter needs to use a +service function and needs to create an event port for it. The callback is +expected to fill the ``struct rte_event_crypto_adapter_conf`` structure +passed to it. + +Adding queue pair to the adapter instance +----------------------------------------- + +Cryptodev device id and queue pair are created using cryptodev APIs. +Refer '`_. + +.. code-block:: c + + struct rte_cryptodev_config conf; + struct rte_cryptodev_qp_conf qp_conf; + uint8_t cdev_id; + uint16_t qp_id = 0; + + rte_cryptodev_configure(cdev_id, &conf); + rte_cryptodev_queue_pair_setup(cdev_id, qp_id, &qp_conf); + +These cryptodev id and queue pair are added to the instance using the +``rte_event_crypto_adapter_queue_pair_add()`` function. +The same is removed using ``rte_event_crypto_adapter_queue_pair_del()``. + +.. code-block:: c + + rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id); + + +Querying adapter capabilities +----------------------------- + +The ``rte_event_crypto_adapter_caps_get()`` function allows +the application to query the adapter capabilities for an eventdev and cryptodev +combination. This API provides whether cryptodev and eventdev are connected using +internal HW port or not. + +.. code-block:: c + + rte_event_crypto_adapter_caps_get(dev_id, cdev_id, &cap); + + +Configure the service function +------------------------------ + +If the adapter uses a service function, the application is required to assign +a service core to the service function as show below. + +.. code-block:: c + + uint32_t service_id; + + if (rte_event_crypto_adapter_service_id_get(id, &service_id) == 0) + rte_service_map_lcore_set(service_id, CORE_ID); + + +Set event request/response information +-------------------------------------- + +In the ENQ_DEQ mode, the application needs to specify the cryptodev ID +and queue pair ID (request information) in addition to the event +information (response information) needed to enqueue an event after +the crypto operation has completed. The request and response information +are specified in the ``struct rte_crypto_op`` private data or session's +private data. + +In the DEQ mode, the application is required to provide only the +response information. + +The SW adapter or HW PMD uses ``rte_crypto_op::sess_type`` to +decide whether request/response data is located in the crypto session/ +crypto security session or at an offset in the ``struct rte_crypto_op``. +The ``rte_crypto_op::private_data_offset`` is used to locate the request/ +response in the ``rte_crypto_op``. + +For crypto session, ``rte_cryptodev_sym_session_set_private_data()`` API +will be used to set request/response data. The same data will be obtained +by ``rte_cryptodev_sym_session_get_private_data()`` API. + +For security session, ``rte_security_session_set_private_data()`` API +will be used to set request/response data. The same data will be obtained +by ``rte_security_session_get_private_data()`` API. + +For session-less it is mandatory to place the request/response data with +the ``rte_crypto_op``. + +.. code-block:: c + + struct rte_event ev; + struct rte_crypto_op *op; + + op = rte_crypto_op_alloc(); + /* fill op structure */ + + memset(&ev, 0, sizeof(ev)); + ev.queue_id = EV_CRYPTO_QUEUE_ID; + ev.priority = 0; + ev.op = RTE_EVENT_OP_NEW; + ev.sched_type = RTE_SCHED_TYPE_ATOMIC; + ev.event_type = RTE_EVENT_TYPE_CRYPTODEV; + ev.sub_event_type = 0; + ev.flow_id = 0xFFFF; + ev.event_ptr = op; + + if (op->sess_type == RTE_CRYPTO_OP_WITH_SESSION) { + union rte_event_crypto_metadata m_data; + + memset(&m_data, 0, sizeof(m_data)); + rte_memcpy(&m_data.response_info, &ev, sizeof(m_data)); + m_data.request_info.cdev_id = cdev_id; + m_data.request_info.queue_pair_id = qp_id; + m_data.response_info.queue_id = EV_APP_QUEUE_ID; + rte_cryptodev_sym_session_set_private_data( + op->sym->session, + &m_data, + sizeof(m_data)); + } if (op->sess_type == RTE_CRYPTO_OP_SESSIONLESS) { + union rte_event_crypto_metadata m_data; + + memset(&m_data, 0, sizeof(m_data)); + uint32_t len = IV_OFFSET + MAXIMUM_IV_LENGTH + + (sizeof(struct rte_crypto_sym_xform) * 2); + op->private_data_offset = len; + rte_memcpy(&m_data.response_info, &ev, sizeof(m_data)); + m_data.request_info.cdev_id = cdev_id; + m_data.request_info.queue_pair_id = qp_id; + m_data.response_info.queue_id = EV_APP_QUEUE_ID; + rte_memcpy(op + len, &m_data, sizeof(m_data)); + } + +Start the adapter instance +-------------------------- + +The application calls ``rte_event_crypto_adapter_start()`` to start the adapter. +This function calls the start callbacks of the eventdev PMDs for hardware based +eventdev-cryptodev connections and ``rte_service_run_state_set()`` to enable the +service function if one exists. + +.. code-block:: c + enum rte_event_crypto_adapter_mode mode; + + mode = RTE_EVENT_CRYPTO_ADAPTER_ENQ_DEQ; + rte_event_crypto_adapter_start(id, mode); + + +Get adapter statistics +---------------------- + +The rte_event_crypto_adapter_stats_get()`` function reports counters defined +in struct ``rte_event_crypto_adapter_stats``. The received packet and +enqueued event counts are a sum of the counts from the eventdev PMD callbacks +if the callback is supported, and the counts maintained by the service function, +if one exists. diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index bbbe789..0de57f7 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -42,6 +42,7 @@ Programmer's Guide thread_safety_dpdk_functions eventdev event_ethernet_rx_adapter + event_crypto_adapter qos_framework power_man packet_classif_access_ctrl diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst index 9cc77f8..e6fef1d 100644 --- a/doc/guides/rel_notes/release_18_05.rst +++ b/doc/guides/rel_notes/release_18_05.rst @@ -58,6 +58,12 @@ New Features * Added support for NVGRE, VXLAN and GENEVE filters in flow API. * Added support for DROP action in flow API. +* **Added Event Crypto Adapter Library.** + + Added the Event Crypto Adapter Library. This library extends the + event-based model by introducing APIs that allow applications to + enqueue/dequeue crypto operations to/from cryptodev as events scheduled + by an event device. API Changes -----------