Re: [v3, 5/5] doc: add event crypto adapter documentation

[Jerin Jacob <jerin.jacob@caviumnetworks.com>]

-----Original Message-----
> Date: Sun, 6 May 2018 00:17:10 +0530
> From: Abhinandan Gujjar <abhinandan.gujjar@intel.com>
> 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
> 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@intel.com>

Adding documentation maintainers for review.
+ john.mcnamara@intel.com
+ marko.kovacevic@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@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@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@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