New upstream version 18.08upstream/18.08

Change-Id: I32fdf5e5016556d9c0a6d88ddaf1fc468961790a
Signed-off-by: Luca Boccassi <luca.boccassi@gmail.com>

1 files changed, 296 insertions, 0 deletions

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 00000000..9fe09c80
--- /dev/null
+++ b/doc/guides/prog_guide/event_crypto_adapter.rst
@@ -0,0 +1,296 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation. All rights reserved.
+
+Event Crypto Adapter Library
+============================
+
+The DPDK :doc:`Eventdev library <eventdev>` provides event driven
+programming model with features to schedule events.
+The :doc:`Cryptodev library <cryptodev_lib>` provides an interface to
+the crypto poll mode drivers which supports different crypto operations.
+The Event Crypto Adapter is one of the adapter which is intended to
+bridge between the event device and the crypto device.
+
+The packet flow from crypto device to the event device can be accomplished
+using SW and HW based transfer mechanism.
+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. The crypto adapter uses a new
+event type called ``RTE_EVENT_TYPE_CRYPTODEV`` to indicate the event source.
+
+The application can choose to submit a crypto operation directly to
+crypto device or send it to the crypto adapter via eventdev based on
+RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
+The first mode is known as the event new(RTE_EVENT_CRYPTO_ADAPTER_OP_NEW)
+mode and the second as the event forward(RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD)
+mode. The choice of mode can be specified while creating the adapter.
+In the former mode, it is an application responsibility to enable ingress
+packet ordering. In the latter mode, it is the adapter responsibility to
+enable the ingress packet ordering.
+
+
+Adapter Mode
+------------
+
+RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, application submits crypto
+operations directly to crypto device. The adapter then dequeues crypto
+completions from crypto device and enqueues them as events to the event device.
+This mode does not ensure ingress ordering, if the application directly
+enqueues to the cryptodev without going through crypto/atomic stage.
+In this mode, events dequeued from the adapter will be treated as new events.
+The application needs to specify event information (response information)
+which is needed to enqueue an event after the crypto operation is completed.
+
+.. _figure_event_crypto_adapter_op_new:
+
+.. figure:: img/event_crypto_adapter_op_new.*
+
+   Working model of ``RTE_EVENT_CRYPTO_ADAPTER_OP_NEW`` mode
+
+
+RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode, if HW supports
+RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability the application
+can directly submit the crypto operations to the cryptodev.
+If not, application retrieves crypto adapter's event port using
+rte_event_crypto_adapter_event_port_get() API. Then, links its event
+queue to this port and starts enqueuing crypto operations as events
+to the eventdev. The adapter then dequeues the events and submits the
+crypto operations to the cryptodev. After the crypto completions, the
+adapter enqueues events to the event device.
+Application can use this mode, when ingress packet ordering is needed.
+In this mode, events dequeued from the adapter will be treated as
+forwarded events. The application needs to specify the cryptodev ID
+and queue pair ID (request information) needed to enqueue a crypto
+operation in addition to the event information (response information)
+needed to enqueue an event after the crypto operation has completed.
+
+.. _figure_event_crypto_adapter_op_forward:
+
+.. figure:: img/event_crypto_adapter_op_forward.*
+
+   Working model of ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode
+
+
+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.
+
+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).
+
+Adapter can be started in ``RTE_EVENT_CRYPTO_ADAPTER_OP_NEW`` or
+``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode.
+
+.. 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 RTE_EVENT_CRYPTO_ADAPTER_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);
+
+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);
+
+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>`.
+
+.. 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()`` API.
+The same is removed using ``rte_event_crypto_adapter_queue_pair_del()`` API.
+If HW supports RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND
+capability, event information must be passed to the add API.
+
+.. code-block:: c
+
+        uint32_t cap;
+        int ret;
+
+        ret = rte_event_crypto_adapter_caps_get(id, evdev, &cap);
+        if (cap & RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND) {
+                struct rte_event event;
+
+                // Fill in event information & pass it to add API
+                rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, &event);
+        } else
+                rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, NULL);
+
+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 RTE_EVENT_CRYPTO_ADAPTER_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 RTE_EVENT_CRYPTO_ADAPTER_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_user_data()`` API
+will be used to set request/response data. The same data will be obtained
+by ``rte_cryptodev_sym_session_get_user_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_user_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.