From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga17.intel.com (mga17.intel.com [192.55.52.151]) by dpdk.org (Postfix) with ESMTP id 4DF074C95 for ; Tue, 24 Apr 2018 14:43:24 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga107.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 24 Apr 2018 05:43:21 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.49,323,1520924400"; d="scan'208";a="222936040" Received: from unknown (HELO localhost.localdomain) ([10.224.122.195]) by fmsmga006.fm.intel.com with ESMTP; 24 Apr 2018 05:43:18 -0700 From: Abhinandan Gujjar 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 Date: Tue, 24 Apr 2018 18:13:27 +0530 Message-Id: <1524573807-168522-7-git-send-email-abhinandan.gujjar@intel.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1524573807-168522-1-git-send-email-abhinandan.gujjar@intel.com> References: <1524573807-168522-1-git-send-email-abhinandan.gujjar@intel.com> Subject: [dpdk-dev] [v2,6/6] doc: add event crypto adapter documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 24 Apr 2018 12:43:24 -0000 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 --- MAINTAINERS | 7 + doc/api/doxy-api-index.md | 1 + doc/guides/prog_guide/event_crypto_adapter.rst | 236 +++++++++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + doc/guides/rel_notes/release_18_05.rst | 6 + 5 files changed, 251 insertions(+) create mode 100644 doc/guides/prog_guide/event_crypto_adapter.rst diff --git a/MAINTAINERS b/MAINTAINERS index 4ba316b..f13a4b5 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -356,6 +356,13 @@ F: lib/librte_eventdev/*timer_adapter* F: test/test/test_event_timer_adapter.c F: doc/guides/prog_guide/event_timer_adapter.rst +Eventdev Crypto Adapter API - EXPERIMENTAL +M: Abhinandan Gujjar +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 M: Hemant Agrawal 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..76d95b3 --- /dev/null +++ b/doc/guides/prog_guide/event_crypto_adapter.rst @@ -0,0 +1,236 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Intel Corporation. + +Event Crypto Adapter Library +============================ + +The DPDK Event device library '`_ +provides event driven programming model with features to schedule events. +The cryptodev library '`_ +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, 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_ENQ_DEQ; + 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 ENQ-DEQ mode, the event port created by adapter can be retrived using +``rte_event_crypto_adapter_event_port_get()`` API. +Application can use this event port to link with event queue on which it +enqueue 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); + + +Adding queue pair to the adapter instance +----------------------------------------- + +Cryptodev device id and queue pair are created using cryptodev APIs. +Refer '`_. + +.. 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()``. + +.. code-block:: c + + struct rte_event_crypto_queue_pair_conf conf; + + rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, &conf); + + +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 + + 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_private_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. diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 589c05d..c2ef87f 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -43,6 +43,7 @@ Programmer's Guide eventdev event_ethernet_rx_adapter event_timer_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 391a0d4..0ba7013 100644 --- a/doc/guides/rel_notes/release_18_05.rst +++ b/doc/guides/rel_notes/release_18_05.rst @@ -77,6 +77,12 @@ New Features timer expiry events. This new type of event is scheduled by an event device along with existing types of events. +* **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