2 * Copyright(c) 2017 Intel Corporation. All rights reserved.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * * Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in
13 * the documentation and/or other materials provided with the
15 * * Neither the name of Intel Corporation nor the names of its
16 * contributors may be used to endorse or promote products derived
17 * from this software without specific prior written permission.
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 #ifndef _RTE_EVENT_ETH_RX_ADAPTER_
33 #define _RTE_EVENT_ETH_RX_ADAPTER_
38 * RTE Event Ethernet Rx Adapter
40 * An eventdev-based packet processing application enqueues/dequeues mbufs
41 * to/from the event device. Packet flow from the ethernet device to the event
42 * device can be accomplished using either HW or SW mechanisms depending on the
43 * platform and the particular combination of ethernet and event devices. The
44 * event ethernet Rx adapter provides common APIs to configure the packet flow
45 * from the ethernet devices to event devices across both these transfer
48 * The adapter uses a EAL service core function for SW based packet transfer
49 * and uses the eventdev PMD functions to configure HW based packet transfer
50 * between the ethernet device and the event device. For SW based packet
51 * transfer, if the mbuf does not have a timestamp set, the adapter adds a
52 * timestamp to the mbuf using rte_get_tsc_cycles(), this provides a more
53 * accurate timestamp as compared to if the application were to set the time
54 * stamp since it avoids event device schedule latency.
56 * The ethernet Rx event adapter's functions are:
57 * - rte_event_eth_rx_adapter_create_ext()
58 * - rte_event_eth_rx_adapter_create()
59 * - rte_event_eth_rx_adapter_free()
60 * - rte_event_eth_rx_adapter_queue_add()
61 * - rte_event_eth_rx_adapter_queue_del()
62 * - rte_event_eth_rx_adapter_start()
63 * - rte_event_eth_rx_adapter_stop()
64 * - rte_event_eth_rx_adapter_stats_get()
65 * - rte_event_eth_rx_adapter_stats_reset()
67 * The application creates an ethernet to event adapter using
68 * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create()
70 * The adapter needs to know which ethernet rx queues to poll for mbufs as well
71 * as event device parameters such as the event queue identifier, event
72 * priority and scheduling type that the adapter should use when constructing
73 * events. The rte_event_eth_rx_adapter_queue_add() function is provided for
75 * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf
76 * is applicable when the Rx adapter uses a service core function and is
77 * intended to provide application control of the frequency of polling ethernet
78 * device receive queues, for example, the application may want to poll higher
79 * priority queues with a higher frequency but at the same time not starve
80 * lower priority queues completely. If this parameter is zero and the receive
81 * interrupt is enabled when configuring the device, the receive queue is
82 * interrupt driven; else, the queue is assigned a servicing weight of one.
84 * The application can start/stop the adapter using the
85 * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop()
86 * functions. If the adapter uses a rte_service function, then the application
87 * is also required to assign a core to the service function and control the
88 * service core using the rte_service APIs. The
89 * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve
90 * the service function ID of the adapter in this case.
92 * Note: Interrupt driven receive queues are currently unimplemented.
101 #include <rte_service.h>
103 #include "rte_eventdev.h"
105 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
107 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
108 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1
109 /**< This flag indicates the flow identifier is valid
110 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
115 * @b EXPERIMENTAL: this API may change without prior notice
117 * Adapter configuration structure that the adapter configuration callback
118 * function is expected to fill out
119 * @see rte_event_eth_rx_adapter_conf_cb
121 struct rte_event_eth_rx_adapter_conf {
122 uint8_t event_port_id;
123 /**< Event port identifier, the adapter enqueues mbuf events to this
127 /**< The adapter can return early if it has processed at least
128 * max_nb_rx mbufs. This isn't treated as a requirement; batching may
129 * cause the adapter to process more than max_nb_rx mbufs.
135 * @b EXPERIMENTAL: this API may change without prior notice
137 * Function type used for adapter configuration callback. The callback is
138 * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
139 * callback is invoked when creating a SW service for packet transfer from
140 * ethdev queues to the event device. The SW service is created within the
141 * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
142 * from ethdev queues to the event device are required.
145 * Adapter identifier.
148 * Event device identifier.
151 * Structure that needs to be populated by this callback.
154 * Argument to the callback. This is the same as the conf_arg passed to the
155 * rte_event_eth_rx_adapter_create_ext().
157 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
158 struct rte_event_eth_rx_adapter_conf *conf,
163 * @b EXPERIMENTAL: this API may change without prior notice
165 * Rx queue configuration structure
167 struct rte_event_eth_rx_adapter_queue_conf {
168 uint32_t rx_queue_flags;
169 /**< Flags for handling received packets
170 * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
172 uint16_t servicing_weight;
173 /**< Relative polling frequency of ethernet receive queue when the
174 * adapter uses a service core function for ethernet to event device
175 * transfers. If it is set to zero, the Rx queue is interrupt driven
176 * (unless rx queue interrupts are not enabled for the ethernet
181 * The values from the following event fields will be used when
182 * queuing mbuf events:
183 * - event_queue_id: Targeted event queue ID for received packets.
184 * - event_priority: Event priority of packets from this Rx queue in
185 * the event queue relative to other events.
186 * - sched_type: Scheduling type for packets from this Rx queue.
187 * - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
188 * is set in rx_queue_flags, this flow_id is used for all
189 * packets received from this queue. Otherwise the flow ID
190 * is set to the RSS hash of the src and dst IPv4/6
193 * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
200 * @b EXPERIMENTAL: this API may change without prior notice
202 * A structure used to retrieve statistics for an eth rx adapter instance.
204 struct rte_event_eth_rx_adapter_stats {
205 uint64_t rx_poll_count;
206 /**< Receive queue poll count */
208 /**< Received packet count */
209 uint64_t rx_enq_count;
210 /**< Eventdev enqueue count */
211 uint64_t rx_enq_retry;
212 /**< Eventdev enqueue retry count */
213 uint64_t rx_enq_start_ts;
214 /**< Rx enqueue start timestamp */
215 uint64_t rx_enq_block_cycles;
216 /**< Cycles for which the service is blocked by the event device,
217 * i.e, the service fails to enqueue to the event device.
219 uint64_t rx_enq_end_ts;
220 /**< Latest timestamp at which the service is unblocked
221 * by the event device. The start, end timestamps and
222 * block cycles can be used to compute the percentage of
223 * cycles the service is blocked by the event device.
229 * @b EXPERIMENTAL: this API may change without prior notice
231 * Create a new ethernet Rx event adapter with the specified identifier.
234 * The identifier of the ethernet Rx event adapter.
237 * The identifier of the device to configure.
240 * Callback function that fills in members of a
241 * struct rte_event_eth_rx_adapter_conf struct passed into
245 * Argument that is passed to the conf_cb function.
249 * - <0: Error code on failure
251 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
252 rte_event_eth_rx_adapter_conf_cb conf_cb,
257 * @b EXPERIMENTAL: this API may change without prior notice
259 * Create a new ethernet Rx event adapter with the specified identifier.
260 * This function uses an internal configuration function that creates an event
261 * port. This default function reconfigures the event device with an
262 * additional event port and setups up the event port using the port_config
263 * parameter passed into this function. In case the application needs more
264 * control in configuration of the service, it should use the
265 * rte_event_eth_rx_adapter_create_ext() version.
268 * The identifier of the ethernet Rx event adapter.
271 * The identifier of the device to configure.
274 * Argument of type *rte_event_port_conf* that is passed to the conf_cb
279 * - <0: Error code on failure
281 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
282 struct rte_event_port_conf *port_config);
286 * @b EXPERIMENTAL: this API may change without prior notice
288 * Free an event adapter
291 * Adapter identifier.
295 * - <0: Error code on failure, If the adapter still has Rx queues
296 * added to it, the function returns -EBUSY.
298 int rte_event_eth_rx_adapter_free(uint8_t id);
302 * @b EXPERIMENTAL: this API may change without prior notice
304 * Add receive queue to an event adapter. After a queue has been
305 * added to the event adapter, the result of the application calling
306 * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
309 * Adapter identifier.
312 * Port identifier of Ethernet device.
315 * Ethernet device receive queue index.
316 * If rx_queue_id is -1, then all Rx queues configured for
317 * the device are added. If the ethdev Rx queues can only be
318 * connected to a single event queue then rx_queue_id is
320 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
323 * Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
326 * - 0: Success, Receive queue added correctly.
327 * - <0: Error code on failure.
328 * - (-EIO) device reconfiguration and restart error. The adapter reconfigures
329 * the event device with an additional port if it is required to use a service
330 * function for packet transfer from the ethernet device to the event device.
331 * If the device had been started before this call, this error code indicates
332 * an error in restart following an error in reconfiguration, i.e., a
333 * combination of the two error codes.
335 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
338 const struct rte_event_eth_rx_adapter_queue_conf *conf);
342 * @b EXPERIMENTAL: this API may change without prior notice
344 * Delete receive queue from an event adapter.
347 * Adapter identifier.
350 * Port identifier of Ethernet device.
353 * Ethernet device receive queue index.
354 * If rx_queue_id is -1, then all Rx queues configured for
355 * the device are deleted. If the ethdev Rx queues can only be
356 * connected to a single event queue then rx_queue_id is
358 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
361 * - 0: Success, Receive queue deleted correctly.
362 * - <0: Error code on failure.
364 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint8_t eth_dev_id,
365 int32_t rx_queue_id);
369 * @b EXPERIMENTAL: this API may change without prior notice
371 * Start ethernet Rx event adapter
374 * Adapter identifier.
377 * - 0: Success, Adapter started correctly.
378 * - <0: Error code on failure.
380 int rte_event_eth_rx_adapter_start(uint8_t id);
384 * @b EXPERIMENTAL: this API may change without prior notice
386 * Stop ethernet Rx event adapter
389 * Adapter identifier.
392 * - 0: Success, Adapter started correctly.
393 * - <0: Error code on failure.
395 int rte_event_eth_rx_adapter_stop(uint8_t id);
399 * @b EXPERIMENTAL: this API may change without prior notice
401 * Retrieve statistics for an adapter
404 * Adapter identifier.
407 * A pointer to structure used to retrieve statistics for an adapter.
410 * - 0: Success, retrieved successfully.
411 * - <0: Error code on failure.
413 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
414 struct rte_event_eth_rx_adapter_stats *stats);
418 * @b EXPERIMENTAL: this API may change without prior notice
420 * Reset statistics for an adapter.
423 * Adapter identifier.
426 * - 0: Success, statistics reset successfully.
427 * - <0: Error code on failure.
429 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
433 * @b EXPERIMENTAL: this API may change without prior notice
435 * Retrieve the service ID of an adapter. If the adapter doesn't use
436 * a rte_service function, this function returns -ESRCH.
439 * Adapter identifier.
441 * @param [out] service_id
442 * A pointer to a uint32_t, to be filled in with the service id.
446 * - <0: Error code on failure, if the adapter doesn't use a rte_service
447 * function, this function returns -ESRCH.
449 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
454 #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */