doc/guides/prog_guide/event_ethernet_rx_adapter.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Intel Corporation. All rights reserved.
   3
   4     Redistribution and use in source and binary forms, with or without
   5     modification, are permitted provided that the following conditions
   6     are met:
   7
   8     * Redistributions of source code must retain the above copyright
   9     notice, this list of conditions and the following disclaimer.
  10     * Redistributions in binary form must reproduce the above copyright
  11     notice, this list of conditions and the following disclaimer in
  12     the documentation and/or other materials provided with the
  13     distribution.
  14     * Neither the name of Intel Corporation nor the names of its
  15     contributors may be used to endorse or promote products derived
  16     from this software without specific prior written permission.
  17
  18     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 Event Ethernet Rx Adapter Library
  31 =================================
  32
  33 The DPDK Eventdev API allows the application to use an event driven programming
  34 model for packet processing. In this model, the application polls an event
  35 device port for receiving events that reference packets instead of polling Rx
  36 queues of ethdev ports. Packet transfer between ethdev and the event device can
  37 be supported in hardware or require a software thread to receive packets from
  38 the ethdev port using ethdev poll mode APIs and enqueue these as events to the
  39 event device using the eventdev API. Both transfer mechanisms may be present on
  40 the same platform depending on the particular combination of the ethdev and
  41 the event device.
  42
  43 The Event Ethernet Rx Adapter library is intended for the application code to
  44 configure both transfer mechanisms using a common API. A capability API allows
  45 the eventdev PMD to advertise features supported for a given ethdev and allows
  46 the application to perform configuration as per supported features.
  47
  48 API Walk-through
  49 ----------------
  50
  51 This section will introduce the reader to the adapter API. The
  52 application has to first instantiate an adapter which is associated with
  53 a single eventdev, next the adapter instance is configured with Rx queues
  54 that are either polled by a SW thread or linked using hardware support. Finally
  55 the adapter is started.
  56
  57 For SW based packet transfers from ethdev to eventdev, the adapter uses a
  58 DPDK service function and the application is also required to assign a core to
  59 the service function.
  60
  61 Creating an Adapter Instance
  62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  63
  64 An adapter instance is created using ``rte_event_eth_rx_adapter_create()``. This
  65 function is passed the event device to be associated with the adapter and port
  66 configuration for the adapter to setup an event port if the adapter needs to use
  67 a service function.
  68
  69 .. code-block:: c
  70
  71         int err;
  72         uint8_t dev_id;
  73         struct rte_event_dev_info dev_info;
  74         struct rte_event_port_conf rx_p_conf;
  75
  76         err = rte_event_dev_info_get(id, &dev_info);
  77
  78         rx_p_conf.new_event_threshold = dev_info.max_num_events;
  79         rx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
  80         rx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
  81         err = rte_event_eth_rx_adapter_create(id, dev_id, &rx_p_conf);
  82
  83 If the application desires to have finer control of eventdev port allocation
  84 and setup, it can use the ``rte_event_eth_rx_adapter_create_ext()`` function.
  85 The ``rte_event_eth_rx_adapter_create_ext()`` function is passed a callback
  86 function. The callback function is invoked if the adapter needs to use a
  87 service function and needs to create an event port for it. The callback is
  88 expected to fill the ``struct rte_event_eth_rx_adapter_conf structure``
  89 passed to it.
  90
  91 Adding Rx Queues to the Adapter Instance
  92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93
  94 Ethdev Rx queues are added to the instance using the
  95 ``rte_event_eth_rx_adapter_queue_add()`` function. Configuration for the Rx
  96 queue is passed in using a ``struct rte_event_eth_rx_adapter_queue_conf``
  97 parameter. Event information for packets from this Rx queue is encoded in the
  98 ``ev`` field of ``struct rte_event_eth_rx_adapter_queue_conf``. The
  99 servicing_weight member of the struct  rte_event_eth_rx_adapter_queue_conf
 100 is the relative polling frequency of the Rx queue and is applicable when the
 101 adapter uses a service core function.
 102
 103 .. code-block:: c
 104
 105         ev.queue_id = 0;
 106         ev.sched_type = RTE_SCHED_TYPE_ATOMIC;
 107         ev.priority = 0;
 108
 109         queue_config.rx_queue_flags = 0;
 110         queue_config.ev = ev;
 111         queue_config.servicing_weight = 1;
 112
 113         err = rte_event_eth_rx_adapter_queue_add(id,
 114                                                 eth_dev_id,
 115                                                 0, &queue_config);
 116
 117 Querying Adapter Capabilities
 118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 119
 120 The ``rte_event_eth_rx_adapter_caps_get()`` function allows
 121 the application to query the adapter capabilities for an eventdev and ethdev
 122 combination. For e.g, if the ``RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID``
 123 is set, the application can override the adapter generated flow ID in the event
 124 using ``rx_queue_flags`` field in ``struct rte_event_eth_rx_adapter_queue_conf``
 125 which is passed as a parameter to the ``rte_event_eth_rx_adapter_queue_add()``
 126 function.
 127
 128 .. code-block:: c
 129
 130         err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap);
 131
 132         queue_config.rx_queue_flags = 0;
 133         if (cap & RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) {
 134                 ev.flow_id = 1;
 135                 queue_config.rx_queue_flags =
 136                         RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID;
 137         }
 138
 139 Configuring the Service Function
 140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 141
 142 If the adapter uses a service function, the application is required to assign
 143 a service core to the service function as show below.
 144
 145 .. code-block:: c
 146
 147         uint32_t service_id;
 148
 149         if (rte_event_eth_rx_adapter_service_id_get(0, &service_id) == 0)
 150                 rte_service_map_lcore_set(service_id, RX_CORE_ID);
 151
 152 Starting the Adapter Instance
 153 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 154
 155 The application calls ``rte_event_eth_rx_adapter_start()`` to start the adapter.
 156 This function calls the start callbacks of the eventdev PMDs for hardware based
 157 eventdev-ethdev connections and ``rte_service_run_state_set()`` to enable the
 158 service function if one exists.
 159
 160 Getting Adapter Statistics
 161 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 162
 163 The  ``rte_event_eth_rx_adapter_stats_get()`` function reports counters defined
 164 in struct ``rte_event_eth_rx_adapter_stats``. The received packet and
 165 enqueued event counts are a sum of the counts from the eventdev PMD callbacks
 166 if the callback is supported, and the counts maintained by the service function,
 167 if one exists. The service function also maintains a count of cycles for which
 168 it was not able to enqueue to the event device.