From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by dpdk.org (Postfix) with ESMTP id 90138493D for ; Sat, 5 May 2018 20:46:58 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga105.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 05 May 2018 11:46:58 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.49,366,1520924400"; d="scan'208";a="47005775" Received: from unknown (HELO localhost.localdomain) ([10.224.122.195]) by FMSMGA003.fm.intel.com with ESMTP; 05 May 2018 11:46:54 -0700 From: Abhinandan Gujjar To: jerin.jacob@caviumnetworks.com, hemant.agrawal@nxp.com, akhil.goyal@nxp.com, dev@dpdk.org Cc: narender.vangati@intel.com, abhinandan.gujjar@intel.com, nikhil.rao@intel.com, gage.eads@intel.com Date: Sun, 6 May 2018 00:17:10 +0530 Message-Id: <1525546030-11204-6-git-send-email-abhinandan.gujjar@intel.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1525546030-11204-1-git-send-email-abhinandan.gujjar@intel.com> References: <1525546030-11204-1-git-send-email-abhinandan.gujjar@intel.com> Subject: [dpdk-dev] [v3,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: , X-List-Received-Date: Sat, 05 May 2018 18:47:00 -0000 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 | 1 + doc/api/doxy-api-index.md | 1 + doc/guides/prog_guide/event_crypto_adapter.rst | 244 +++++ .../img/event_crypto_adapter_op_forward.svg | 1073 ++++++++++++++++++++ .../prog_guide/img/event_crypto_adapter_op_new.svg | 968 ++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + doc/guides/rel_notes/release_18_05.rst | 6 + 7 files changed, 2294 insertions(+) create mode 100644 doc/guides/prog_guide/event_crypto_adapter.rst create mode 100644 doc/guides/prog_guide/img/event_crypto_adapter_op_forward.svg create mode 100644 doc/guides/prog_guide/img/event_crypto_adapter_op_new.svg diff --git a/MAINTAINERS b/MAINTAINERS index 60ebef7..ea5dc40 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -367,6 +367,7 @@ 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 diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 26ce7b4..0162bb7 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -21,6 +21,7 @@ The public API headers are grouped by topics: [eventdev] (@ref rte_eventdev.h), [event_eth_rx_adapter] (@ref rte_event_eth_rx_adapter.h), [event_timer_adapter] (@ref rte_event_timer_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..899f393 --- /dev/null +++ b/doc/guides/prog_guide/event_crypto_adapter.rst @@ -0,0 +1,244 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Intel Corporation. + +Event Crypto Adapter Library +============================ + +The DPDK Event device library :doc:``provides event driven +programming model with features to schedule events. The cryptodev +library :doc:`` 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 crypto device. + +The packet flow from crypto device 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 crypto device 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_OP_NEW`` or +``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode. +In the first mode, application submits crypto operations directly to the crypto device. +Adapter only dequeues crypto completions and enqueues them as events to the event device. + +.. figure:: img/event_crypto_adapter_op_new.* + +In the second mode, application enqueues crypto operations as events to the event device. +The crypto adapter dequeues events and submits crypto operations to the crypto device. +After the crypto completions, adapter enqueues them as events to the event device. + +.. figure:: img/event_crypto_adapter_op_forward.* + +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, id; + struct rte_event_dev_info dev_info; + struct rte_event_port_conf conf; + enum rte_event_crypto_adapter_mode mode; + + 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; + mode = RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD; + err = rte_event_crypto_adapter_create(id, dev_id, &conf, mode); + +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. + +For OP_FORWARD mode, the event port created by adapter can be retrieved using +``rte_event_crypto_adapter_event_port_get()`` API. +Application can use this event port to link with event queue on which it +enqueues events towards the crypto adapter. + +.. code-block:: c + + uint8_t id, evdev, crypto_ev_port_id, app_qid; + struct rte_event ev; + int ret; + + ret = rte_event_crypto_adapter_event_port_get(id, &crypto_ev_port_id); + ret = rte_event_queue_setup(evdev, app_qid, NULL); + ret = rte_event_port_link(evdev, crypto_ev_port_id, &app_qid, NULL, 1); + + /* Fill in event info and update event_ptr with rte_crypto_op */ + memset(&ev, 0, sizeof(ev)); + ev.queue_id = app_qid; + . + . + ev.event_ptr = op; + ret = rte_event_enqueue_burst(evdev, app_ev_port_id, ev, nb_events); + + +Adding queue pair to the adapter instance +----------------------------------------- + +Cryptodev device id and queue pair are created using cryptodev APIs. +For more information see :doc:`here `. + +.. code-block:: c + + struct rte_cryptodev_config conf; + struct rte_cryptodev_qp_conf qp_conf; + uint8_t cdev_id = 0; + 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 + + struct rte_event_crypto_queue_pair_conf conf; + + rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, &conf); + + +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 OP_FORWARD 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 OP_NEW 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. The +RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA capability indicates +whether HW or SW supports this feature. + +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 + + union rte_event_crypto_metadata m_data; + struct rte_event ev; + struct rte_crypto_op *op; + + /* Allocate & fill op structure */ + op = rte_crypto_op_alloc(); + + memset(&m_data, 0, sizeof(m_data)); + memset(&ev, 0, sizeof(ev)); + /* Fill event information and update event_ptr to rte_crypto_op */ + ev.event_ptr = op; + + if (op->sess_type == RTE_CRYPTO_OP_WITH_SESSION) { + /* Copy response information */ + rte_memcpy(&m_data.response_info, &ev, sizeof(ev)); + /* Copy request information */ + m_data.request_info.cdev_id = cdev_id; + m_data.request_info.queue_pair_id = qp_id; + /* Call set API to store private data information */ + rte_cryptodev_sym_session_set_private_data( + op->sym->session, + &m_data, + sizeof(m_data)); + } if (op->sess_type == RTE_CRYPTO_OP_SESSIONLESS) { + uint32_t len = IV_OFFSET + MAXIMUM_IV_LENGTH + + (sizeof(struct rte_crypto_sym_xform) * 2); + op->private_data_offset = len; + /* Copy response information */ + rte_memcpy(&m_data.response_info, &ev, sizeof(ev)); + /* Copy request information */ + m_data.request_info.cdev_id = cdev_id; + m_data.request_info.queue_pair_id = qp_id; + /* Store private data information along with rte_crypto_op */ + 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 + + 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/img/event_crypto_adapter_op_forward.svg b/doc/guides/prog_guide/img/event_crypto_adapter_op_forward.svg new file mode 100644 index 0000000..38be6a2 --- /dev/null +++ b/doc/guides/prog_guide/img/event_crypto_adapter_op_forward.svg @@ -0,0 +1,1073 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + Square + Atomic Queue #1 + + + + + + + + + + + + + + + + + + Square + Atomic Queue #1 + + + + + + + + + + + + + + + + + + + + + + 1 + + + 2 + + + + 8 + + + + + 7 + + + + + 3 + + + + 4 + + + 5 + + + Square + Atomic Queue #1 + + + + + + + + + + + + + + + + Square + Atomic Queue #1 + + + + + + + + + + + + + + + + + + 6 + + + Eventdev + + + CryptoAdapter + + + Orderedstage + + + Cryptodev + + + 1. Events from the previous stage.2. Application in ordered stage dequeues events from eventdev.3. Application enqueues crypto operations as events to eventdev.4. Crypto adapter dequeues event from eventdev.5. Crypto adapter submits crypto operations to cryptodev (Atomic stage)6. Crypto adapter dequeues crypto completions from cryptodev7. Crypto adapter enqueues events to the eventdev8. Events to the next stage + + + diff --git a/doc/guides/prog_guide/img/event_crypto_adapter_op_new.svg b/doc/guides/prog_guide/img/event_crypto_adapter_op_new.svg new file mode 100644 index 0000000..c87321f --- /dev/null +++ b/doc/guides/prog_guide/img/event_crypto_adapter_op_new.svg @@ -0,0 +1,968 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + Square + Atomic Queue #1 + + + + + + + + + + + + + + + + Square + Atomic Queue #1 + + + + + + + + + + + + + + + + Square + Atomic Queue #1 + + + + + + + + + + + + + + + + + Square + Atomic Queue #1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 1 + + + 2 + + + + + 3 + + + 4 + + + 6 + + + Eventdev + + + Atomic stage+enqueue tocryptodev + + + 5 + + + Cryptodev + + + Cryptoadapter + + + 1. Events from the previous stage2. Application in atomic stage dequeues events from eventdev.3. Crypto operations are submitted to cryptodev.4. Crypto adapter dequeues crypto completions from cryptodev5. Crypto adapter enqueues events to the eventdev6. Events to the next stage + + + diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 235ad02..8a38c37 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -44,6 +44,7 @@ Programmer's Guide eventdev event_ethernet_rx_adapter event_timer_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 0ae61e8..79e60d1 100644 --- a/doc/guides/rel_notes/release_18_05.rst +++ b/doc/guides/rel_notes/release_18_05.rst @@ -16,6 +16,12 @@ DPDK Release 18.05 xdg-open build/doc/html/guides/rel_notes/release_18_05.html +* **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. New Features ------------ -- 1.9.1