doc/guides/prog_guide/event_crypto_adapter.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation. All rights reserved.
   3
   4 Event Crypto Adapter Library
   5 ============================
   6
   7 The DPDK :doc:`Eventdev library <eventdev>` provides event driven
   8 programming model with features to schedule events.
   9 The :doc:`Cryptodev library <cryptodev_lib>` provides an interface to
  10 the crypto poll mode drivers which supports different crypto operations.
  11 The Event Crypto Adapter is one of the adapter which is intended to
  12 bridge between the event device and the crypto device.
  13
  14 The packet flow from crypto device to the event device can be accomplished
  15 using SW and HW based transfer mechanism.
  16 The Adapter queries an eventdev PMD to determine which mechanism to be used.
  17 The adapter uses an EAL service core function for SW based packet transfer
  18 and uses the eventdev PMD functions to configure HW based packet transfer
  19 between the crypto device and the event device. The crypto adapter uses a new
  20 event type called ``RTE_EVENT_TYPE_CRYPTODEV`` to indicate the event source.
  21
  22 The application can choose to submit a crypto operation directly to
  23 crypto device or send it to the crypto adapter via eventdev based on
  24 RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
  25 The first mode is known as the event new(RTE_EVENT_CRYPTO_ADAPTER_OP_NEW)
  26 mode and the second as the event forward(RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD)
  27 mode. The choice of mode can be specified while creating the adapter.
  28 In the former mode, it is an application responsibility to enable ingress
  29 packet ordering. In the latter mode, it is the adapter responsibility to
  30 enable the ingress packet ordering.
  31
  32
  33 Adapter Mode
  34 ------------
  35
  36 RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode
  37 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38
  39 In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, application submits crypto
  40 operations directly to crypto device. The adapter then dequeues crypto
  41 completions from crypto device and enqueues them as events to the event device.
  42 This mode does not ensure ingress ordering, if the application directly
  43 enqueues to the cryptodev without going through crypto/atomic stage.
  44 In this mode, events dequeued from the adapter will be treated as new events.
  45 The application needs to specify event information (response information)
  46 which 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
  55 RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57
  58 In the ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode, if the event PMD and crypto
  59 PMD supports internal event port
  60 (``RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD``), the application should
  61 use ``rte_event_crypto_adapter_enqueue()`` API to enqueue crypto operations as
  62 events to crypto adapter. If not, application retrieves crypto adapter's event
  63 port using ``rte_event_crypto_adapter_event_port_get()`` API, links its event
  64 queue to this port and starts enqueuing crypto operations as events to eventdev
  65 using ``rte_event_enqueue_burst()``. The adapter then dequeues the events and
  66 submits the crypto operations to the cryptodev. After the crypto operation is
  67 complete, the adapter enqueues events to the event device. The application can
  68 use this mode when ingress packet ordering is needed. In this mode, events
  69 dequeued from the adapter will be treated as forwarded events. The application
  70 needs to specify the cryptodev ID and queue pair ID (request information) needed
  71 to enqueue a crypto operation in addition to the event information (response
  72 information) needed to enqueue an event after the crypto operation has
  73 completed.
  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
  82 API Overview
  83 ------------
  84
  85 This section has a brief introduction to the event crypto adapter APIs.
  86 The application is expected to create an adapter which is associated with
  87 a single eventdev, then add cryptodev and queue pair to the adapter instance.
  88
  89 Create an adapter instance
  90 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  91
  92 An adapter instance is created using ``rte_event_crypto_adapter_create()``. This
  93 function is called with event device to be associated with the adapter and port
  94 configuration for the adapter to setup an event port(if the adapter needs to use
  95 a service function).
  96
  97 Adapter 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
 116 If the application desires to have finer control of eventdev port allocation
 117 and setup, it can use the ``rte_event_crypto_adapter_create_ext()`` function.
 118 The ``rte_event_crypto_adapter_create_ext()`` function is passed as a callback
 119 function. The callback function is invoked if the adapter needs to use a
 120 service function and needs to create an event port for it. The callback is
 121 expected to fill the ``struct rte_event_crypto_adapter_conf`` structure
 122 passed to it.
 123
 124 In the ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode, if the event PMD and crypto
 125 PMD supports internal event port
 126 (``RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD``), events with crypto
 127 operations should be enqueued to the crypto adapter using
 128 ``rte_event_crypto_adapter_enqueue()`` API. If not, the event port created by
 129 the adapter can be retrieved using ``rte_event_crypto_adapter_event_port_get()``
 130 API. An application can use this event port to link with an event queue, on
 131 which 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
 162
 163 Querying adapter capabilities
 164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 165
 166 The ``rte_event_crypto_adapter_caps_get()`` function allows
 167 the application to query the adapter capabilities for an eventdev and cryptodev
 168 combination. This API provides whether cryptodev and eventdev are connected using
 169 internal HW port or not.
 170
 171 .. code-block:: c
 172
 173         rte_event_crypto_adapter_caps_get(dev_id, cdev_id, &cap);
 174
 175 Adding queue pair to the adapter instance
 176 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 177
 178 Cryptodev device id and queue pair are created using cryptodev APIs.
 179 For more information see :doc:`here  <cryptodev_lib>`.
 180
 181 .. code-block:: c
 182
 183         struct rte_cryptodev_config conf;
 184         struct rte_cryptodev_qp_conf qp_conf;
 185         uint8_t cdev_id = 0;
 186         uint16_t qp_id = 0;
 187
 188         rte_cryptodev_configure(cdev_id, &conf);
 189         rte_cryptodev_queue_pair_setup(cdev_id, qp_id, &qp_conf);
 190
 191 These cryptodev id and queue pair are added to the instance using the
 192 ``rte_event_crypto_adapter_queue_pair_add()`` API.
 193 The same is removed using ``rte_event_crypto_adapter_queue_pair_del()`` API.
 194 If HW supports RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND
 195 capability, event information must be passed to the add API.
 196
 197 .. code-block:: c
 198
 199         uint32_t cap;
 200         int ret;
 201
 202         ret = rte_event_crypto_adapter_caps_get(id, evdev, &cap);
 203         if (cap & RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND) {
 204                 struct rte_event event;
 205
 206                 // Fill in event information & pass it to add API
 207                 rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, &event);
 208         } else
 209                 rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, NULL);
 210
 211 Configure the service function
 212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 213
 214 If the adapter uses a service function, the application is required to assign
 215 a service core to the service function as show below.
 216
 217 .. code-block:: c
 218
 219         uint32_t service_id;
 220
 221         if (rte_event_crypto_adapter_service_id_get(id, &service_id) == 0)
 222                 rte_service_map_lcore_set(service_id, CORE_ID);
 223
 224 Set event request/response information
 225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 226
 227 In the RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode, the application needs
 228 to specify the cryptodev ID and queue pair ID (request information) in
 229 addition to the event information (response information) needed to enqueue
 230 an event after the crypto operation has completed. The request and response
 231 information are specified in the ``struct rte_crypto_op`` private data or
 232 session's private data.
 233
 234 In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, the application is required
 235 to provide only the response information.
 236
 237 The SW adapter or HW PMD uses ``rte_crypto_op::sess_type`` to
 238 decide whether request/response data is located in the crypto session/
 239 crypto security session or at an offset in the ``struct rte_crypto_op``.
 240 The ``rte_crypto_op::private_data_offset`` is used to locate the request/
 241 response in the ``rte_crypto_op``.
 242
 243 For crypto session, ``rte_cryptodev_sym_session_set_user_data()`` API
 244 will be used to set request/response data. The same data will be obtained
 245 by ``rte_cryptodev_sym_session_get_user_data()`` API.  The
 246 RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA capability indicates
 247 whether HW or SW supports this feature.
 248
 249 For security session, ``rte_security_session_set_private_data()`` API
 250 will be used to set request/response data. The same data will be obtained
 251 by ``rte_security_session_get_private_data()`` API.
 252
 253 For session-less it is mandatory to place the request/response data with
 254 the ``rte_crypto_op``.
 255
 256 .. code-block:: c
 257
 258         union rte_event_crypto_metadata m_data;
 259         struct rte_event ev;
 260         struct rte_crypto_op *op;
 261
 262         /* Allocate & fill op structure */
 263         op = rte_crypto_op_alloc();
 264
 265         memset(&m_data, 0, sizeof(m_data));
 266         memset(&ev, 0, sizeof(ev));
 267         /* Fill event information and update event_ptr to rte_crypto_op */
 268         ev.event_ptr = op;
 269
 270         if (op->sess_type == RTE_CRYPTO_OP_WITH_SESSION) {
 271                 /* Copy response information */
 272                 rte_memcpy(&m_data.response_info, &ev, sizeof(ev));
 273                 /* Copy request information */
 274                 m_data.request_info.cdev_id = cdev_id;
 275                 m_data.request_info.queue_pair_id = qp_id;
 276                 /* Call set API to store private data information */
 277                 rte_cryptodev_sym_session_set_user_data(
 278                         op->sym->session,
 279                         &m_data,
 280                         sizeof(m_data));
 281         } if (op->sess_type == RTE_CRYPTO_OP_SESSIONLESS) {
 282                 uint32_t len = IV_OFFSET + MAXIMUM_IV_LENGTH +
 283                                (sizeof(struct rte_crypto_sym_xform) * 2);
 284                 op->private_data_offset = len;
 285                 /* Copy response information */
 286                 rte_memcpy(&m_data.response_info, &ev, sizeof(ev));
 287                 /* Copy request information */
 288                 m_data.request_info.cdev_id = cdev_id;
 289                 m_data.request_info.queue_pair_id = qp_id;
 290                 /* Store private data information along with rte_crypto_op */
 291                 rte_memcpy(op + len, &m_data, sizeof(m_data));
 292         }
 293
 294 Start the adapter instance
 295 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 296
 297 The application calls ``rte_event_crypto_adapter_start()`` to start the adapter.
 298 This function calls the start callbacks of the eventdev PMDs for hardware based
 299 eventdev-cryptodev connections and ``rte_service_run_state_set()`` to enable the
 300 service function if one exists.
 301
 302 .. code-block:: c
 303
 304         rte_event_crypto_adapter_start(id, mode);
 305
 306 .. Note::
 307
 308          The eventdev to which the event_crypto_adapter is connected needs to
 309          be started before calling rte_event_crypto_adapter_start().
 310
 311 Get adapter statistics
 312 ~~~~~~~~~~~~~~~~~~~~~~
 313
 314 The  ``rte_event_crypto_adapter_stats_get()`` function reports counters defined
 315 in struct ``rte_event_crypto_adapter_stats``. The received packet and
 316 enqueued event counts are a sum of the counts from the eventdev PMD callbacks
 317 if the callback is supported, and the counts maintained by the service function,
 318 if one exists.