[dpdk-dev] [dpdk-dev, v1, 5/5] doc: add event crypto adapter documentation
Abhinandan Gujjar
abhinandan.gujjar at intel.com
Wed Apr 4 08:57:27 CEST 2018
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 <abhinandan.gujjar at intel.com>
---
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 <abhinandan.gujjar at intel.com>
+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 <shreyansh.jain at nxp.com>
M: Hemant Agrawal <hemant.agrawal at nxp.com>
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 '<http://dpdk.org/doc/guides/prog_guide/eventdev.html>`_
+provides event driven programming model with features to schedule events.
+The cryptodev library '<http://dpdk.org/doc/guides/prog_guide/cryptodev_lib.html>`_
+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 '<http://dpdk.org/doc/guides/prog_guide/cryptodev_lib.html>`_.
+
+.. 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
-----------
--
1.9.1
More information about the dev
mailing list