doc/guides/prog_guide/event_ethernet_rx_adapter.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation.
   3
   4 Event Ethernet Rx Adapter Library
   5 =================================
   6
   7 The DPDK Eventdev API allows the application to use an event driven programming
   8 model for packet processing. In this model, the application polls an event
   9 device port for receiving events that reference packets instead of polling Rx
  10 queues of ethdev ports. Packet transfer between ethdev and the event device can
  11 be supported in hardware or require a software thread to receive packets from
  12 the ethdev port using ethdev poll mode APIs and enqueue these as events to the
  13 event device using the eventdev API. Both transfer mechanisms may be present on
  14 the same platform depending on the particular combination of the ethdev and
  15 the event device.
  16
  17 The Event Ethernet Rx Adapter library is intended for the application code to
  18 configure both transfer mechanisms using a common API. A capability API allows
  19 the eventdev PMD to advertise features supported for a given ethdev and allows
  20 the application to perform configuration as per supported features.
  21
  22 API Walk-through
  23 ----------------
  24
  25 This section will introduce the reader to the adapter API. The
  26 application has to first instantiate an adapter which is associated with
  27 a single eventdev, next the adapter instance is configured with Rx queues
  28 that are either polled by a SW thread or linked using hardware support. Finally
  29 the adapter is started.
  30
  31 For SW based packet transfers from ethdev to eventdev, the adapter uses a
  32 DPDK service function and the application is also required to assign a core to
  33 the service function.
  34
  35 Creating an Adapter Instance
  36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  37
  38 An adapter instance is created using ``rte_event_eth_rx_adapter_create()``. This
  39 function is passed the event device to be associated with the adapter and port
  40 configuration for the adapter to setup an event port if the adapter needs to use
  41 a service function.
  42
  43 .. code-block:: c
  44
  45         int err;
  46         uint8_t dev_id;
  47         struct rte_event_dev_info dev_info;
  48         struct rte_event_port_conf rx_p_conf;
  49
  50         err = rte_event_dev_info_get(id, &dev_info);
  51
  52         rx_p_conf.new_event_threshold = dev_info.max_num_events;
  53         rx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
  54         rx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
  55         err = rte_event_eth_rx_adapter_create(id, dev_id, &rx_p_conf);
  56
  57 If the application desires to have finer control of eventdev port allocation
  58 and setup, it can use the ``rte_event_eth_rx_adapter_create_ext()`` function.
  59 The ``rte_event_eth_rx_adapter_create_ext()`` function is passed a callback
  60 function. The callback function is invoked if the adapter needs to use a
  61 service function and needs to create an event port for it. The callback is
  62 expected to fill the ``struct rte_event_eth_rx_adapter_conf structure``
  63 passed to it.
  64
  65 Adding Rx Queues to the Adapter Instance
  66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  67
  68 Ethdev Rx queues are added to the instance using the
  69 ``rte_event_eth_rx_adapter_queue_add()`` function. Configuration for the Rx
  70 queue is passed in using a ``struct rte_event_eth_rx_adapter_queue_conf``
  71 parameter. Event information for packets from this Rx queue is encoded in the
  72 ``ev`` field of ``struct rte_event_eth_rx_adapter_queue_conf``. The
  73 servicing_weight member of the struct  rte_event_eth_rx_adapter_queue_conf
  74 is the relative polling frequency of the Rx queue and is applicable when the
  75 adapter uses a service core function.
  76
  77 .. code-block:: c
  78
  79         ev.queue_id = 0;
  80         ev.sched_type = RTE_SCHED_TYPE_ATOMIC;
  81         ev.priority = 0;
  82
  83         queue_config.rx_queue_flags = 0;
  84         queue_config.ev = ev;
  85         queue_config.servicing_weight = 1;
  86
  87         err = rte_event_eth_rx_adapter_queue_add(id,
  88                                                 eth_dev_id,
  89                                                 0, &queue_config);
  90
  91 Querying Adapter Capabilities
  92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93
  94 The ``rte_event_eth_rx_adapter_caps_get()`` function allows
  95 the application to query the adapter capabilities for an eventdev and ethdev
  96 combination. For e.g, if the ``RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID``
  97 is set, the application can override the adapter generated flow ID in the event
  98 using ``rx_queue_flags`` field in ``struct rte_event_eth_rx_adapter_queue_conf``
  99 which is passed as a parameter to the ``rte_event_eth_rx_adapter_queue_add()``
 100 function.
 101
 102 .. code-block:: c
 103
 104         err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap);
 105
 106         queue_config.rx_queue_flags = 0;
 107         if (cap & RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) {
 108                 ev.flow_id = 1;
 109                 queue_config.rx_queue_flags =
 110                         RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID;
 111         }
 112
 113 Configuring the Service Function
 114 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 115
 116 If the adapter uses a service function, the application is required to assign
 117 a service core to the service function as show below.
 118
 119 .. code-block:: c
 120
 121         uint32_t service_id;
 122
 123         if (rte_event_eth_rx_adapter_service_id_get(0, &service_id) == 0)
 124                 rte_service_map_lcore_set(service_id, RX_CORE_ID);
 125
 126 Starting the Adapter Instance
 127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 128
 129 The application calls ``rte_event_eth_rx_adapter_start()`` to start the adapter.
 130 This function calls the start callbacks of the eventdev PMDs for hardware based
 131 eventdev-ethdev connections and ``rte_service_run_state_set()`` to enable the
 132 service function if one exists.
 133
 134 Getting Adapter Statistics
 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 136
 137 The  ``rte_event_eth_rx_adapter_stats_get()`` function reports counters defined
 138 in struct ``rte_event_eth_rx_adapter_stats``. The received packet and
 139 enqueued event counts are a sum of the counts from the eventdev PMD callbacks
 140 if the callback is supported, and the counts maintained by the service function,
 141 if one exists. The service function also maintains a count of cycles for which
 142 it was not able to enqueue to the event device.