1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2017 Intel Corporation. 3 * All rights reserved. 4 */ 5 6 #ifndef _RTE_EVENT_ETH_RX_ADAPTER_ 7 #define _RTE_EVENT_ETH_RX_ADAPTER_ 8 9 /** 10 * @file 11 * 12 * RTE Event Ethernet Rx Adapter 13 * 14 * An eventdev-based packet processing application enqueues/dequeues mbufs 15 * to/from the event device. Packet flow from the ethernet device to the event 16 * device can be accomplished using either HW or SW mechanisms depending on the 17 * platform and the particular combination of ethernet and event devices. The 18 * event ethernet Rx adapter provides common APIs to configure the packet flow 19 * from the ethernet devices to event devices across both these transfer 20 * mechanisms. 21 * 22 * The adapter uses a EAL service core function for SW based packet transfer 23 * and uses the eventdev PMD functions to configure HW based packet transfer 24 * between the ethernet device and the event device. 25 * 26 * The ethernet Rx event adapter's functions are: 27 * - rte_event_eth_rx_adapter_create_ext() 28 * - rte_event_eth_rx_adapter_create() 29 * - rte_event_eth_rx_adapter_free() 30 * - rte_event_eth_rx_adapter_queue_add() 31 * - rte_event_eth_rx_adapter_queue_del() 32 * - rte_event_eth_rx_adapter_start() 33 * - rte_event_eth_rx_adapter_stop() 34 * - rte_event_eth_rx_adapter_stats_get() 35 * - rte_event_eth_rx_adapter_stats_reset() 36 * 37 * The application creates an ethernet to event adapter using 38 * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create() 39 * functions. 40 * The adapter needs to know which ethernet rx queues to poll for mbufs as well 41 * as event device parameters such as the event queue identifier, event 42 * priority and scheduling type that the adapter should use when constructing 43 * events. The rte_event_eth_rx_adapter_queue_add() function is provided for 44 * this purpose. 45 * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf 46 * is applicable when the Rx adapter uses a service core function and is 47 * intended to provide application control of the frequency of polling ethernet 48 * device receive queues, for example, the application may want to poll higher 49 * priority queues with a higher frequency but at the same time not starve 50 * lower priority queues completely. If this parameter is zero and the receive 51 * interrupt is enabled when configuring the device, the receive queue is 52 * interrupt driven; else, the queue is assigned a servicing weight of one. 53 * 54 * The application can start/stop the adapter using the 55 * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop() 56 * functions. If the adapter uses a rte_service function, then the application 57 * is also required to assign a core to the service function and control the 58 * service core using the rte_service APIs. The 59 * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve 60 * the service function ID of the adapter in this case. 61 * 62 * For SW based packet transfers, i.e., when the 63 * RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT is not set in the adapter's 64 * capabilities flags for a particular ethernet device, the service function 65 * temporarily enqueues events to an event buffer before batch enqueuing these 66 * to the event device. If the buffer fills up, the service function stops 67 * dequeuing packets from the ethernet device. The application may want to 68 * monitor the buffer fill level and instruct the service function to 69 * selectively buffer events. The application may also use some other 70 * criteria to decide which packets should enter the event device even when 71 * the event buffer fill level is low or may want to enqueue packets to an 72 * internal event port. The rte_event_eth_rx_adapter_cb_register() function 73 * allows the application to register a callback that selects which packets are 74 * enqueued to the event device by the SW adapter. The callback interface is 75 * event based so the callback can also modify the event data if it needs to. 76 */ 77 78 #ifdef __cplusplus 79 extern "C" { 80 #endif 81 82 #include <stdint.h> 83 84 #include <rte_service.h> 85 86 #include "rte_eventdev.h" 87 88 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32 89 90 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */ 91 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1 92 /**< This flag indicates the flow identifier is valid 93 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags 94 */ 95 96 /** 97 * Adapter configuration structure that the adapter configuration callback 98 * function is expected to fill out 99 * @see rte_event_eth_rx_adapter_conf_cb 100 */ 101 struct rte_event_eth_rx_adapter_conf { 102 uint8_t event_port_id; 103 /**< Event port identifier, the adapter enqueues mbuf events to this 104 * port. 105 */ 106 uint32_t max_nb_rx; 107 /**< The adapter can return early if it has processed at least 108 * max_nb_rx mbufs. This isn't treated as a requirement; batching may 109 * cause the adapter to process more than max_nb_rx mbufs. 110 */ 111 }; 112 113 /** 114 * Function type used for adapter configuration callback. The callback is 115 * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this 116 * callback is invoked when creating a SW service for packet transfer from 117 * ethdev queues to the event device. The SW service is created within the 118 * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers 119 * from ethdev queues to the event device are required. 120 * 121 * @param id 122 * Adapter identifier. 123 * 124 * @param dev_id 125 * Event device identifier. 126 * 127 * @param [out] conf 128 * Structure that needs to be populated by this callback. 129 * 130 * @param arg 131 * Argument to the callback. This is the same as the conf_arg passed to the 132 * rte_event_eth_rx_adapter_create_ext(). 133 */ 134 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id, 135 struct rte_event_eth_rx_adapter_conf *conf, 136 void *arg); 137 138 /** 139 * Rx queue configuration structure 140 */ 141 struct rte_event_eth_rx_adapter_queue_conf { 142 uint32_t rx_queue_flags; 143 /**< Flags for handling received packets 144 * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 145 */ 146 uint16_t servicing_weight; 147 /**< Relative polling frequency of ethernet receive queue when the 148 * adapter uses a service core function for ethernet to event device 149 * transfers. If it is set to zero, the Rx queue is interrupt driven 150 * (unless rx queue interrupts are not enabled for the ethernet 151 * device). 152 */ 153 struct rte_event ev; 154 /**< 155 * The values from the following event fields will be used when 156 * queuing mbuf events: 157 * - event_queue_id: Targeted event queue ID for received packets. 158 * - event_priority: Event priority of packets from this Rx queue in 159 * the event queue relative to other events. 160 * - sched_type: Scheduling type for packets from this Rx queue. 161 * - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit 162 * is set in rx_queue_flags, this flow_id is used for all 163 * packets received from this queue. Otherwise the flow ID 164 * is set to the RSS hash of the src and dst IPv4/6 165 * addresses. 166 * 167 * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the 168 * enqueued event. 169 */ 170 }; 171 172 /** 173 * A structure used to retrieve statistics for an eth rx adapter instance. 174 */ 175 struct rte_event_eth_rx_adapter_stats { 176 uint64_t rx_poll_count; 177 /**< Receive queue poll count */ 178 uint64_t rx_packets; 179 /**< Received packet count */ 180 uint64_t rx_enq_count; 181 /**< Eventdev enqueue count */ 182 uint64_t rx_enq_retry; 183 /**< Eventdev enqueue retry count */ 184 uint64_t rx_dropped; 185 /**< Received packet dropped count */ 186 uint64_t rx_enq_start_ts; 187 /**< Rx enqueue start timestamp */ 188 uint64_t rx_enq_block_cycles; 189 /**< Cycles for which the service is blocked by the event device, 190 * i.e, the service fails to enqueue to the event device. 191 */ 192 uint64_t rx_enq_end_ts; 193 /**< Latest timestamp at which the service is unblocked 194 * by the event device. The start, end timestamps and 195 * block cycles can be used to compute the percentage of 196 * cycles the service is blocked by the event device. 197 */ 198 uint64_t rx_intr_packets; 199 /**< Received packet count for interrupt mode Rx queues */ 200 }; 201 202 /** 203 * 204 * Callback function invoked by the SW adapter before it continues 205 * to process events. The callback is passed the size of the enqueue 206 * buffer in the SW adapter and the occupancy of the buffer. The 207 * callback can use these values to decide which events are 208 * enqueued to the event device by the SW adapter. The callback may 209 * also enqueue events internally using its own event port. The SW 210 * adapter populates the event information based on the Rx queue 211 * configuration in the adapter. The callback can modify the this event 212 * information for the events to be enqueued by the SW adapter. 213 * 214 * The callback return value is the number of events from the 215 * beginning of the event array that are to be enqueued by 216 * the SW adapter. It is the callback's responsibility to arrange 217 * these events at the beginning of the array, if these events are 218 * not contiguous in the original array. The *nb_dropped* parameter is 219 * a pointer to the number of events dropped by the callback, this 220 * number is used by the adapter to indicate the number of dropped packets 221 * as part of its statistics. 222 * 223 * @param eth_dev_id 224 * Port identifier of the Ethernet device. 225 * @param queue_id 226 * Receive queue index. 227 * @param enqueue_buf_size 228 * Total enqueue buffer size. 229 * @param enqueue_buf_count 230 * Event count in enqueue buffer. 231 * @param[in, out] ev 232 * Event array. 233 * @param nb_event 234 * Event array length. 235 * @param cb_arg 236 * Callback argument. 237 * @param[out] nb_dropped 238 * Packets dropped by callback. 239 * @return 240 * - The number of events to be enqueued by the SW adapter. 241 */ 242 typedef uint16_t (*rte_event_eth_rx_adapter_cb_fn)(uint16_t eth_dev_id, 243 uint16_t queue_id, 244 uint32_t enqueue_buf_size, 245 uint32_t enqueue_buf_count, 246 struct rte_event *ev, 247 uint16_t nb_event, 248 void *cb_arg, 249 uint16_t *nb_dropped); 250 251 /** 252 * Create a new ethernet Rx event adapter with the specified identifier. 253 * 254 * @param id 255 * The identifier of the ethernet Rx event adapter. 256 * 257 * @param dev_id 258 * The identifier of the device to configure. 259 * 260 * @param conf_cb 261 * Callback function that fills in members of a 262 * struct rte_event_eth_rx_adapter_conf struct passed into 263 * it. 264 * 265 * @param conf_arg 266 * Argument that is passed to the conf_cb function. 267 * 268 * @return 269 * - 0: Success 270 * - <0: Error code on failure 271 */ 272 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id, 273 rte_event_eth_rx_adapter_conf_cb conf_cb, 274 void *conf_arg); 275 276 /** 277 * Create a new ethernet Rx event adapter with the specified identifier. 278 * This function uses an internal configuration function that creates an event 279 * port. This default function reconfigures the event device with an 280 * additional event port and setups up the event port using the port_config 281 * parameter passed into this function. In case the application needs more 282 * control in configuration of the service, it should use the 283 * rte_event_eth_rx_adapter_create_ext() version. 284 * 285 * @param id 286 * The identifier of the ethernet Rx event adapter. 287 * 288 * @param dev_id 289 * The identifier of the device to configure. 290 * 291 * @param port_config 292 * Argument of type *rte_event_port_conf* that is passed to the conf_cb 293 * function. 294 * 295 * @return 296 * - 0: Success 297 * - <0: Error code on failure 298 */ 299 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id, 300 struct rte_event_port_conf *port_config); 301 302 /** 303 * Free an event adapter 304 * 305 * @param id 306 * Adapter identifier. 307 * 308 * @return 309 * - 0: Success 310 * - <0: Error code on failure, If the adapter still has Rx queues 311 * added to it, the function returns -EBUSY. 312 */ 313 int rte_event_eth_rx_adapter_free(uint8_t id); 314 315 /** 316 * Add receive queue to an event adapter. After a queue has been 317 * added to the event adapter, the result of the application calling 318 * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined. 319 * 320 * @param id 321 * Adapter identifier. 322 * 323 * @param eth_dev_id 324 * Port identifier of Ethernet device. 325 * 326 * @param rx_queue_id 327 * Ethernet device receive queue index. 328 * If rx_queue_id is -1, then all Rx queues configured for 329 * the device are added. If the ethdev Rx queues can only be 330 * connected to a single event queue then rx_queue_id is 331 * required to be -1. 332 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ 333 * 334 * @param conf 335 * Additional configuration structure of type *rte_event_eth_rx_adapter_conf* 336 * 337 * @return 338 * - 0: Success, Receive queue added correctly. 339 * - <0: Error code on failure. 340 * - (-EIO) device reconfiguration and restart error. The adapter reconfigures 341 * the event device with an additional port if it is required to use a service 342 * function for packet transfer from the ethernet device to the event device. 343 * If the device had been started before this call, this error code indicates 344 * an error in restart following an error in reconfiguration, i.e., a 345 * combination of the two error codes. 346 */ 347 int rte_event_eth_rx_adapter_queue_add(uint8_t id, 348 uint16_t eth_dev_id, 349 int32_t rx_queue_id, 350 const struct rte_event_eth_rx_adapter_queue_conf *conf); 351 352 /** 353 * Delete receive queue from an event adapter. 354 * 355 * @param id 356 * Adapter identifier. 357 * 358 * @param eth_dev_id 359 * Port identifier of Ethernet device. 360 * 361 * @param rx_queue_id 362 * Ethernet device receive queue index. 363 * If rx_queue_id is -1, then all Rx queues configured for 364 * the device are deleted. If the ethdev Rx queues can only be 365 * connected to a single event queue then rx_queue_id is 366 * required to be -1. 367 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ 368 * 369 * @return 370 * - 0: Success, Receive queue deleted correctly. 371 * - <0: Error code on failure. 372 */ 373 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id, 374 int32_t rx_queue_id); 375 376 /** 377 * Start ethernet Rx event adapter 378 * 379 * @param id 380 * Adapter identifier. 381 * 382 * @return 383 * - 0: Success, Adapter started correctly. 384 * - <0: Error code on failure. 385 * 386 * @note 387 * The eventdev to which the event_eth_rx_adapter is connected needs to 388 * be started before calling rte_event_eth_rx_adapter_start(). 389 */ 390 int rte_event_eth_rx_adapter_start(uint8_t id); 391 392 /** 393 * Stop ethernet Rx event adapter 394 * 395 * @param id 396 * Adapter identifier. 397 * 398 * @return 399 * - 0: Success, Adapter started correctly. 400 * - <0: Error code on failure. 401 */ 402 int rte_event_eth_rx_adapter_stop(uint8_t id); 403 404 /** 405 * Retrieve statistics for an adapter 406 * 407 * @param id 408 * Adapter identifier. 409 * 410 * @param [out] stats 411 * A pointer to structure used to retrieve statistics for an adapter. 412 * 413 * @return 414 * - 0: Success, retrieved successfully. 415 * - <0: Error code on failure. 416 */ 417 int rte_event_eth_rx_adapter_stats_get(uint8_t id, 418 struct rte_event_eth_rx_adapter_stats *stats); 419 420 /** 421 * Reset statistics for an adapter. 422 * 423 * @param id 424 * Adapter identifier. 425 * 426 * @return 427 * - 0: Success, statistics reset successfully. 428 * - <0: Error code on failure. 429 */ 430 int rte_event_eth_rx_adapter_stats_reset(uint8_t id); 431 432 /** 433 * Retrieve the service ID of an adapter. If the adapter doesn't use 434 * a rte_service function, this function returns -ESRCH. 435 * 436 * @param id 437 * Adapter identifier. 438 * 439 * @param [out] service_id 440 * A pointer to a uint32_t, to be filled in with the service id. 441 * 442 * @return 443 * - 0: Success 444 * - <0: Error code on failure, if the adapter doesn't use a rte_service 445 * function, this function returns -ESRCH. 446 */ 447 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id); 448 449 /** 450 * Register callback to process Rx packets, this is supported for 451 * SW based packet transfers. 452 * @see rte_event_eth_rx_cb_fn 453 * 454 * @param id 455 * Adapter identifier. 456 * @param eth_dev_id 457 * Port identifier of Ethernet device. 458 * @param cb_fn 459 * Callback function. 460 * @param cb_arg 461 * Callback arg. 462 * @return 463 * - 0: Success 464 * - <0: Error code on failure. 465 */ 466 int rte_event_eth_rx_adapter_cb_register(uint8_t id, uint16_t eth_dev_id, 467 rte_event_eth_rx_adapter_cb_fn cb_fn, 468 void *cb_arg); 469 470 #ifdef __cplusplus 471 } 472 #endif 473 #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */ 474