2 Copyright(c) 2017 Intel Corporation. All rights reserved.
4 Redistribution and use in source and binary forms, with or without
5 modification, are permitted provided that the following conditions
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
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.
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.
30 Event Ethernet Rx Adapter Library
31 =================================
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
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.
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.
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
61 Creating an Adapter Instance
62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
73 struct rte_event_dev_info dev_info;
74 struct rte_event_port_conf rx_p_conf;
76 err = rte_event_dev_info_get(id, &dev_info);
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);
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``
91 Adding Rx Queues to the Adapter Instance
92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
106 ev.sched_type = RTE_SCHED_TYPE_ATOMIC;
109 queue_config.rx_queue_flags = 0;
110 queue_config.ev = ev;
111 queue_config.servicing_weight = 1;
113 err = rte_event_eth_rx_adapter_queue_add(id,
117 Querying Adapter Capabilities
118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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()``
130 err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap);
132 queue_config.rx_queue_flags = 0;
133 if (cap & RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) {
135 queue_config.rx_queue_flags =
136 RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID;
139 Configuring the Service Function
140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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);
152 Starting the Adapter Instance
153 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
160 Getting Adapter Statistics
161 ~~~~~~~~~~~~~~~~~~~~~~~~~~
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.