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.
52 * The ethernet Rx event adapter's functions are:
53 * - rte_event_eth_rx_adapter_create_ext()
54 * - rte_event_eth_rx_adapter_create()
55 * - rte_event_eth_rx_adapter_free()
56 * - rte_event_eth_rx_adapter_queue_add()
57 * - rte_event_eth_rx_adapter_queue_del()
58 * - rte_event_eth_rx_adapter_start()
59 * - rte_event_eth_rx_adapter_stop()
60 * - rte_event_eth_rx_adapter_stats_get()
61 * - rte_event_eth_rx_adapter_stats_reset()
63 * The application creates an ethernet to event adapter using
64 * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create()
66 * The adapter needs to know which ethernet rx queues to poll for mbufs as well
67 * as event device parameters such as the event queue identifier, event
68 * priority and scheduling type that the adapter should use when constructing
69 * events. The rte_event_eth_rx_adapter_queue_add() function is provided for
71 * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf
72 * is applicable when the Rx adapter uses a service core function and is
73 * intended to provide application control of the frequency of polling ethernet
74 * device receive queues, for example, the application may want to poll higher
75 * priority queues with a higher frequency but at the same time not starve
76 * lower priority queues completely. If this parameter is zero and the receive
77 * interrupt is enabled when configuring the device, the receive queue is
78 * interrupt driven; else, the queue is assigned a servicing weight of one.
80 * The application can start/stop the adapter using the
81 * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop()
82 * functions. If the adapter uses a rte_service function, then the application
83 * is also required to assign a core to the service function and control the
84 * service core using the rte_service APIs. The
85 * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve
86 * the service function ID of the adapter in this case.
88 * Note: Interrupt driven receive queues are currently unimplemented.
97 #include <rte_service.h>
99 #include "rte_eventdev.h"
101 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
103 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
104 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1
105 /**< This flag indicates the flow identifier is valid
106 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
111 * @b EXPERIMENTAL: this API may change without prior notice
113 * Adapter configuration structure that the adapter configuration callback
114 * function is expected to fill out
115 * @see rte_event_eth_rx_adapter_conf_cb
117 struct rte_event_eth_rx_adapter_conf {
118 uint8_t event_port_id;
119 /**< Event port identifier, the adapter enqueues mbuf events to this
123 /**< The adapter can return early if it has processed at least
124 * max_nb_rx mbufs. This isn't treated as a requirement; batching may
125 * cause the adapter to process more than max_nb_rx mbufs.
131 * @b EXPERIMENTAL: this API may change without prior notice
133 * Function type used for adapter configuration callback. The callback is
134 * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
135 * callback is invoked when creating a SW service for packet transfer from
136 * ethdev queues to the event device. The SW service is created within the
137 * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
138 * from ethdev queues to the event device are required.
141 * Adapter identifier.
144 * Event device identifier.
147 * Structure that needs to be populated by this callback.
150 * Argument to the callback. This is the same as the conf_arg passed to the
151 * rte_event_eth_rx_adapter_create_ext().
153 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
154 struct rte_event_eth_rx_adapter_conf *conf,
159 * @b EXPERIMENTAL: this API may change without prior notice
161 * Rx queue configuration structure
163 struct rte_event_eth_rx_adapter_queue_conf {
164 uint32_t rx_queue_flags;
165 /**< Flags for handling received packets
166 * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
168 uint16_t servicing_weight;
169 /**< Relative polling frequency of ethernet receive queue when the
170 * adapter uses a service core function for ethernet to event device
171 * transfers. If it is set to zero, the Rx queue is interrupt driven
172 * (unless rx queue interrupts are not enabled for the ethernet
177 * The values from the following event fields will be used when
178 * queuing mbuf events:
179 * - event_queue_id: Targeted event queue ID for received packets.
180 * - event_priority: Event priority of packets from this Rx queue in
181 * the event queue relative to other events.
182 * - sched_type: Scheduling type for packets from this Rx queue.
183 * - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
184 * is set in rx_queue_flags, this flow_id is used for all
185 * packets received from this queue. Otherwise the flow ID
186 * is set to the RSS hash of the src and dst IPv4/6
189 * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
196 * @b EXPERIMENTAL: this API may change without prior notice
198 * A structure used to retrieve statistics for an eth rx adapter instance.
200 struct rte_event_eth_rx_adapter_stats {
201 uint64_t rx_poll_count;
202 /**< Receive queue poll count */
204 /**< Received packet count */
205 uint64_t rx_enq_count;
206 /**< Eventdev enqueue count */
207 uint64_t rx_enq_retry;
208 /**< Eventdev enqueue retry count */
209 uint64_t rx_enq_start_ts;
210 /**< Rx enqueue start timestamp */
211 uint64_t rx_enq_block_cycles;
212 /**< Cycles for which the service is blocked by the event device,
213 * i.e, the service fails to enqueue to the event device.
215 uint64_t rx_enq_end_ts;
216 /**< Latest timestamp at which the service is unblocked
217 * by the event device. The start, end timestamps and
218 * block cycles can be used to compute the percentage of
219 * cycles the service is blocked by the event device.
225 * @b EXPERIMENTAL: this API may change without prior notice
227 * Create a new ethernet Rx event adapter with the specified identifier.
230 * The identifier of the ethernet Rx event adapter.
233 * The identifier of the device to configure.
236 * Callback function that fills in members of a
237 * struct rte_event_eth_rx_adapter_conf struct passed into
241 * Argument that is passed to the conf_cb function.
245 * - <0: Error code on failure
247 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
248 rte_event_eth_rx_adapter_conf_cb conf_cb,
253 * @b EXPERIMENTAL: this API may change without prior notice
255 * Create a new ethernet Rx event adapter with the specified identifier.
256 * This function uses an internal configuration function that creates an event
257 * port. This default function reconfigures the event device with an
258 * additional event port and setups up the event port using the port_config
259 * parameter passed into this function. In case the application needs more
260 * control in configuration of the service, it should use the
261 * rte_event_eth_rx_adapter_create_ext() version.
264 * The identifier of the ethernet Rx event adapter.
267 * The identifier of the device to configure.
270 * Argument of type *rte_event_port_conf* that is passed to the conf_cb
275 * - <0: Error code on failure
277 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
278 struct rte_event_port_conf *port_config);
282 * @b EXPERIMENTAL: this API may change without prior notice
284 * Free an event adapter
287 * Adapter identifier.
291 * - <0: Error code on failure, If the adapter still has Rx queues
292 * added to it, the function returns -EBUSY.
294 int rte_event_eth_rx_adapter_free(uint8_t id);
298 * @b EXPERIMENTAL: this API may change without prior notice
300 * Add receive queue to an event adapter. After a queue has been
301 * added to the event adapter, the result of the application calling
302 * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
305 * Adapter identifier.
308 * Port identifier of Ethernet device.
311 * Ethernet device receive queue index.
312 * If rx_queue_id is -1, then all Rx queues configured for
313 * the device are added. If the ethdev Rx queues can only be
314 * connected to a single event queue then rx_queue_id is
316 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
319 * Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
322 * - 0: Success, Receive queue added correctly.
323 * - <0: Error code on failure.
324 * - (-EIO) device reconfiguration and restart error. The adapter reconfigures
325 * the event device with an additional port if it is required to use a service
326 * function for packet transfer from the ethernet device to the event device.
327 * If the device had been started before this call, this error code indicates
328 * an error in restart following an error in reconfiguration, i.e., a
329 * combination of the two error codes.
331 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
334 const struct rte_event_eth_rx_adapter_queue_conf *conf);
338 * @b EXPERIMENTAL: this API may change without prior notice
340 * Delete receive queue from an event adapter.
343 * Adapter identifier.
346 * Port identifier of Ethernet device.
349 * Ethernet device receive queue index.
350 * If rx_queue_id is -1, then all Rx queues configured for
351 * the device are deleted. If the ethdev Rx queues can only be
352 * connected to a single event queue then rx_queue_id is
354 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
357 * - 0: Success, Receive queue deleted correctly.
358 * - <0: Error code on failure.
360 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint8_t eth_dev_id,
361 int32_t rx_queue_id);
365 * @b EXPERIMENTAL: this API may change without prior notice
367 * Start ethernet Rx event adapter
370 * Adapter identifier.
373 * - 0: Success, Adapter started correctly.
374 * - <0: Error code on failure.
376 int rte_event_eth_rx_adapter_start(uint8_t id);
380 * @b EXPERIMENTAL: this API may change without prior notice
382 * Stop ethernet Rx event adapter
385 * Adapter identifier.
388 * - 0: Success, Adapter started correctly.
389 * - <0: Error code on failure.
391 int rte_event_eth_rx_adapter_stop(uint8_t id);
395 * @b EXPERIMENTAL: this API may change without prior notice
397 * Retrieve statistics for an adapter
400 * Adapter identifier.
403 * A pointer to structure used to retrieve statistics for an adapter.
406 * - 0: Success, retrieved successfully.
407 * - <0: Error code on failure.
409 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
410 struct rte_event_eth_rx_adapter_stats *stats);
414 * @b EXPERIMENTAL: this API may change without prior notice
416 * Reset statistics for an adapter.
419 * Adapter identifier.
422 * - 0: Success, statistics reset successfully.
423 * - <0: Error code on failure.
425 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
429 * @b EXPERIMENTAL: this API may change without prior notice
431 * Retrieve the service ID of an adapter. If the adapter doesn't use
432 * a rte_service function, this function returns -ESRCH.
435 * Adapter identifier.
437 * @param [out] service_id
438 * A pointer to a uint32_t, to be filled in with the service id.
442 * - <0: Error code on failure, if the adapter doesn't use a rte_service
443 * function, this function returns -ESRCH.
445 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
450 #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */