1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2018 Intel Corporation. All rights reserved. 3 4Event Crypto Adapter Library 5============================ 6 7The DPDK :doc:`Eventdev library <eventdev>` provides event driven 8programming model with features to schedule events. 9The :doc:`../cryptodev_lib` provides an interface to 10the crypto poll mode drivers which supports different crypto operations. 11The Event Crypto Adapter is one of the adapter which is intended to 12bridge between the event device and the crypto device. 13 14The packet flow from crypto device to the event device can be accomplished 15using SW and HW based transfer mechanism. 16The Adapter queries an eventdev PMD to determine which mechanism to be used. 17The adapter uses an EAL service core function for SW based packet transfer 18and uses the eventdev PMD functions to configure HW based packet transfer 19between the crypto device and the event device. The crypto adapter uses a new 20event type called ``RTE_EVENT_TYPE_CRYPTODEV`` to indicate the event source. 21 22The application can choose to submit a crypto operation directly to 23crypto device or send it to the crypto adapter via eventdev based on 24RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability. 25The first mode is known as the event new(RTE_EVENT_CRYPTO_ADAPTER_OP_NEW) 26mode and the second as the event forward(RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD) 27mode. The choice of mode can be specified while creating the adapter. 28In the former mode, it is an application responsibility to enable ingress 29packet ordering. In the latter mode, it is the adapter responsibility to 30enable the ingress packet ordering. 31 32 33Adapter Mode 34------------ 35 36RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode 37~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 38 39In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, application submits crypto 40operations directly to crypto device. The adapter then dequeues crypto 41completions from crypto device and enqueues them as events to the event device. 42This mode does not ensure ingress ordering, if the application directly 43enqueues to the cryptodev without going through crypto/atomic stage. 44In this mode, events dequeued from the adapter will be treated as new events. 45The application needs to specify event information (response information) 46which is needed to enqueue an event after the crypto operation is completed. 47 48.. _figure_event_crypto_adapter_op_new: 49 50.. figure:: ../img/event_crypto_adapter_op_new.* 51 52 Working model of ``RTE_EVENT_CRYPTO_ADAPTER_OP_NEW`` mode 53 54 55RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode 56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 57 58In the ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode, if the event PMD and crypto 59PMD supports internal event port 60(``RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD``), the application should 61use ``rte_event_crypto_adapter_enqueue()`` API to enqueue crypto operations as 62events to crypto adapter. If not, application retrieves crypto adapter's event 63port using ``rte_event_crypto_adapter_event_port_get()`` API, links its event 64queue to this port and starts enqueuing crypto operations as events to eventdev 65using ``rte_event_enqueue_burst()``. The adapter then dequeues the events and 66submits the crypto operations to the cryptodev. After the crypto operation is 67complete, the adapter enqueues events to the event device. The application can 68use this mode when ingress packet ordering is needed. In this mode, events 69dequeued from the adapter will be treated as forwarded events. The application 70needs to specify the cryptodev ID and queue pair ID (request information) needed 71to enqueue a crypto operation in addition to the event information (response 72information) needed to enqueue an event after the crypto operation has 73completed. 74 75.. _figure_event_crypto_adapter_op_forward: 76 77.. figure:: ../img/event_crypto_adapter_op_forward.* 78 79 Working model of ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode 80 81 82API Overview 83------------ 84 85This section has a brief introduction to the event crypto adapter APIs. 86The application is expected to create an adapter which is associated with 87a single eventdev, then add cryptodev and queue pair to the adapter instance. 88 89Create an adapter instance 90~~~~~~~~~~~~~~~~~~~~~~~~~~ 91 92An adapter instance is created using ``rte_event_crypto_adapter_create()``. This 93function is called with event device to be associated with the adapter and port 94configuration for the adapter to setup an event port(if the adapter needs to use 95a service function). 96 97Adapter can be started in ``RTE_EVENT_CRYPTO_ADAPTER_OP_NEW`` or 98``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode. 99 100.. code-block:: c 101 102 int err; 103 uint8_t dev_id, id; 104 struct rte_event_dev_info dev_info; 105 struct rte_event_port_conf conf; 106 enum rte_event_crypto_adapter_mode mode; 107 108 err = rte_event_dev_info_get(id, &dev_info); 109 110 conf.new_event_threshold = dev_info.max_num_events; 111 conf.dequeue_depth = dev_info.max_event_port_dequeue_depth; 112 conf.enqueue_depth = dev_info.max_event_port_enqueue_depth; 113 mode = RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD; 114 err = rte_event_crypto_adapter_create(id, dev_id, &conf, mode); 115 116If the application desires to have finer control of eventdev port allocation 117and setup, it can use the ``rte_event_crypto_adapter_create_ext()`` function. 118The ``rte_event_crypto_adapter_create_ext()`` function is passed as a callback 119function. The callback function is invoked if the adapter needs to use a 120service function and needs to create an event port for it. The callback is 121expected to fill the ``struct rte_event_crypto_adapter_conf`` structure 122passed to it. 123 124In the ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode, if the event PMD and crypto 125PMD supports internal event port 126(``RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD``), events with crypto 127operations should be enqueued to the crypto adapter using 128``rte_event_crypto_adapter_enqueue()`` API. If not, the event port created by 129the adapter can be retrieved using ``rte_event_crypto_adapter_event_port_get()`` 130API. An application can use this event port to link with an event queue, on 131which it enqueues events towards the crypto adapter using 132``rte_event_enqueue_burst()``. 133 134.. code-block:: c 135 136 uint8_t id, evdev_id, cdev_id, crypto_ev_port_id, app_qid; 137 struct rte_event ev; 138 uint32_t cap; 139 int ret; 140 141 // Fill in event info and update event_ptr with rte_crypto_op 142 memset(&ev, 0, sizeof(ev)); 143 . 144 . 145 ev.event_ptr = op; 146 147 ret = rte_event_crypto_adapter_caps_get(evdev_id, cdev_id, &cap); 148 if (cap & RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD) { 149 ret = rte_event_crypto_adapter_enqueue(evdev_id, app_ev_port_id, 150 ev, nb_events); 151 } else { 152 ret = rte_event_crypto_adapter_event_port_get(id, 153 &crypto_ev_port_id); 154 ret = rte_event_queue_setup(evdev_id, app_qid, NULL); 155 ret = rte_event_port_link(evdev_id, crypto_ev_port_id, &app_qid, 156 NULL, 1); 157 ev.queue_id = app_qid; 158 ret = rte_event_enqueue_burst(evdev_id, app_ev_port_id, ev, 159 nb_events); 160 } 161 162Event device configuration for service based adapter 163~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 164 165When ``rte_event_crypto_adapter_create()`` is used for creating 166adapter instance, ``rte_event_dev_config::nb_event_ports`` is 167automatically incremented, and event device is reconfigured 168with additional event port during service initialization. 169This event device reconfigure logic also increments the 170``rte_event_dev_config::nb_single_link_event_port_queues`` 171parameter if the adapter event port config is of type 172``RTE_EVENT_PORT_CFG_SINGLE_LINK``. 173 174Application no longer needs to configure the 175event device with ``rte_event_dev_config::nb_event_ports`` and 176``rte_event_dev_config::nb_single_link_event_port_queues`` 177parameters required for crypto adapter when the adapter is created 178using the above-mentioned API. 179 180Querying adapter capabilities 181~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 182 183The ``rte_event_crypto_adapter_caps_get()`` function allows 184the application to query the adapter capabilities for an eventdev and cryptodev 185combination. This API provides whether cryptodev and eventdev are connected using 186internal HW port or not. 187 188.. code-block:: c 189 190 rte_event_crypto_adapter_caps_get(dev_id, cdev_id, &cap); 191 192Adding queue pair to the adapter instance 193~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 194 195Cryptodev device id and queue pair are created using cryptodev APIs. 196For more information see :doc:`here <../cryptodev_lib>`. 197 198.. code-block:: c 199 200 struct rte_cryptodev_config conf; 201 struct rte_cryptodev_qp_conf qp_conf; 202 uint8_t cdev_id = 0; 203 uint16_t qp_id = 0; 204 205 rte_cryptodev_configure(cdev_id, &conf); 206 rte_cryptodev_queue_pair_setup(cdev_id, qp_id, &qp_conf); 207 208These cryptodev id and queue pair are added to the instance using the 209``rte_event_crypto_adapter_queue_pair_add()`` API. 210The same is removed using ``rte_event_crypto_adapter_queue_pair_del()`` API. 211If HW supports RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND 212capability, event information must be passed to the add API. 213 214.. code-block:: c 215 216 uint32_t cap; 217 int ret; 218 219 ret = rte_event_crypto_adapter_caps_get(id, evdev, &cap); 220 if (cap & RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND) { 221 struct rte_event_crypto_adapter_queue_conf conf; 222 223 // Fill in conf.event information & pass it to add API 224 rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, &conf); 225 } else 226 rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, NULL); 227 228Configure the service function 229~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 230 231If the adapter uses a service function, the application is required to assign 232a service core to the service function as show below. 233 234.. code-block:: c 235 236 uint32_t service_id; 237 238 if (rte_event_crypto_adapter_service_id_get(id, &service_id) == 0) 239 rte_service_map_lcore_set(service_id, CORE_ID); 240 241Set event request/response information 242~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 243 244In the RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode, the application needs 245to specify the cryptodev ID and queue pair ID (request information) in 246addition to the event information (response information) needed to enqueue 247an event after the crypto operation has completed. The request and response 248information are specified in the ``struct rte_crypto_op`` private data or 249session's private data. 250 251In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, the application is required 252to provide only the response information. 253 254The SW adapter or HW PMD uses ``rte_crypto_op::sess_type`` to 255decide whether request/response data is located in the crypto session/ 256crypto security session or at an offset in the ``struct rte_crypto_op``. 257The ``rte_crypto_op::private_data_offset`` is used to locate the request/ 258response in the ``rte_crypto_op``. 259 260For crypto session, ``rte_cryptodev_sym_session_set_user_data()`` API 261will be used to set request/response data. The same data will be obtained 262by ``rte_cryptodev_sym_session_get_user_data()`` API. The 263RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA capability indicates 264whether HW or SW supports this feature. 265 266For security session, ``rte_security_session_set_private_data()`` API 267will be used to set request/response data. The same data will be obtained 268by ``rte_security_session_get_private_data()`` API. 269 270For session-less it is mandatory to place the request/response data with 271the ``rte_crypto_op``. 272 273.. code-block:: c 274 275 union rte_event_crypto_metadata m_data; 276 struct rte_event ev; 277 struct rte_crypto_op *op; 278 279 /* Allocate & fill op structure */ 280 op = rte_crypto_op_alloc(); 281 282 memset(&m_data, 0, sizeof(m_data)); 283 memset(&ev, 0, sizeof(ev)); 284 /* Fill event information and update event_ptr to rte_crypto_op */ 285 ev.event_ptr = op; 286 287 if (op->sess_type == RTE_CRYPTO_OP_WITH_SESSION) { 288 /* Copy response information */ 289 rte_memcpy(&m_data.response_info, &ev, sizeof(ev)); 290 /* Copy request information */ 291 m_data.request_info.cdev_id = cdev_id; 292 m_data.request_info.queue_pair_id = qp_id; 293 /* Call set API to store private data information */ 294 rte_cryptodev_sym_session_set_user_data( 295 op->sym->session, 296 &m_data, 297 sizeof(m_data)); 298 } if (op->sess_type == RTE_CRYPTO_OP_SESSIONLESS) { 299 uint32_t len = IV_OFFSET + MAXIMUM_IV_LENGTH + 300 (sizeof(struct rte_crypto_sym_xform) * 2); 301 op->private_data_offset = len; 302 /* Copy response information */ 303 rte_memcpy(&m_data.response_info, &ev, sizeof(ev)); 304 /* Copy request information */ 305 m_data.request_info.cdev_id = cdev_id; 306 m_data.request_info.queue_pair_id = qp_id; 307 /* Store private data information along with rte_crypto_op */ 308 rte_memcpy(op + len, &m_data, sizeof(m_data)); 309 } 310 311Enable event vectorization 312~~~~~~~~~~~~~~~~~~~~~~~~~~ 313 314The event crypto adapter can aggregate outcoming crypto operations based on 315provided response information of ``rte_event_crypto_metadata::response_info`` 316and generate a ``rte_event`` containing ``rte_event_vector`` whose event type 317is ``RTE_EVENT_TYPE_CRYPTODEV_VECTOR``. 318To enable vectorization application should set 319RTE_EVENT_CRYPTO_ADAPTER_EVENT_VECTOR in 320``rte_event_crypto_adapter_queue_conf::flag`` and provide vector 321configuration(size, mempool, etc.) with respect of 322``rte_event_crypto_adapter_vector_limits``, which could be obtained by calling 323``rte_event_crypto_adapter_vector_limits_get()``. 324 325The RTE_EVENT_CRYPTO_ADAPTER_CAP_EVENT_VECTOR capability indicates whether 326PMD supports this feature. 327 328Start the adapter instance 329~~~~~~~~~~~~~~~~~~~~~~~~~~ 330 331The application calls ``rte_event_crypto_adapter_start()`` to start the adapter. 332This function calls the start callbacks of the eventdev PMDs for hardware based 333eventdev-cryptodev connections and ``rte_service_run_state_set()`` to enable the 334service function if one exists. 335 336.. code-block:: c 337 338 rte_event_crypto_adapter_start(id, mode); 339 340.. Note:: 341 342 The eventdev to which the event_crypto_adapter is connected needs to 343 be started before calling rte_event_crypto_adapter_start(). 344 345Get adapter statistics 346~~~~~~~~~~~~~~~~~~~~~~ 347 348The ``rte_event_crypto_adapter_stats_get()`` function reports counters defined 349in struct ``rte_event_crypto_adapter_stats``. The received packet and 350enqueued event counts are a sum of the counts from the eventdev PMD callbacks 351if the callback is supported, and the counts maintained by the service function, 352if one exists. 353 354Set/Get adapter runtime configuration parameters 355~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 356 357The runtime configuration parameters of adapter can be set/get using 358``rte_event_crypto_adapter_runtime_params_set()`` and 359``rte_event_crypto_adapter_runtime_params_get()`` respectively. 360The parameters that can be set/get are defined in 361``struct rte_event_crypto_adapter_runtime_params``. 362