[dpdk-dev] [v3, 5/5] doc: add event crypto adapter documentation
Jerin Jacob
jerin.jacob at caviumnetworks.com
Mon May 7 14:27:42 CEST 2018
-----Original Message-----
> Date: Sun, 6 May 2018 00:17:10 +0530
> From: Abhinandan Gujjar <abhinandan.gujjar at intel.com>
> To: jerin.jacob at caviumnetworks.com, hemant.agrawal at nxp.com,
> akhil.goyal at nxp.com, dev at dpdk.org
> CC: narender.vangati at intel.com, abhinandan.gujjar at intel.com,
> nikhil.rao at intel.com, gage.eads at intel.com
> Subject: [v3,5/5] doc: add event crypto adapter documentation
> X-Mailer: git-send-email 1.9.1
>
> 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>
Adding documentation maintainers for review.
+ john.mcnamara at intel.com
+ marko.kovacevic at intel.com
> ---
> 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 <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>
> 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:`<eventdev>`provides event driven
> +programming model with features to schedule events. The cryptodev
> +library :doc:`<cryptodev_lib>` 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.
This portion you can update from header file comments.
---
> +
> +.. 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.
We need talk about OP_FORWARD capability here. This portion you can update
from header file comments.
> +After the crypto completions, adapter enqueues them as events to the event device.
> +
> +.. figure:: img/event_crypto_adapter_op_forward.*
Diagram text you can update from from header file comments.
> +
> +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
s/OP_FORWARD/RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD/
> +``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.
Here you can describe if the PMD has RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD capability then
what could be the difference in application.
> +
> +.. 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 <cryptodev_lib>`.
IMO, we need to talk about EV_BIND capability here before using queue_pair_add()
> +
> +.. 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()``.
With above comments:
Acked-by: Jerin Jacob <jerin.jacob at caviumnetworks.com>
NOTE:
Wednesday morning the last deadline for RC3 pull request, If we can
address the comments from all parties(including NXP) before that then
we can push that in RC3.
/Jerin
More information about the dev
mailing list