-----Original Message----- > Date: Sun, 6 May 2018 00:17:10 +0530 > From: Abhinandan Gujjar <abhinandan.guj...@intel.com> > To: jerin.ja...@caviumnetworks.com, hemant.agra...@nxp.com, > akhil.go...@nxp.com, dev@dpdk.org > CC: narender.vang...@intel.com, abhinandan.guj...@intel.com, > nikhil....@intel.com, gage.e...@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.guj...@intel.com>
Adding documentation maintainers for review. + john.mcnam...@intel.com + marko.kovace...@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.guj...@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.j...@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.ja...@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
