1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2017 Intel Corporation 3 */ 4 5 #ifndef _RTE_ETHDEV_H_ 6 #define _RTE_ETHDEV_H_ 7 8 /** 9 * @file 10 * 11 * RTE Ethernet Device API 12 * 13 * The Ethernet Device API is composed of two parts: 14 * 15 * - The application-oriented Ethernet API that includes functions to setup 16 * an Ethernet device (configure it, setup its RX and TX queues and start it), 17 * to get its MAC address, the speed and the status of its physical link, 18 * to receive and to transmit packets, and so on. 19 * 20 * - The driver-oriented Ethernet API that exports functions allowing 21 * an Ethernet Poll Mode Driver (PMD) to allocate an Ethernet device instance, 22 * create memzone for HW rings and process registered callbacks, and so on. 23 * PMDs should include rte_ethdev_driver.h instead of this header. 24 * 25 * By default, all the functions of the Ethernet Device API exported by a PMD 26 * are lock-free functions which assume to not be invoked in parallel on 27 * different logical cores to work on the same target object. For instance, 28 * the receive function of a PMD cannot be invoked in parallel on two logical 29 * cores to poll the same RX queue [of the same port]. Of course, this function 30 * can be invoked in parallel by different logical cores on different RX queues. 31 * It is the responsibility of the upper level application to enforce this rule. 32 * 33 * If needed, parallel accesses by multiple logical cores to shared queues 34 * shall be explicitly protected by dedicated inline lock-aware functions 35 * built on top of their corresponding lock-free functions of the PMD API. 36 * 37 * In all functions of the Ethernet API, the Ethernet device is 38 * designated by an integer >= 0 named the device port identifier. 39 * 40 * At the Ethernet driver level, Ethernet devices are represented by a generic 41 * data structure of type *rte_eth_dev*. 42 * 43 * Ethernet devices are dynamically registered during the PCI probing phase 44 * performed at EAL initialization time. 45 * When an Ethernet device is being probed, an *rte_eth_dev* structure and 46 * a new port identifier are allocated for that device. Then, the eth_dev_init() 47 * function supplied by the Ethernet driver matching the probed PCI 48 * device is invoked to properly initialize the device. 49 * 50 * The role of the device init function consists of resetting the hardware, 51 * checking access to Non-volatile Memory (NVM), reading the MAC address 52 * from NVM etc. 53 * 54 * If the device init operation is successful, the correspondence between 55 * the port identifier assigned to the new device and its associated 56 * *rte_eth_dev* structure is effectively registered. 57 * Otherwise, both the *rte_eth_dev* structure and the port identifier are 58 * freed. 59 * 60 * The functions exported by the application Ethernet API to setup a device 61 * designated by its port identifier must be invoked in the following order: 62 * - rte_eth_dev_configure() 63 * - rte_eth_tx_queue_setup() 64 * - rte_eth_rx_queue_setup() 65 * - rte_eth_dev_start() 66 * 67 * Then, the network application can invoke, in any order, the functions 68 * exported by the Ethernet API to get the MAC address of a given device, to 69 * get the speed and the status of a device physical link, to receive/transmit 70 * [burst of] packets, and so on. 71 * 72 * If the application wants to change the configuration (i.e. call 73 * rte_eth_dev_configure(), rte_eth_tx_queue_setup(), or 74 * rte_eth_rx_queue_setup()), it must call rte_eth_dev_stop() first to stop the 75 * device and then do the reconfiguration before calling rte_eth_dev_start() 76 * again. The transmit and receive functions should not be invoked when the 77 * device is stopped. 78 * 79 * Please note that some configuration is not stored between calls to 80 * rte_eth_dev_stop()/rte_eth_dev_start(). The following configuration will 81 * be retained: 82 * 83 * - flow control settings 84 * - receive mode configuration (promiscuous mode, hardware checksum mode, 85 * RSS/VMDQ settings etc.) 86 * - VLAN filtering configuration 87 * - MAC addresses supplied to MAC address array 88 * - flow director filtering mode (but not filtering rules) 89 * - NIC queue statistics mappings 90 * 91 * Any other configuration will not be stored and will need to be re-entered 92 * before a call to rte_eth_dev_start(). 93 * 94 * Finally, a network application can close an Ethernet device by invoking the 95 * rte_eth_dev_close() function. 96 * 97 * Each function of the application Ethernet API invokes a specific function 98 * of the PMD that controls the target device designated by its port 99 * identifier. 100 * For this purpose, all device-specific functions of an Ethernet driver are 101 * supplied through a set of pointers contained in a generic structure of type 102 * *eth_dev_ops*. 103 * The address of the *eth_dev_ops* structure is stored in the *rte_eth_dev* 104 * structure by the device init function of the Ethernet driver, which is 105 * invoked during the PCI probing phase, as explained earlier. 106 * 107 * In other words, each function of the Ethernet API simply retrieves the 108 * *rte_eth_dev* structure associated with the device port identifier and 109 * performs an indirect invocation of the corresponding driver function 110 * supplied in the *eth_dev_ops* structure of the *rte_eth_dev* structure. 111 * 112 * For performance reasons, the address of the burst-oriented RX and TX 113 * functions of the Ethernet driver are not contained in the *eth_dev_ops* 114 * structure. Instead, they are directly stored at the beginning of the 115 * *rte_eth_dev* structure to avoid an extra indirect memory access during 116 * their invocation. 117 * 118 * RTE ethernet device drivers do not use interrupts for transmitting or 119 * receiving. Instead, Ethernet drivers export Poll-Mode receive and transmit 120 * functions to applications. 121 * Both receive and transmit functions are packet-burst oriented to minimize 122 * their cost per packet through the following optimizations: 123 * 124 * - Sharing among multiple packets the incompressible cost of the 125 * invocation of receive/transmit functions. 126 * 127 * - Enabling receive/transmit functions to take advantage of burst-oriented 128 * hardware features (L1 cache, prefetch instructions, NIC head/tail 129 * registers) to minimize the number of CPU cycles per packet, for instance, 130 * by avoiding useless read memory accesses to ring descriptors, or by 131 * systematically using arrays of pointers that exactly fit L1 cache line 132 * boundaries and sizes. 133 * 134 * The burst-oriented receive function does not provide any error notification, 135 * to avoid the corresponding overhead. As a hint, the upper-level application 136 * might check the status of the device link once being systematically returned 137 * a 0 value by the receive function of the driver for a given number of tries. 138 */ 139 140 #ifdef __cplusplus 141 extern "C" { 142 #endif 143 144 #include <stdint.h> 145 146 /* Use this macro to check if LRO API is supported */ 147 #define RTE_ETHDEV_HAS_LRO_SUPPORT 148 149 #include <rte_compat.h> 150 #include <rte_log.h> 151 #include <rte_interrupts.h> 152 #include <rte_dev.h> 153 #include <rte_devargs.h> 154 #include <rte_errno.h> 155 #include <rte_common.h> 156 #include <rte_config.h> 157 158 #include "rte_ether.h" 159 #include "rte_eth_ctrl.h" 160 #include "rte_dev_info.h" 161 162 extern int rte_eth_dev_logtype; 163 164 #define RTE_ETHDEV_LOG(level, ...) \ 165 rte_log(RTE_LOG_ ## level, rte_eth_dev_logtype, "" __VA_ARGS__) 166 167 struct rte_mbuf; 168 169 /** 170 * Initializes a device iterator. 171 * 172 * This iterator allows accessing a list of devices matching some devargs. 173 * 174 * @param iter 175 * Device iterator handle initialized by the function. 176 * The fields bus_str and cls_str might be dynamically allocated, 177 * and could be freed by calling rte_eth_iterator_cleanup(). 178 * 179 * @param devargs 180 * Device description string. 181 * 182 * @return 183 * 0 on successful initialization, negative otherwise. 184 */ 185 int rte_eth_iterator_init(struct rte_dev_iterator *iter, const char *devargs); 186 187 /** 188 * Iterates on devices with devargs filter. 189 * The ownership is not checked. 190 * 191 * The next port id is returned, and the iterator is updated. 192 * 193 * @param iter 194 * Device iterator handle initialized by rte_eth_iterator_init(). 195 * Some fields bus_str and cls_str might be freed when no more port is found, 196 * by calling rte_eth_iterator_cleanup(). 197 * 198 * @return 199 * A port id if found, RTE_MAX_ETHPORTS otherwise. 200 */ 201 uint16_t rte_eth_iterator_next(struct rte_dev_iterator *iter); 202 203 /** 204 * Free some allocated fields of the iterator. 205 * 206 * This function is automatically called by rte_eth_iterator_next() 207 * on the last iteration (i.e. when no more matching port is found). 208 * 209 * It is safe to call this function twice; it will do nothing more. 210 * 211 * @param iter 212 * Device iterator handle initialized by rte_eth_iterator_init(). 213 * The fields bus_str and cls_str are freed if needed. 214 */ 215 void rte_eth_iterator_cleanup(struct rte_dev_iterator *iter); 216 217 /** 218 * Macro to iterate over all ethdev ports matching some devargs. 219 * 220 * If a break is done before the end of the loop, 221 * the function rte_eth_iterator_cleanup() must be called. 222 * 223 * @param id 224 * Iterated port id of type uint16_t. 225 * @param devargs 226 * Device parameters input as string of type char*. 227 * @param iter 228 * Iterator handle of type struct rte_dev_iterator, used internally. 229 */ 230 #define RTE_ETH_FOREACH_MATCHING_DEV(id, devargs, iter) \ 231 for (rte_eth_iterator_init(iter, devargs), \ 232 id = rte_eth_iterator_next(iter); \ 233 id != RTE_MAX_ETHPORTS; \ 234 id = rte_eth_iterator_next(iter)) 235 236 /** 237 * A structure used to retrieve statistics for an Ethernet port. 238 * Not all statistics fields in struct rte_eth_stats are supported 239 * by any type of network interface card (NIC). If any statistics 240 * field is not supported, its value is 0. 241 */ 242 struct rte_eth_stats { 243 uint64_t ipackets; /**< Total number of successfully received packets. */ 244 uint64_t opackets; /**< Total number of successfully transmitted packets.*/ 245 uint64_t ibytes; /**< Total number of successfully received bytes. */ 246 uint64_t obytes; /**< Total number of successfully transmitted bytes. */ 247 uint64_t imissed; 248 /**< Total of RX packets dropped by the HW, 249 * because there are no available buffer (i.e. RX queues are full). 250 */ 251 uint64_t ierrors; /**< Total number of erroneous received packets. */ 252 uint64_t oerrors; /**< Total number of failed transmitted packets. */ 253 uint64_t rx_nombuf; /**< Total number of RX mbuf allocation failures. */ 254 uint64_t q_ipackets[RTE_ETHDEV_QUEUE_STAT_CNTRS]; 255 /**< Total number of queue RX packets. */ 256 uint64_t q_opackets[RTE_ETHDEV_QUEUE_STAT_CNTRS]; 257 /**< Total number of queue TX packets. */ 258 uint64_t q_ibytes[RTE_ETHDEV_QUEUE_STAT_CNTRS]; 259 /**< Total number of successfully received queue bytes. */ 260 uint64_t q_obytes[RTE_ETHDEV_QUEUE_STAT_CNTRS]; 261 /**< Total number of successfully transmitted queue bytes. */ 262 uint64_t q_errors[RTE_ETHDEV_QUEUE_STAT_CNTRS]; 263 /**< Total number of queue packets received that are dropped. */ 264 }; 265 266 /** 267 * Device supported speeds bitmap flags 268 */ 269 #define ETH_LINK_SPEED_AUTONEG (0 << 0) /**< Autonegotiate (all speeds) */ 270 #define ETH_LINK_SPEED_FIXED (1 << 0) /**< Disable autoneg (fixed speed) */ 271 #define ETH_LINK_SPEED_10M_HD (1 << 1) /**< 10 Mbps half-duplex */ 272 #define ETH_LINK_SPEED_10M (1 << 2) /**< 10 Mbps full-duplex */ 273 #define ETH_LINK_SPEED_100M_HD (1 << 3) /**< 100 Mbps half-duplex */ 274 #define ETH_LINK_SPEED_100M (1 << 4) /**< 100 Mbps full-duplex */ 275 #define ETH_LINK_SPEED_1G (1 << 5) /**< 1 Gbps */ 276 #define ETH_LINK_SPEED_2_5G (1 << 6) /**< 2.5 Gbps */ 277 #define ETH_LINK_SPEED_5G (1 << 7) /**< 5 Gbps */ 278 #define ETH_LINK_SPEED_10G (1 << 8) /**< 10 Gbps */ 279 #define ETH_LINK_SPEED_20G (1 << 9) /**< 20 Gbps */ 280 #define ETH_LINK_SPEED_25G (1 << 10) /**< 25 Gbps */ 281 #define ETH_LINK_SPEED_40G (1 << 11) /**< 40 Gbps */ 282 #define ETH_LINK_SPEED_50G (1 << 12) /**< 50 Gbps */ 283 #define ETH_LINK_SPEED_56G (1 << 13) /**< 56 Gbps */ 284 #define ETH_LINK_SPEED_100G (1 << 14) /**< 100 Gbps */ 285 286 /** 287 * Ethernet numeric link speeds in Mbps 288 */ 289 #define ETH_SPEED_NUM_NONE 0 /**< Not defined */ 290 #define ETH_SPEED_NUM_10M 10 /**< 10 Mbps */ 291 #define ETH_SPEED_NUM_100M 100 /**< 100 Mbps */ 292 #define ETH_SPEED_NUM_1G 1000 /**< 1 Gbps */ 293 #define ETH_SPEED_NUM_2_5G 2500 /**< 2.5 Gbps */ 294 #define ETH_SPEED_NUM_5G 5000 /**< 5 Gbps */ 295 #define ETH_SPEED_NUM_10G 10000 /**< 10 Gbps */ 296 #define ETH_SPEED_NUM_20G 20000 /**< 20 Gbps */ 297 #define ETH_SPEED_NUM_25G 25000 /**< 25 Gbps */ 298 #define ETH_SPEED_NUM_40G 40000 /**< 40 Gbps */ 299 #define ETH_SPEED_NUM_50G 50000 /**< 50 Gbps */ 300 #define ETH_SPEED_NUM_56G 56000 /**< 56 Gbps */ 301 #define ETH_SPEED_NUM_100G 100000 /**< 100 Gbps */ 302 303 /** 304 * A structure used to retrieve link-level information of an Ethernet port. 305 */ 306 __extension__ 307 struct rte_eth_link { 308 uint32_t link_speed; /**< ETH_SPEED_NUM_ */ 309 uint16_t link_duplex : 1; /**< ETH_LINK_[HALF/FULL]_DUPLEX */ 310 uint16_t link_autoneg : 1; /**< ETH_LINK_[AUTONEG/FIXED] */ 311 uint16_t link_status : 1; /**< ETH_LINK_[DOWN/UP] */ 312 } __attribute__((aligned(8))); /**< aligned for atomic64 read/write */ 313 314 /* Utility constants */ 315 #define ETH_LINK_HALF_DUPLEX 0 /**< Half-duplex connection (see link_duplex). */ 316 #define ETH_LINK_FULL_DUPLEX 1 /**< Full-duplex connection (see link_duplex). */ 317 #define ETH_LINK_DOWN 0 /**< Link is down (see link_status). */ 318 #define ETH_LINK_UP 1 /**< Link is up (see link_status). */ 319 #define ETH_LINK_FIXED 0 /**< No autonegotiation (see link_autoneg). */ 320 #define ETH_LINK_AUTONEG 1 /**< Autonegotiated (see link_autoneg). */ 321 322 /** 323 * A structure used to configure the ring threshold registers of an RX/TX 324 * queue for an Ethernet port. 325 */ 326 struct rte_eth_thresh { 327 uint8_t pthresh; /**< Ring prefetch threshold. */ 328 uint8_t hthresh; /**< Ring host threshold. */ 329 uint8_t wthresh; /**< Ring writeback threshold. */ 330 }; 331 332 /** 333 * Simple flags are used for rte_eth_conf.rxmode.mq_mode. 334 */ 335 #define ETH_MQ_RX_RSS_FLAG 0x1 336 #define ETH_MQ_RX_DCB_FLAG 0x2 337 #define ETH_MQ_RX_VMDQ_FLAG 0x4 338 339 /** 340 * A set of values to identify what method is to be used to route 341 * packets to multiple queues. 342 */ 343 enum rte_eth_rx_mq_mode { 344 /** None of DCB,RSS or VMDQ mode */ 345 ETH_MQ_RX_NONE = 0, 346 347 /** For RX side, only RSS is on */ 348 ETH_MQ_RX_RSS = ETH_MQ_RX_RSS_FLAG, 349 /** For RX side,only DCB is on. */ 350 ETH_MQ_RX_DCB = ETH_MQ_RX_DCB_FLAG, 351 /** Both DCB and RSS enable */ 352 ETH_MQ_RX_DCB_RSS = ETH_MQ_RX_RSS_FLAG | ETH_MQ_RX_DCB_FLAG, 353 354 /** Only VMDQ, no RSS nor DCB */ 355 ETH_MQ_RX_VMDQ_ONLY = ETH_MQ_RX_VMDQ_FLAG, 356 /** RSS mode with VMDQ */ 357 ETH_MQ_RX_VMDQ_RSS = ETH_MQ_RX_RSS_FLAG | ETH_MQ_RX_VMDQ_FLAG, 358 /** Use VMDQ+DCB to route traffic to queues */ 359 ETH_MQ_RX_VMDQ_DCB = ETH_MQ_RX_VMDQ_FLAG | ETH_MQ_RX_DCB_FLAG, 360 /** Enable both VMDQ and DCB in VMDq */ 361 ETH_MQ_RX_VMDQ_DCB_RSS = ETH_MQ_RX_RSS_FLAG | ETH_MQ_RX_DCB_FLAG | 362 ETH_MQ_RX_VMDQ_FLAG, 363 }; 364 365 /** 366 * for rx mq mode backward compatible 367 */ 368 #define ETH_RSS ETH_MQ_RX_RSS 369 #define VMDQ_DCB ETH_MQ_RX_VMDQ_DCB 370 #define ETH_DCB_RX ETH_MQ_RX_DCB 371 372 /** 373 * A set of values to identify what method is to be used to transmit 374 * packets using multi-TCs. 375 */ 376 enum rte_eth_tx_mq_mode { 377 ETH_MQ_TX_NONE = 0, /**< It is in neither DCB nor VT mode. */ 378 ETH_MQ_TX_DCB, /**< For TX side,only DCB is on. */ 379 ETH_MQ_TX_VMDQ_DCB, /**< For TX side,both DCB and VT is on. */ 380 ETH_MQ_TX_VMDQ_ONLY, /**< Only VT on, no DCB */ 381 }; 382 383 /** 384 * for tx mq mode backward compatible 385 */ 386 #define ETH_DCB_NONE ETH_MQ_TX_NONE 387 #define ETH_VMDQ_DCB_TX ETH_MQ_TX_VMDQ_DCB 388 #define ETH_DCB_TX ETH_MQ_TX_DCB 389 390 /** 391 * A structure used to configure the RX features of an Ethernet port. 392 */ 393 struct rte_eth_rxmode { 394 /** The multi-queue packet distribution mode to be used, e.g. RSS. */ 395 enum rte_eth_rx_mq_mode mq_mode; 396 uint32_t max_rx_pkt_len; /**< Only used if JUMBO_FRAME enabled. */ 397 uint16_t split_hdr_size; /**< hdr buf size (header_split enabled).*/ 398 /** 399 * Per-port Rx offloads to be set using DEV_RX_OFFLOAD_* flags. 400 * Only offloads set on rx_offload_capa field on rte_eth_dev_info 401 * structure are allowed to be set. 402 */ 403 uint64_t offloads; 404 }; 405 406 /** 407 * VLAN types to indicate if it is for single VLAN, inner VLAN or outer VLAN. 408 * Note that single VLAN is treated the same as inner VLAN. 409 */ 410 enum rte_vlan_type { 411 ETH_VLAN_TYPE_UNKNOWN = 0, 412 ETH_VLAN_TYPE_INNER, /**< Inner VLAN. */ 413 ETH_VLAN_TYPE_OUTER, /**< Single VLAN, or outer VLAN. */ 414 ETH_VLAN_TYPE_MAX, 415 }; 416 417 /** 418 * A structure used to describe a vlan filter. 419 * If the bit corresponding to a VID is set, such VID is on. 420 */ 421 struct rte_vlan_filter_conf { 422 uint64_t ids[64]; 423 }; 424 425 /** 426 * A structure used to configure the Receive Side Scaling (RSS) feature 427 * of an Ethernet port. 428 * If not NULL, the *rss_key* pointer of the *rss_conf* structure points 429 * to an array holding the RSS key to use for hashing specific header 430 * fields of received packets. The length of this array should be indicated 431 * by *rss_key_len* below. Otherwise, a default random hash key is used by 432 * the device driver. 433 * 434 * The *rss_key_len* field of the *rss_conf* structure indicates the length 435 * in bytes of the array pointed by *rss_key*. To be compatible, this length 436 * will be checked in i40e only. Others assume 40 bytes to be used as before. 437 * 438 * The *rss_hf* field of the *rss_conf* structure indicates the different 439 * types of IPv4/IPv6 packets to which the RSS hashing must be applied. 440 * Supplying an *rss_hf* equal to zero disables the RSS feature. 441 */ 442 struct rte_eth_rss_conf { 443 uint8_t *rss_key; /**< If not NULL, 40-byte hash key. */ 444 uint8_t rss_key_len; /**< hash key length in bytes. */ 445 uint64_t rss_hf; /**< Hash functions to apply - see below. */ 446 }; 447 448 /* 449 * The RSS offload types are defined based on flow types which are defined 450 * in rte_eth_ctrl.h. Different NIC hardwares may support different RSS offload 451 * types. The supported flow types or RSS offload types can be queried by 452 * rte_eth_dev_info_get(). 453 */ 454 #define ETH_RSS_IPV4 (1ULL << RTE_ETH_FLOW_IPV4) 455 #define ETH_RSS_FRAG_IPV4 (1ULL << RTE_ETH_FLOW_FRAG_IPV4) 456 #define ETH_RSS_NONFRAG_IPV4_TCP (1ULL << RTE_ETH_FLOW_NONFRAG_IPV4_TCP) 457 #define ETH_RSS_NONFRAG_IPV4_UDP (1ULL << RTE_ETH_FLOW_NONFRAG_IPV4_UDP) 458 #define ETH_RSS_NONFRAG_IPV4_SCTP (1ULL << RTE_ETH_FLOW_NONFRAG_IPV4_SCTP) 459 #define ETH_RSS_NONFRAG_IPV4_OTHER (1ULL << RTE_ETH_FLOW_NONFRAG_IPV4_OTHER) 460 #define ETH_RSS_IPV6 (1ULL << RTE_ETH_FLOW_IPV6) 461 #define ETH_RSS_FRAG_IPV6 (1ULL << RTE_ETH_FLOW_FRAG_IPV6) 462 #define ETH_RSS_NONFRAG_IPV6_TCP (1ULL << RTE_ETH_FLOW_NONFRAG_IPV6_TCP) 463 #define ETH_RSS_NONFRAG_IPV6_UDP (1ULL << RTE_ETH_FLOW_NONFRAG_IPV6_UDP) 464 #define ETH_RSS_NONFRAG_IPV6_SCTP (1ULL << RTE_ETH_FLOW_NONFRAG_IPV6_SCTP) 465 #define ETH_RSS_NONFRAG_IPV6_OTHER (1ULL << RTE_ETH_FLOW_NONFRAG_IPV6_OTHER) 466 #define ETH_RSS_L2_PAYLOAD (1ULL << RTE_ETH_FLOW_L2_PAYLOAD) 467 #define ETH_RSS_IPV6_EX (1ULL << RTE_ETH_FLOW_IPV6_EX) 468 #define ETH_RSS_IPV6_TCP_EX (1ULL << RTE_ETH_FLOW_IPV6_TCP_EX) 469 #define ETH_RSS_IPV6_UDP_EX (1ULL << RTE_ETH_FLOW_IPV6_UDP_EX) 470 #define ETH_RSS_PORT (1ULL << RTE_ETH_FLOW_PORT) 471 #define ETH_RSS_VXLAN (1ULL << RTE_ETH_FLOW_VXLAN) 472 #define ETH_RSS_GENEVE (1ULL << RTE_ETH_FLOW_GENEVE) 473 #define ETH_RSS_NVGRE (1ULL << RTE_ETH_FLOW_NVGRE) 474 475 #define ETH_RSS_IP ( \ 476 ETH_RSS_IPV4 | \ 477 ETH_RSS_FRAG_IPV4 | \ 478 ETH_RSS_NONFRAG_IPV4_OTHER | \ 479 ETH_RSS_IPV6 | \ 480 ETH_RSS_FRAG_IPV6 | \ 481 ETH_RSS_NONFRAG_IPV6_OTHER | \ 482 ETH_RSS_IPV6_EX) 483 484 #define ETH_RSS_UDP ( \ 485 ETH_RSS_NONFRAG_IPV4_UDP | \ 486 ETH_RSS_NONFRAG_IPV6_UDP | \ 487 ETH_RSS_IPV6_UDP_EX) 488 489 #define ETH_RSS_TCP ( \ 490 ETH_RSS_NONFRAG_IPV4_TCP | \ 491 ETH_RSS_NONFRAG_IPV6_TCP | \ 492 ETH_RSS_IPV6_TCP_EX) 493 494 #define ETH_RSS_SCTP ( \ 495 ETH_RSS_NONFRAG_IPV4_SCTP | \ 496 ETH_RSS_NONFRAG_IPV6_SCTP) 497 498 #define ETH_RSS_TUNNEL ( \ 499 ETH_RSS_VXLAN | \ 500 ETH_RSS_GENEVE | \ 501 ETH_RSS_NVGRE) 502 503 /**< Mask of valid RSS hash protocols */ 504 #define ETH_RSS_PROTO_MASK ( \ 505 ETH_RSS_IPV4 | \ 506 ETH_RSS_FRAG_IPV4 | \ 507 ETH_RSS_NONFRAG_IPV4_TCP | \ 508 ETH_RSS_NONFRAG_IPV4_UDP | \ 509 ETH_RSS_NONFRAG_IPV4_SCTP | \ 510 ETH_RSS_NONFRAG_IPV4_OTHER | \ 511 ETH_RSS_IPV6 | \ 512 ETH_RSS_FRAG_IPV6 | \ 513 ETH_RSS_NONFRAG_IPV6_TCP | \ 514 ETH_RSS_NONFRAG_IPV6_UDP | \ 515 ETH_RSS_NONFRAG_IPV6_SCTP | \ 516 ETH_RSS_NONFRAG_IPV6_OTHER | \ 517 ETH_RSS_L2_PAYLOAD | \ 518 ETH_RSS_IPV6_EX | \ 519 ETH_RSS_IPV6_TCP_EX | \ 520 ETH_RSS_IPV6_UDP_EX | \ 521 ETH_RSS_PORT | \ 522 ETH_RSS_VXLAN | \ 523 ETH_RSS_GENEVE | \ 524 ETH_RSS_NVGRE) 525 526 /* 527 * Definitions used for redirection table entry size. 528 * Some RSS RETA sizes may not be supported by some drivers, check the 529 * documentation or the description of relevant functions for more details. 530 */ 531 #define ETH_RSS_RETA_SIZE_64 64 532 #define ETH_RSS_RETA_SIZE_128 128 533 #define ETH_RSS_RETA_SIZE_256 256 534 #define ETH_RSS_RETA_SIZE_512 512 535 #define RTE_RETA_GROUP_SIZE 64 536 537 /* Definitions used for VMDQ and DCB functionality */ 538 #define ETH_VMDQ_MAX_VLAN_FILTERS 64 /**< Maximum nb. of VMDQ vlan filters. */ 539 #define ETH_DCB_NUM_USER_PRIORITIES 8 /**< Maximum nb. of DCB priorities. */ 540 #define ETH_VMDQ_DCB_NUM_QUEUES 128 /**< Maximum nb. of VMDQ DCB queues. */ 541 #define ETH_DCB_NUM_QUEUES 128 /**< Maximum nb. of DCB queues. */ 542 543 /* DCB capability defines */ 544 #define ETH_DCB_PG_SUPPORT 0x00000001 /**< Priority Group(ETS) support. */ 545 #define ETH_DCB_PFC_SUPPORT 0x00000002 /**< Priority Flow Control support. */ 546 547 /* Definitions used for VLAN Offload functionality */ 548 #define ETH_VLAN_STRIP_OFFLOAD 0x0001 /**< VLAN Strip On/Off */ 549 #define ETH_VLAN_FILTER_OFFLOAD 0x0002 /**< VLAN Filter On/Off */ 550 #define ETH_VLAN_EXTEND_OFFLOAD 0x0004 /**< VLAN Extend On/Off */ 551 552 /* Definitions used for mask VLAN setting */ 553 #define ETH_VLAN_STRIP_MASK 0x0001 /**< VLAN Strip setting mask */ 554 #define ETH_VLAN_FILTER_MASK 0x0002 /**< VLAN Filter setting mask*/ 555 #define ETH_VLAN_EXTEND_MASK 0x0004 /**< VLAN Extend setting mask*/ 556 #define ETH_VLAN_ID_MAX 0x0FFF /**< VLAN ID is in lower 12 bits*/ 557 558 /* Definitions used for receive MAC address */ 559 #define ETH_NUM_RECEIVE_MAC_ADDR 128 /**< Maximum nb. of receive mac addr. */ 560 561 /* Definitions used for unicast hash */ 562 #define ETH_VMDQ_NUM_UC_HASH_ARRAY 128 /**< Maximum nb. of UC hash array. */ 563 564 /* Definitions used for VMDQ pool rx mode setting */ 565 #define ETH_VMDQ_ACCEPT_UNTAG 0x0001 /**< accept untagged packets. */ 566 #define ETH_VMDQ_ACCEPT_HASH_MC 0x0002 /**< accept packets in multicast table . */ 567 #define ETH_VMDQ_ACCEPT_HASH_UC 0x0004 /**< accept packets in unicast table. */ 568 #define ETH_VMDQ_ACCEPT_BROADCAST 0x0008 /**< accept broadcast packets. */ 569 #define ETH_VMDQ_ACCEPT_MULTICAST 0x0010 /**< multicast promiscuous. */ 570 571 /** Maximum nb. of vlan per mirror rule */ 572 #define ETH_MIRROR_MAX_VLANS 64 573 574 #define ETH_MIRROR_VIRTUAL_POOL_UP 0x01 /**< Virtual Pool uplink Mirroring. */ 575 #define ETH_MIRROR_UPLINK_PORT 0x02 /**< Uplink Port Mirroring. */ 576 #define ETH_MIRROR_DOWNLINK_PORT 0x04 /**< Downlink Port Mirroring. */ 577 #define ETH_MIRROR_VLAN 0x08 /**< VLAN Mirroring. */ 578 #define ETH_MIRROR_VIRTUAL_POOL_DOWN 0x10 /**< Virtual Pool downlink Mirroring. */ 579 580 /** 581 * A structure used to configure VLAN traffic mirror of an Ethernet port. 582 */ 583 struct rte_eth_vlan_mirror { 584 uint64_t vlan_mask; /**< mask for valid VLAN ID. */ 585 /** VLAN ID list for vlan mirroring. */ 586 uint16_t vlan_id[ETH_MIRROR_MAX_VLANS]; 587 }; 588 589 /** 590 * A structure used to configure traffic mirror of an Ethernet port. 591 */ 592 struct rte_eth_mirror_conf { 593 uint8_t rule_type; /**< Mirroring rule type */ 594 uint8_t dst_pool; /**< Destination pool for this mirror rule. */ 595 uint64_t pool_mask; /**< Bitmap of pool for pool mirroring */ 596 /** VLAN ID setting for VLAN mirroring. */ 597 struct rte_eth_vlan_mirror vlan; 598 }; 599 600 /** 601 * A structure used to configure 64 entries of Redirection Table of the 602 * Receive Side Scaling (RSS) feature of an Ethernet port. To configure 603 * more than 64 entries supported by hardware, an array of this structure 604 * is needed. 605 */ 606 struct rte_eth_rss_reta_entry64 { 607 uint64_t mask; 608 /**< Mask bits indicate which entries need to be updated/queried. */ 609 uint16_t reta[RTE_RETA_GROUP_SIZE]; 610 /**< Group of 64 redirection table entries. */ 611 }; 612 613 /** 614 * This enum indicates the possible number of traffic classes 615 * in DCB configurations 616 */ 617 enum rte_eth_nb_tcs { 618 ETH_4_TCS = 4, /**< 4 TCs with DCB. */ 619 ETH_8_TCS = 8 /**< 8 TCs with DCB. */ 620 }; 621 622 /** 623 * This enum indicates the possible number of queue pools 624 * in VMDQ configurations. 625 */ 626 enum rte_eth_nb_pools { 627 ETH_8_POOLS = 8, /**< 8 VMDq pools. */ 628 ETH_16_POOLS = 16, /**< 16 VMDq pools. */ 629 ETH_32_POOLS = 32, /**< 32 VMDq pools. */ 630 ETH_64_POOLS = 64 /**< 64 VMDq pools. */ 631 }; 632 633 /* This structure may be extended in future. */ 634 struct rte_eth_dcb_rx_conf { 635 enum rte_eth_nb_tcs nb_tcs; /**< Possible DCB TCs, 4 or 8 TCs */ 636 /** Traffic class each UP mapped to. */ 637 uint8_t dcb_tc[ETH_DCB_NUM_USER_PRIORITIES]; 638 }; 639 640 struct rte_eth_vmdq_dcb_tx_conf { 641 enum rte_eth_nb_pools nb_queue_pools; /**< With DCB, 16 or 32 pools. */ 642 /** Traffic class each UP mapped to. */ 643 uint8_t dcb_tc[ETH_DCB_NUM_USER_PRIORITIES]; 644 }; 645 646 struct rte_eth_dcb_tx_conf { 647 enum rte_eth_nb_tcs nb_tcs; /**< Possible DCB TCs, 4 or 8 TCs. */ 648 /** Traffic class each UP mapped to. */ 649 uint8_t dcb_tc[ETH_DCB_NUM_USER_PRIORITIES]; 650 }; 651 652 struct rte_eth_vmdq_tx_conf { 653 enum rte_eth_nb_pools nb_queue_pools; /**< VMDq mode, 64 pools. */ 654 }; 655 656 /** 657 * A structure used to configure the VMDQ+DCB feature 658 * of an Ethernet port. 659 * 660 * Using this feature, packets are routed to a pool of queues, based 661 * on the vlan id in the vlan tag, and then to a specific queue within 662 * that pool, using the user priority vlan tag field. 663 * 664 * A default pool may be used, if desired, to route all traffic which 665 * does not match the vlan filter rules. 666 */ 667 struct rte_eth_vmdq_dcb_conf { 668 enum rte_eth_nb_pools nb_queue_pools; /**< With DCB, 16 or 32 pools */ 669 uint8_t enable_default_pool; /**< If non-zero, use a default pool */ 670 uint8_t default_pool; /**< The default pool, if applicable */ 671 uint8_t nb_pool_maps; /**< We can have up to 64 filters/mappings */ 672 struct { 673 uint16_t vlan_id; /**< The vlan id of the received frame */ 674 uint64_t pools; /**< Bitmask of pools for packet rx */ 675 } pool_map[ETH_VMDQ_MAX_VLAN_FILTERS]; /**< VMDq vlan pool maps. */ 676 uint8_t dcb_tc[ETH_DCB_NUM_USER_PRIORITIES]; 677 /**< Selects a queue in a pool */ 678 }; 679 680 /** 681 * A structure used to configure the VMDQ feature of an Ethernet port when 682 * not combined with the DCB feature. 683 * 684 * Using this feature, packets are routed to a pool of queues. By default, 685 * the pool selection is based on the MAC address, the vlan id in the 686 * vlan tag as specified in the pool_map array. 687 * Passing the ETH_VMDQ_ACCEPT_UNTAG in the rx_mode field allows pool 688 * selection using only the MAC address. MAC address to pool mapping is done 689 * using the rte_eth_dev_mac_addr_add function, with the pool parameter 690 * corresponding to the pool id. 691 * 692 * Queue selection within the selected pool will be done using RSS when 693 * it is enabled or revert to the first queue of the pool if not. 694 * 695 * A default pool may be used, if desired, to route all traffic which 696 * does not match the vlan filter rules or any pool MAC address. 697 */ 698 struct rte_eth_vmdq_rx_conf { 699 enum rte_eth_nb_pools nb_queue_pools; /**< VMDq only mode, 8 or 64 pools */ 700 uint8_t enable_default_pool; /**< If non-zero, use a default pool */ 701 uint8_t default_pool; /**< The default pool, if applicable */ 702 uint8_t enable_loop_back; /**< Enable VT loop back */ 703 uint8_t nb_pool_maps; /**< We can have up to 64 filters/mappings */ 704 uint32_t rx_mode; /**< Flags from ETH_VMDQ_ACCEPT_* */ 705 struct { 706 uint16_t vlan_id; /**< The vlan id of the received frame */ 707 uint64_t pools; /**< Bitmask of pools for packet rx */ 708 } pool_map[ETH_VMDQ_MAX_VLAN_FILTERS]; /**< VMDq vlan pool maps. */ 709 }; 710 711 /** 712 * A structure used to configure the TX features of an Ethernet port. 713 */ 714 struct rte_eth_txmode { 715 enum rte_eth_tx_mq_mode mq_mode; /**< TX multi-queues mode. */ 716 /** 717 * Per-port Tx offloads to be set using DEV_TX_OFFLOAD_* flags. 718 * Only offloads set on tx_offload_capa field on rte_eth_dev_info 719 * structure are allowed to be set. 720 */ 721 uint64_t offloads; 722 723 /* For i40e specifically */ 724 uint16_t pvid; 725 __extension__ 726 uint8_t hw_vlan_reject_tagged : 1, 727 /**< If set, reject sending out tagged pkts */ 728 hw_vlan_reject_untagged : 1, 729 /**< If set, reject sending out untagged pkts */ 730 hw_vlan_insert_pvid : 1; 731 /**< If set, enable port based VLAN insertion */ 732 }; 733 734 /** 735 * A structure used to configure an RX ring of an Ethernet port. 736 */ 737 struct rte_eth_rxconf { 738 struct rte_eth_thresh rx_thresh; /**< RX ring threshold registers. */ 739 uint16_t rx_free_thresh; /**< Drives the freeing of RX descriptors. */ 740 uint8_t rx_drop_en; /**< Drop packets if no descriptors are available. */ 741 uint8_t rx_deferred_start; /**< Do not start queue with rte_eth_dev_start(). */ 742 /** 743 * Per-queue Rx offloads to be set using DEV_RX_OFFLOAD_* flags. 744 * Only offloads set on rx_queue_offload_capa or rx_offload_capa 745 * fields on rte_eth_dev_info structure are allowed to be set. 746 */ 747 uint64_t offloads; 748 }; 749 750 /** 751 * A structure used to configure a TX ring of an Ethernet port. 752 */ 753 struct rte_eth_txconf { 754 struct rte_eth_thresh tx_thresh; /**< TX ring threshold registers. */ 755 uint16_t tx_rs_thresh; /**< Drives the setting of RS bit on TXDs. */ 756 uint16_t tx_free_thresh; /**< Start freeing TX buffers if there are 757 less free descriptors than this value. */ 758 759 uint8_t tx_deferred_start; /**< Do not start queue with rte_eth_dev_start(). */ 760 /** 761 * Per-queue Tx offloads to be set using DEV_TX_OFFLOAD_* flags. 762 * Only offloads set on tx_queue_offload_capa or tx_offload_capa 763 * fields on rte_eth_dev_info structure are allowed to be set. 764 */ 765 uint64_t offloads; 766 }; 767 768 /** 769 * A structure contains information about HW descriptor ring limitations. 770 */ 771 struct rte_eth_desc_lim { 772 uint16_t nb_max; /**< Max allowed number of descriptors. */ 773 uint16_t nb_min; /**< Min allowed number of descriptors. */ 774 uint16_t nb_align; /**< Number of descriptors should be aligned to. */ 775 776 /** 777 * Max allowed number of segments per whole packet. 778 * 779 * - For TSO packet this is the total number of data descriptors allowed 780 * by device. 781 * 782 * @see nb_mtu_seg_max 783 */ 784 uint16_t nb_seg_max; 785 786 /** 787 * Max number of segments per one MTU. 788 * 789 * - For non-TSO packet, this is the maximum allowed number of segments 790 * in a single transmit packet. 791 * 792 * - For TSO packet each segment within the TSO may span up to this 793 * value. 794 * 795 * @see nb_seg_max 796 */ 797 uint16_t nb_mtu_seg_max; 798 }; 799 800 /** 801 * This enum indicates the flow control mode 802 */ 803 enum rte_eth_fc_mode { 804 RTE_FC_NONE = 0, /**< Disable flow control. */ 805 RTE_FC_RX_PAUSE, /**< RX pause frame, enable flowctrl on TX side. */ 806 RTE_FC_TX_PAUSE, /**< TX pause frame, enable flowctrl on RX side. */ 807 RTE_FC_FULL /**< Enable flow control on both side. */ 808 }; 809 810 /** 811 * A structure used to configure Ethernet flow control parameter. 812 * These parameters will be configured into the register of the NIC. 813 * Please refer to the corresponding data sheet for proper value. 814 */ 815 struct rte_eth_fc_conf { 816 uint32_t high_water; /**< High threshold value to trigger XOFF */ 817 uint32_t low_water; /**< Low threshold value to trigger XON */ 818 uint16_t pause_time; /**< Pause quota in the Pause frame */ 819 uint16_t send_xon; /**< Is XON frame need be sent */ 820 enum rte_eth_fc_mode mode; /**< Link flow control mode */ 821 uint8_t mac_ctrl_frame_fwd; /**< Forward MAC control frames */ 822 uint8_t autoneg; /**< Use Pause autoneg */ 823 }; 824 825 /** 826 * A structure used to configure Ethernet priority flow control parameter. 827 * These parameters will be configured into the register of the NIC. 828 * Please refer to the corresponding data sheet for proper value. 829 */ 830 struct rte_eth_pfc_conf { 831 struct rte_eth_fc_conf fc; /**< General flow control parameter. */ 832 uint8_t priority; /**< VLAN User Priority. */ 833 }; 834 835 /** 836 * Memory space that can be configured to store Flow Director filters 837 * in the board memory. 838 */ 839 enum rte_fdir_pballoc_type { 840 RTE_FDIR_PBALLOC_64K = 0, /**< 64k. */ 841 RTE_FDIR_PBALLOC_128K, /**< 128k. */ 842 RTE_FDIR_PBALLOC_256K, /**< 256k. */ 843 }; 844 845 /** 846 * Select report mode of FDIR hash information in RX descriptors. 847 */ 848 enum rte_fdir_status_mode { 849 RTE_FDIR_NO_REPORT_STATUS = 0, /**< Never report FDIR hash. */ 850 RTE_FDIR_REPORT_STATUS, /**< Only report FDIR hash for matching pkts. */ 851 RTE_FDIR_REPORT_STATUS_ALWAYS, /**< Always report FDIR hash. */ 852 }; 853 854 /** 855 * A structure used to configure the Flow Director (FDIR) feature 856 * of an Ethernet port. 857 * 858 * If mode is RTE_FDIR_DISABLE, the pballoc value is ignored. 859 */ 860 struct rte_fdir_conf { 861 enum rte_fdir_mode mode; /**< Flow Director mode. */ 862 enum rte_fdir_pballoc_type pballoc; /**< Space for FDIR filters. */ 863 enum rte_fdir_status_mode status; /**< How to report FDIR hash. */ 864 /** RX queue of packets matching a "drop" filter in perfect mode. */ 865 uint8_t drop_queue; 866 struct rte_eth_fdir_masks mask; 867 struct rte_eth_fdir_flex_conf flex_conf; 868 /**< Flex payload configuration. */ 869 }; 870 871 /** 872 * UDP tunneling configuration. 873 * Used to config the UDP port for a type of tunnel. 874 * NICs need the UDP port to identify the tunnel type. 875 * Normally a type of tunnel has a default UDP port, this structure can be used 876 * in case if the users want to change or support more UDP port. 877 */ 878 struct rte_eth_udp_tunnel { 879 uint16_t udp_port; /**< UDP port used for the tunnel. */ 880 uint8_t prot_type; /**< Tunnel type. Defined in rte_eth_tunnel_type. */ 881 }; 882 883 /** 884 * A structure used to enable/disable specific device interrupts. 885 */ 886 struct rte_intr_conf { 887 /** enable/disable lsc interrupt. 0 (default) - disable, 1 enable */ 888 uint32_t lsc:1; 889 /** enable/disable rxq interrupt. 0 (default) - disable, 1 enable */ 890 uint32_t rxq:1; 891 /** enable/disable rmv interrupt. 0 (default) - disable, 1 enable */ 892 uint32_t rmv:1; 893 }; 894 895 /** 896 * A structure used to configure an Ethernet port. 897 * Depending upon the RX multi-queue mode, extra advanced 898 * configuration settings may be needed. 899 */ 900 struct rte_eth_conf { 901 uint32_t link_speeds; /**< bitmap of ETH_LINK_SPEED_XXX of speeds to be 902 used. ETH_LINK_SPEED_FIXED disables link 903 autonegotiation, and a unique speed shall be 904 set. Otherwise, the bitmap defines the set of 905 speeds to be advertised. If the special value 906 ETH_LINK_SPEED_AUTONEG (0) is used, all speeds 907 supported are advertised. */ 908 struct rte_eth_rxmode rxmode; /**< Port RX configuration. */ 909 struct rte_eth_txmode txmode; /**< Port TX configuration. */ 910 uint32_t lpbk_mode; /**< Loopback operation mode. By default the value 911 is 0, meaning the loopback mode is disabled. 912 Read the datasheet of given ethernet controller 913 for details. The possible values of this field 914 are defined in implementation of each driver. */ 915 struct { 916 struct rte_eth_rss_conf rss_conf; /**< Port RSS configuration */ 917 struct rte_eth_vmdq_dcb_conf vmdq_dcb_conf; 918 /**< Port vmdq+dcb configuration. */ 919 struct rte_eth_dcb_rx_conf dcb_rx_conf; 920 /**< Port dcb RX configuration. */ 921 struct rte_eth_vmdq_rx_conf vmdq_rx_conf; 922 /**< Port vmdq RX configuration. */ 923 } rx_adv_conf; /**< Port RX filtering configuration. */ 924 union { 925 struct rte_eth_vmdq_dcb_tx_conf vmdq_dcb_tx_conf; 926 /**< Port vmdq+dcb TX configuration. */ 927 struct rte_eth_dcb_tx_conf dcb_tx_conf; 928 /**< Port dcb TX configuration. */ 929 struct rte_eth_vmdq_tx_conf vmdq_tx_conf; 930 /**< Port vmdq TX configuration. */ 931 } tx_adv_conf; /**< Port TX DCB configuration (union). */ 932 /** Currently,Priority Flow Control(PFC) are supported,if DCB with PFC 933 is needed,and the variable must be set ETH_DCB_PFC_SUPPORT. */ 934 uint32_t dcb_capability_en; 935 struct rte_fdir_conf fdir_conf; /**< FDIR configuration. */ 936 struct rte_intr_conf intr_conf; /**< Interrupt mode configuration. */ 937 }; 938 939 /** 940 * RX offload capabilities of a device. 941 */ 942 #define DEV_RX_OFFLOAD_VLAN_STRIP 0x00000001 943 #define DEV_RX_OFFLOAD_IPV4_CKSUM 0x00000002 944 #define DEV_RX_OFFLOAD_UDP_CKSUM 0x00000004 945 #define DEV_RX_OFFLOAD_TCP_CKSUM 0x00000008 946 #define DEV_RX_OFFLOAD_TCP_LRO 0x00000010 947 #define DEV_RX_OFFLOAD_QINQ_STRIP 0x00000020 948 #define DEV_RX_OFFLOAD_OUTER_IPV4_CKSUM 0x00000040 949 #define DEV_RX_OFFLOAD_MACSEC_STRIP 0x00000080 950 #define DEV_RX_OFFLOAD_HEADER_SPLIT 0x00000100 951 #define DEV_RX_OFFLOAD_VLAN_FILTER 0x00000200 952 #define DEV_RX_OFFLOAD_VLAN_EXTEND 0x00000400 953 #define DEV_RX_OFFLOAD_JUMBO_FRAME 0x00000800 954 #define DEV_RX_OFFLOAD_SCATTER 0x00002000 955 #define DEV_RX_OFFLOAD_TIMESTAMP 0x00004000 956 #define DEV_RX_OFFLOAD_SECURITY 0x00008000 957 #define DEV_RX_OFFLOAD_KEEP_CRC 0x00010000 958 #define DEV_RX_OFFLOAD_SCTP_CKSUM 0x00020000 959 #define DEV_RX_OFFLOAD_OUTER_UDP_CKSUM 0x00040000 960 961 #define DEV_RX_OFFLOAD_CHECKSUM (DEV_RX_OFFLOAD_IPV4_CKSUM | \ 962 DEV_RX_OFFLOAD_UDP_CKSUM | \ 963 DEV_RX_OFFLOAD_TCP_CKSUM) 964 #define DEV_RX_OFFLOAD_VLAN (DEV_RX_OFFLOAD_VLAN_STRIP | \ 965 DEV_RX_OFFLOAD_VLAN_FILTER | \ 966 DEV_RX_OFFLOAD_VLAN_EXTEND) 967 968 /* 969 * If new Rx offload capabilities are defined, they also must be 970 * mentioned in rte_rx_offload_names in rte_ethdev.c file. 971 */ 972 973 /** 974 * TX offload capabilities of a device. 975 */ 976 #define DEV_TX_OFFLOAD_VLAN_INSERT 0x00000001 977 #define DEV_TX_OFFLOAD_IPV4_CKSUM 0x00000002 978 #define DEV_TX_OFFLOAD_UDP_CKSUM 0x00000004 979 #define DEV_TX_OFFLOAD_TCP_CKSUM 0x00000008 980 #define DEV_TX_OFFLOAD_SCTP_CKSUM 0x00000010 981 #define DEV_TX_OFFLOAD_TCP_TSO 0x00000020 982 #define DEV_TX_OFFLOAD_UDP_TSO 0x00000040 983 #define DEV_TX_OFFLOAD_OUTER_IPV4_CKSUM 0x00000080 /**< Used for tunneling packet. */ 984 #define DEV_TX_OFFLOAD_QINQ_INSERT 0x00000100 985 #define DEV_TX_OFFLOAD_VXLAN_TNL_TSO 0x00000200 /**< Used for tunneling packet. */ 986 #define DEV_TX_OFFLOAD_GRE_TNL_TSO 0x00000400 /**< Used for tunneling packet. */ 987 #define DEV_TX_OFFLOAD_IPIP_TNL_TSO 0x00000800 /**< Used for tunneling packet. */ 988 #define DEV_TX_OFFLOAD_GENEVE_TNL_TSO 0x00001000 /**< Used for tunneling packet. */ 989 #define DEV_TX_OFFLOAD_MACSEC_INSERT 0x00002000 990 #define DEV_TX_OFFLOAD_MT_LOCKFREE 0x00004000 991 /**< Multiple threads can invoke rte_eth_tx_burst() concurrently on the same 992 * tx queue without SW lock. 993 */ 994 #define DEV_TX_OFFLOAD_MULTI_SEGS 0x00008000 995 /**< Device supports multi segment send. */ 996 #define DEV_TX_OFFLOAD_MBUF_FAST_FREE 0x00010000 997 /**< Device supports optimization for fast release of mbufs. 998 * When set application must guarantee that per-queue all mbufs comes from 999 * the same mempool and has refcnt = 1. 1000 */ 1001 #define DEV_TX_OFFLOAD_SECURITY 0x00020000 1002 /** 1003 * Device supports generic UDP tunneled packet TSO. 1004 * Application must set PKT_TX_TUNNEL_UDP and other mbuf fields required 1005 * for tunnel TSO. 1006 */ 1007 #define DEV_TX_OFFLOAD_UDP_TNL_TSO 0x00040000 1008 /** 1009 * Device supports generic IP tunneled packet TSO. 1010 * Application must set PKT_TX_TUNNEL_IP and other mbuf fields required 1011 * for tunnel TSO. 1012 */ 1013 #define DEV_TX_OFFLOAD_IP_TNL_TSO 0x00080000 1014 /** Device supports outer UDP checksum */ 1015 #define DEV_TX_OFFLOAD_OUTER_UDP_CKSUM 0x00100000 1016 /** 1017 * Device supports match on metadata Tx offload.. 1018 * Application must set PKT_TX_METADATA and mbuf metadata field. 1019 */ 1020 #define DEV_TX_OFFLOAD_MATCH_METADATA 0x00200000 1021 1022 #define RTE_ETH_DEV_CAPA_RUNTIME_RX_QUEUE_SETUP 0x00000001 1023 /**< Device supports Rx queue setup after device started*/ 1024 #define RTE_ETH_DEV_CAPA_RUNTIME_TX_QUEUE_SETUP 0x00000002 1025 /**< Device supports Tx queue setup after device started*/ 1026 1027 /* 1028 * If new Tx offload capabilities are defined, they also must be 1029 * mentioned in rte_tx_offload_names in rte_ethdev.c file. 1030 */ 1031 1032 /* 1033 * Fallback default preferred Rx/Tx port parameters. 1034 * These are used if an application requests default parameters 1035 * but the PMD does not provide preferred values. 1036 */ 1037 #define RTE_ETH_DEV_FALLBACK_RX_RINGSIZE 512 1038 #define RTE_ETH_DEV_FALLBACK_TX_RINGSIZE 512 1039 #define RTE_ETH_DEV_FALLBACK_RX_NBQUEUES 1 1040 #define RTE_ETH_DEV_FALLBACK_TX_NBQUEUES 1 1041 1042 /** 1043 * Preferred Rx/Tx port parameters. 1044 * There are separate instances of this structure for transmission 1045 * and reception respectively. 1046 */ 1047 struct rte_eth_dev_portconf { 1048 uint16_t burst_size; /**< Device-preferred burst size */ 1049 uint16_t ring_size; /**< Device-preferred size of queue rings */ 1050 uint16_t nb_queues; /**< Device-preferred number of queues */ 1051 }; 1052 1053 /** 1054 * Default values for switch domain id when ethdev does not support switch 1055 * domain definitions. 1056 */ 1057 #define RTE_ETH_DEV_SWITCH_DOMAIN_ID_INVALID (0) 1058 1059 /** 1060 * Ethernet device associated switch information 1061 */ 1062 struct rte_eth_switch_info { 1063 const char *name; /**< switch name */ 1064 uint16_t domain_id; /**< switch domain id */ 1065 uint16_t port_id; 1066 /**< 1067 * mapping to the devices physical switch port as enumerated from the 1068 * perspective of the embedded interconnect/switch. For SR-IOV enabled 1069 * device this may correspond to the VF_ID of each virtual function, 1070 * but each driver should explicitly define the mapping of switch 1071 * port identifier to that physical interconnect/switch 1072 */ 1073 }; 1074 1075 /** 1076 * Ethernet device information 1077 */ 1078 1079 /** 1080 * A structure used to retrieve the contextual information of 1081 * an Ethernet device, such as the controlling driver of the 1082 * device, etc... 1083 */ 1084 struct rte_eth_dev_info { 1085 struct rte_device *device; /** Generic device information */ 1086 const char *driver_name; /**< Device Driver name. */ 1087 unsigned int if_index; /**< Index to bound host interface, or 0 if none. 1088 Use if_indextoname() to translate into an interface name. */ 1089 const uint32_t *dev_flags; /**< Device flags */ 1090 uint32_t min_rx_bufsize; /**< Minimum size of RX buffer. */ 1091 uint32_t max_rx_pktlen; /**< Maximum configurable length of RX pkt. */ 1092 uint16_t max_rx_queues; /**< Maximum number of RX queues. */ 1093 uint16_t max_tx_queues; /**< Maximum number of TX queues. */ 1094 uint32_t max_mac_addrs; /**< Maximum number of MAC addresses. */ 1095 uint32_t max_hash_mac_addrs; 1096 /** Maximum number of hash MAC addresses for MTA and UTA. */ 1097 uint16_t max_vfs; /**< Maximum number of VFs. */ 1098 uint16_t max_vmdq_pools; /**< Maximum number of VMDq pools. */ 1099 uint64_t rx_offload_capa; 1100 /**< All RX offload capabilities including all per-queue ones */ 1101 uint64_t tx_offload_capa; 1102 /**< All TX offload capabilities including all per-queue ones */ 1103 uint64_t rx_queue_offload_capa; 1104 /**< Device per-queue RX offload capabilities. */ 1105 uint64_t tx_queue_offload_capa; 1106 /**< Device per-queue TX offload capabilities. */ 1107 uint16_t reta_size; 1108 /**< Device redirection table size, the total number of entries. */ 1109 uint8_t hash_key_size; /**< Hash key size in bytes */ 1110 /** Bit mask of RSS offloads, the bit offset also means flow type */ 1111 uint64_t flow_type_rss_offloads; 1112 struct rte_eth_rxconf default_rxconf; /**< Default RX configuration */ 1113 struct rte_eth_txconf default_txconf; /**< Default TX configuration */ 1114 uint16_t vmdq_queue_base; /**< First queue ID for VMDQ pools. */ 1115 uint16_t vmdq_queue_num; /**< Queue number for VMDQ pools. */ 1116 uint16_t vmdq_pool_base; /**< First ID of VMDQ pools. */ 1117 struct rte_eth_desc_lim rx_desc_lim; /**< RX descriptors limits */ 1118 struct rte_eth_desc_lim tx_desc_lim; /**< TX descriptors limits */ 1119 uint32_t speed_capa; /**< Supported speeds bitmap (ETH_LINK_SPEED_). */ 1120 /** Configured number of rx/tx queues */ 1121 uint16_t nb_rx_queues; /**< Number of RX queues. */ 1122 uint16_t nb_tx_queues; /**< Number of TX queues. */ 1123 /** Rx parameter recommendations */ 1124 struct rte_eth_dev_portconf default_rxportconf; 1125 /** Tx parameter recommendations */ 1126 struct rte_eth_dev_portconf default_txportconf; 1127 /** Generic device capabilities (RTE_ETH_DEV_CAPA_). */ 1128 uint64_t dev_capa; 1129 /** 1130 * Switching information for ports on a device with a 1131 * embedded managed interconnect/switch. 1132 */ 1133 struct rte_eth_switch_info switch_info; 1134 }; 1135 1136 /** 1137 * Ethernet device RX queue information structure. 1138 * Used to retrieve information about configured queue. 1139 */ 1140 struct rte_eth_rxq_info { 1141 struct rte_mempool *mp; /**< mempool used by that queue. */ 1142 struct rte_eth_rxconf conf; /**< queue config parameters. */ 1143 uint8_t scattered_rx; /**< scattered packets RX supported. */ 1144 uint16_t nb_desc; /**< configured number of RXDs. */ 1145 } __rte_cache_min_aligned; 1146 1147 /** 1148 * Ethernet device TX queue information structure. 1149 * Used to retrieve information about configured queue. 1150 */ 1151 struct rte_eth_txq_info { 1152 struct rte_eth_txconf conf; /**< queue config parameters. */ 1153 uint16_t nb_desc; /**< configured number of TXDs. */ 1154 } __rte_cache_min_aligned; 1155 1156 /** Maximum name length for extended statistics counters */ 1157 #define RTE_ETH_XSTATS_NAME_SIZE 64 1158 1159 /** 1160 * An Ethernet device extended statistic structure 1161 * 1162 * This structure is used by rte_eth_xstats_get() to provide 1163 * statistics that are not provided in the generic *rte_eth_stats* 1164 * structure. 1165 * It maps a name id, corresponding to an index in the array returned 1166 * by rte_eth_xstats_get_names(), to a statistic value. 1167 */ 1168 struct rte_eth_xstat { 1169 uint64_t id; /**< The index in xstats name array. */ 1170 uint64_t value; /**< The statistic counter value. */ 1171 }; 1172 1173 /** 1174 * A name element for extended statistics. 1175 * 1176 * An array of this structure is returned by rte_eth_xstats_get_names(). 1177 * It lists the names of extended statistics for a PMD. The *rte_eth_xstat* 1178 * structure references these names by their array index. 1179 */ 1180 struct rte_eth_xstat_name { 1181 char name[RTE_ETH_XSTATS_NAME_SIZE]; /**< The statistic name. */ 1182 }; 1183 1184 #define ETH_DCB_NUM_TCS 8 1185 #define ETH_MAX_VMDQ_POOL 64 1186 1187 /** 1188 * A structure used to get the information of queue and 1189 * TC mapping on both TX and RX paths. 1190 */ 1191 struct rte_eth_dcb_tc_queue_mapping { 1192 /** rx queues assigned to tc per Pool */ 1193 struct { 1194 uint8_t base; 1195 uint8_t nb_queue; 1196 } tc_rxq[ETH_MAX_VMDQ_POOL][ETH_DCB_NUM_TCS]; 1197 /** rx queues assigned to tc per Pool */ 1198 struct { 1199 uint8_t base; 1200 uint8_t nb_queue; 1201 } tc_txq[ETH_MAX_VMDQ_POOL][ETH_DCB_NUM_TCS]; 1202 }; 1203 1204 /** 1205 * A structure used to get the information of DCB. 1206 * It includes TC UP mapping and queue TC mapping. 1207 */ 1208 struct rte_eth_dcb_info { 1209 uint8_t nb_tcs; /**< number of TCs */ 1210 uint8_t prio_tc[ETH_DCB_NUM_USER_PRIORITIES]; /**< Priority to tc */ 1211 uint8_t tc_bws[ETH_DCB_NUM_TCS]; /**< TX BW percentage for each TC */ 1212 /** rx queues assigned to tc */ 1213 struct rte_eth_dcb_tc_queue_mapping tc_queue; 1214 }; 1215 1216 /** 1217 * RX/TX queue states 1218 */ 1219 #define RTE_ETH_QUEUE_STATE_STOPPED 0 1220 #define RTE_ETH_QUEUE_STATE_STARTED 1 1221 1222 #define RTE_ETH_ALL RTE_MAX_ETHPORTS 1223 1224 /* Macros to check for valid port */ 1225 #define RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, retval) do { \ 1226 if (!rte_eth_dev_is_valid_port(port_id)) { \ 1227 RTE_ETHDEV_LOG(ERR, "Invalid port_id=%u\n", port_id); \ 1228 return retval; \ 1229 } \ 1230 } while (0) 1231 1232 #define RTE_ETH_VALID_PORTID_OR_RET(port_id) do { \ 1233 if (!rte_eth_dev_is_valid_port(port_id)) { \ 1234 RTE_ETHDEV_LOG(ERR, "Invalid port_id=%u\n", port_id); \ 1235 return; \ 1236 } \ 1237 } while (0) 1238 1239 /** 1240 * l2 tunnel configuration. 1241 */ 1242 1243 /**< l2 tunnel enable mask */ 1244 #define ETH_L2_TUNNEL_ENABLE_MASK 0x00000001 1245 /**< l2 tunnel insertion mask */ 1246 #define ETH_L2_TUNNEL_INSERTION_MASK 0x00000002 1247 /**< l2 tunnel stripping mask */ 1248 #define ETH_L2_TUNNEL_STRIPPING_MASK 0x00000004 1249 /**< l2 tunnel forwarding mask */ 1250 #define ETH_L2_TUNNEL_FORWARDING_MASK 0x00000008 1251 1252 /** 1253 * Function type used for RX packet processing packet callbacks. 1254 * 1255 * The callback function is called on RX with a burst of packets that have 1256 * been received on the given port and queue. 1257 * 1258 * @param port_id 1259 * The Ethernet port on which RX is being performed. 1260 * @param queue 1261 * The queue on the Ethernet port which is being used to receive the packets. 1262 * @param pkts 1263 * The burst of packets that have just been received. 1264 * @param nb_pkts 1265 * The number of packets in the burst pointed to by "pkts". 1266 * @param max_pkts 1267 * The max number of packets that can be stored in the "pkts" array. 1268 * @param user_param 1269 * The arbitrary user parameter passed in by the application when the callback 1270 * was originally configured. 1271 * @return 1272 * The number of packets returned to the user. 1273 */ 1274 typedef uint16_t (*rte_rx_callback_fn)(uint16_t port_id, uint16_t queue, 1275 struct rte_mbuf *pkts[], uint16_t nb_pkts, uint16_t max_pkts, 1276 void *user_param); 1277 1278 /** 1279 * Function type used for TX packet processing packet callbacks. 1280 * 1281 * The callback function is called on TX with a burst of packets immediately 1282 * before the packets are put onto the hardware queue for transmission. 1283 * 1284 * @param port_id 1285 * The Ethernet port on which TX is being performed. 1286 * @param queue 1287 * The queue on the Ethernet port which is being used to transmit the packets. 1288 * @param pkts 1289 * The burst of packets that are about to be transmitted. 1290 * @param nb_pkts 1291 * The number of packets in the burst pointed to by "pkts". 1292 * @param user_param 1293 * The arbitrary user parameter passed in by the application when the callback 1294 * was originally configured. 1295 * @return 1296 * The number of packets to be written to the NIC. 1297 */ 1298 typedef uint16_t (*rte_tx_callback_fn)(uint16_t port_id, uint16_t queue, 1299 struct rte_mbuf *pkts[], uint16_t nb_pkts, void *user_param); 1300 1301 /** 1302 * Possible states of an ethdev port. 1303 */ 1304 enum rte_eth_dev_state { 1305 /** Device is unused before being probed. */ 1306 RTE_ETH_DEV_UNUSED = 0, 1307 /** Device is attached when allocated in probing. */ 1308 RTE_ETH_DEV_ATTACHED, 1309 /** Device is in removed state when plug-out is detected. */ 1310 RTE_ETH_DEV_REMOVED, 1311 }; 1312 1313 struct rte_eth_dev_sriov { 1314 uint8_t active; /**< SRIOV is active with 16, 32 or 64 pools */ 1315 uint8_t nb_q_per_pool; /**< rx queue number per pool */ 1316 uint16_t def_vmdq_idx; /**< Default pool num used for PF */ 1317 uint16_t def_pool_q_idx; /**< Default pool queue start reg index */ 1318 }; 1319 #define RTE_ETH_DEV_SRIOV(dev) ((dev)->data->sriov) 1320 1321 #define RTE_ETH_NAME_MAX_LEN RTE_DEV_NAME_MAX_LEN 1322 1323 #define RTE_ETH_DEV_NO_OWNER 0 1324 1325 #define RTE_ETH_MAX_OWNER_NAME_LEN 64 1326 1327 struct rte_eth_dev_owner { 1328 uint64_t id; /**< The owner unique identifier. */ 1329 char name[RTE_ETH_MAX_OWNER_NAME_LEN]; /**< The owner name. */ 1330 }; 1331 1332 /** 1333 * Port is released (i.e. totally freed and data erased) on close. 1334 * Temporary flag for PMD migration to new rte_eth_dev_close() behaviour. 1335 */ 1336 #define RTE_ETH_DEV_CLOSE_REMOVE 0x0001 1337 /** Device supports link state interrupt */ 1338 #define RTE_ETH_DEV_INTR_LSC 0x0002 1339 /** Device is a bonded slave */ 1340 #define RTE_ETH_DEV_BONDED_SLAVE 0x0004 1341 /** Device supports device removal interrupt */ 1342 #define RTE_ETH_DEV_INTR_RMV 0x0008 1343 /** Device is port representor */ 1344 #define RTE_ETH_DEV_REPRESENTOR 0x0010 1345 /** Device does not support MAC change after started */ 1346 #define RTE_ETH_DEV_NOLIVE_MAC_ADDR 0x0020 1347 1348 /** 1349 * Iterates over valid ethdev ports owned by a specific owner. 1350 * 1351 * @param port_id 1352 * The id of the next possible valid owned port. 1353 * @param owner_id 1354 * The owner identifier. 1355 * RTE_ETH_DEV_NO_OWNER means iterate over all valid ownerless ports. 1356 * @return 1357 * Next valid port id owned by owner_id, RTE_MAX_ETHPORTS if there is none. 1358 */ 1359 uint64_t rte_eth_find_next_owned_by(uint16_t port_id, 1360 const uint64_t owner_id); 1361 1362 /** 1363 * Macro to iterate over all enabled ethdev ports owned by a specific owner. 1364 */ 1365 #define RTE_ETH_FOREACH_DEV_OWNED_BY(p, o) \ 1366 for (p = rte_eth_find_next_owned_by(0, o); \ 1367 (unsigned int)p < (unsigned int)RTE_MAX_ETHPORTS; \ 1368 p = rte_eth_find_next_owned_by(p + 1, o)) 1369 1370 /** 1371 * Iterates over valid ethdev ports. 1372 * 1373 * @param port_id 1374 * The id of the next possible valid port. 1375 * @return 1376 * Next valid port id, RTE_MAX_ETHPORTS if there is none. 1377 */ 1378 uint16_t rte_eth_find_next(uint16_t port_id); 1379 1380 /** 1381 * Macro to iterate over all enabled and ownerless ethdev ports. 1382 */ 1383 #define RTE_ETH_FOREACH_DEV(p) \ 1384 RTE_ETH_FOREACH_DEV_OWNED_BY(p, RTE_ETH_DEV_NO_OWNER) 1385 1386 1387 /** 1388 * @warning 1389 * @b EXPERIMENTAL: this API may change without prior notice. 1390 * 1391 * Get a new unique owner identifier. 1392 * An owner identifier is used to owns Ethernet devices by only one DPDK entity 1393 * to avoid multiple management of device by different entities. 1394 * 1395 * @param owner_id 1396 * Owner identifier pointer. 1397 * @return 1398 * Negative errno value on error, 0 on success. 1399 */ 1400 int __rte_experimental rte_eth_dev_owner_new(uint64_t *owner_id); 1401 1402 /** 1403 * @warning 1404 * @b EXPERIMENTAL: this API may change without prior notice. 1405 * 1406 * Set an Ethernet device owner. 1407 * 1408 * @param port_id 1409 * The identifier of the port to own. 1410 * @param owner 1411 * The owner pointer. 1412 * @return 1413 * Negative errno value on error, 0 on success. 1414 */ 1415 int __rte_experimental rte_eth_dev_owner_set(const uint16_t port_id, 1416 const struct rte_eth_dev_owner *owner); 1417 1418 /** 1419 * @warning 1420 * @b EXPERIMENTAL: this API may change without prior notice. 1421 * 1422 * Unset Ethernet device owner to make the device ownerless. 1423 * 1424 * @param port_id 1425 * The identifier of port to make ownerless. 1426 * @param owner_id 1427 * The owner identifier. 1428 * @return 1429 * 0 on success, negative errno value on error. 1430 */ 1431 int __rte_experimental rte_eth_dev_owner_unset(const uint16_t port_id, 1432 const uint64_t owner_id); 1433 1434 /** 1435 * @warning 1436 * @b EXPERIMENTAL: this API may change without prior notice. 1437 * 1438 * Remove owner from all Ethernet devices owned by a specific owner. 1439 * 1440 * @param owner_id 1441 * The owner identifier. 1442 */ 1443 void __rte_experimental rte_eth_dev_owner_delete(const uint64_t owner_id); 1444 1445 /** 1446 * @warning 1447 * @b EXPERIMENTAL: this API may change without prior notice. 1448 * 1449 * Get the owner of an Ethernet device. 1450 * 1451 * @param port_id 1452 * The port identifier. 1453 * @param owner 1454 * The owner structure pointer to fill. 1455 * @return 1456 * 0 on success, negative errno value on error.. 1457 */ 1458 int __rte_experimental rte_eth_dev_owner_get(const uint16_t port_id, 1459 struct rte_eth_dev_owner *owner); 1460 1461 /** 1462 * Get the total number of Ethernet devices that have been successfully 1463 * initialized by the matching Ethernet driver during the PCI probing phase 1464 * and that are available for applications to use. These devices must be 1465 * accessed by using the ``RTE_ETH_FOREACH_DEV()`` macro to deal with 1466 * non-contiguous ranges of devices. 1467 * These non-contiguous ranges can be created by calls to hotplug functions or 1468 * by some PMDs. 1469 * 1470 * @return 1471 * - The total number of usable Ethernet devices. 1472 */ 1473 __rte_deprecated 1474 uint16_t rte_eth_dev_count(void); 1475 1476 /** 1477 * Get the number of ports which are usable for the application. 1478 * 1479 * These devices must be iterated by using the macro 1480 * ``RTE_ETH_FOREACH_DEV`` or ``RTE_ETH_FOREACH_DEV_OWNED_BY`` 1481 * to deal with non-contiguous ranges of devices. 1482 * 1483 * @return 1484 * The count of available Ethernet devices. 1485 */ 1486 uint16_t rte_eth_dev_count_avail(void); 1487 1488 /** 1489 * Get the total number of ports which are allocated. 1490 * 1491 * Some devices may not be available for the application. 1492 * 1493 * @return 1494 * The total count of Ethernet devices. 1495 */ 1496 uint16_t __rte_experimental rte_eth_dev_count_total(void); 1497 1498 /** 1499 * Convert a numerical speed in Mbps to a bitmap flag that can be used in 1500 * the bitmap link_speeds of the struct rte_eth_conf 1501 * 1502 * @param speed 1503 * Numerical speed value in Mbps 1504 * @param duplex 1505 * ETH_LINK_[HALF/FULL]_DUPLEX (only for 10/100M speeds) 1506 * @return 1507 * 0 if the speed cannot be mapped 1508 */ 1509 uint32_t rte_eth_speed_bitflag(uint32_t speed, int duplex); 1510 1511 /** 1512 * Get DEV_RX_OFFLOAD_* flag name. 1513 * 1514 * @param offload 1515 * Offload flag. 1516 * @return 1517 * Offload name or 'UNKNOWN' if the flag cannot be recognised. 1518 */ 1519 const char *rte_eth_dev_rx_offload_name(uint64_t offload); 1520 1521 /** 1522 * Get DEV_TX_OFFLOAD_* flag name. 1523 * 1524 * @param offload 1525 * Offload flag. 1526 * @return 1527 * Offload name or 'UNKNOWN' if the flag cannot be recognised. 1528 */ 1529 const char *rte_eth_dev_tx_offload_name(uint64_t offload); 1530 1531 /** 1532 * Configure an Ethernet device. 1533 * This function must be invoked first before any other function in the 1534 * Ethernet API. This function can also be re-invoked when a device is in the 1535 * stopped state. 1536 * 1537 * @param port_id 1538 * The port identifier of the Ethernet device to configure. 1539 * @param nb_rx_queue 1540 * The number of receive queues to set up for the Ethernet device. 1541 * @param nb_tx_queue 1542 * The number of transmit queues to set up for the Ethernet device. 1543 * @param eth_conf 1544 * The pointer to the configuration data to be used for the Ethernet device. 1545 * The *rte_eth_conf* structure includes: 1546 * - the hardware offload features to activate, with dedicated fields for 1547 * each statically configurable offload hardware feature provided by 1548 * Ethernet devices, such as IP checksum or VLAN tag stripping for 1549 * example. 1550 * The Rx offload bitfield API is obsolete and will be deprecated. 1551 * Applications should set the ignore_bitfield_offloads bit on *rxmode* 1552 * structure and use offloads field to set per-port offloads instead. 1553 * - Any offloading set in eth_conf->[rt]xmode.offloads must be within 1554 * the [rt]x_offload_capa returned from rte_eth_dev_info_get(). 1555 * Any type of device supported offloading set in the input argument 1556 * eth_conf->[rt]xmode.offloads to rte_eth_dev_configure() is enabled 1557 * on all queues and it can't be disabled in rte_eth_[rt]x_queue_setup() 1558 * - the Receive Side Scaling (RSS) configuration when using multiple RX 1559 * queues per port. Any RSS hash function set in eth_conf->rss_conf.rss_hf 1560 * must be within the flow_type_rss_offloads provided by drivers via 1561 * rte_eth_dev_info_get() API. 1562 * 1563 * Embedding all configuration information in a single data structure 1564 * is the more flexible method that allows the addition of new features 1565 * without changing the syntax of the API. 1566 * @return 1567 * - 0: Success, device configured. 1568 * - <0: Error code returned by the driver configuration function. 1569 */ 1570 int rte_eth_dev_configure(uint16_t port_id, uint16_t nb_rx_queue, 1571 uint16_t nb_tx_queue, const struct rte_eth_conf *eth_conf); 1572 1573 /** 1574 * @warning 1575 * @b EXPERIMENTAL: this API may change without prior notice. 1576 * 1577 * Check if an Ethernet device was physically removed. 1578 * 1579 * @param port_id 1580 * The port identifier of the Ethernet device. 1581 * @return 1582 * 1 when the Ethernet device is removed, otherwise 0. 1583 */ 1584 int __rte_experimental 1585 rte_eth_dev_is_removed(uint16_t port_id); 1586 1587 /** 1588 * Allocate and set up a receive queue for an Ethernet device. 1589 * 1590 * The function allocates a contiguous block of memory for *nb_rx_desc* 1591 * receive descriptors from a memory zone associated with *socket_id* 1592 * and initializes each receive descriptor with a network buffer allocated 1593 * from the memory pool *mb_pool*. 1594 * 1595 * @param port_id 1596 * The port identifier of the Ethernet device. 1597 * @param rx_queue_id 1598 * The index of the receive queue to set up. 1599 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 1600 * to rte_eth_dev_configure(). 1601 * @param nb_rx_desc 1602 * The number of receive descriptors to allocate for the receive ring. 1603 * @param socket_id 1604 * The *socket_id* argument is the socket identifier in case of NUMA. 1605 * The value can be *SOCKET_ID_ANY* if there is no NUMA constraint for 1606 * the DMA memory allocated for the receive descriptors of the ring. 1607 * @param rx_conf 1608 * The pointer to the configuration data to be used for the receive queue. 1609 * NULL value is allowed, in which case default RX configuration 1610 * will be used. 1611 * The *rx_conf* structure contains an *rx_thresh* structure with the values 1612 * of the Prefetch, Host, and Write-Back threshold registers of the receive 1613 * ring. 1614 * In addition it contains the hardware offloads features to activate using 1615 * the DEV_RX_OFFLOAD_* flags. 1616 * If an offloading set in rx_conf->offloads 1617 * hasn't been set in the input argument eth_conf->rxmode.offloads 1618 * to rte_eth_dev_configure(), it is a new added offloading, it must be 1619 * per-queue type and it is enabled for the queue. 1620 * No need to repeat any bit in rx_conf->offloads which has already been 1621 * enabled in rte_eth_dev_configure() at port level. An offloading enabled 1622 * at port level can't be disabled at queue level. 1623 * @param mb_pool 1624 * The pointer to the memory pool from which to allocate *rte_mbuf* network 1625 * memory buffers to populate each descriptor of the receive ring. 1626 * @return 1627 * - 0: Success, receive queue correctly set up. 1628 * - -EIO: if device is removed. 1629 * - -EINVAL: The size of network buffers which can be allocated from the 1630 * memory pool does not fit the various buffer sizes allowed by the 1631 * device controller. 1632 * - -ENOMEM: Unable to allocate the receive ring descriptors or to 1633 * allocate network memory buffers from the memory pool when 1634 * initializing receive descriptors. 1635 */ 1636 int rte_eth_rx_queue_setup(uint16_t port_id, uint16_t rx_queue_id, 1637 uint16_t nb_rx_desc, unsigned int socket_id, 1638 const struct rte_eth_rxconf *rx_conf, 1639 struct rte_mempool *mb_pool); 1640 1641 /** 1642 * Allocate and set up a transmit queue for an Ethernet device. 1643 * 1644 * @param port_id 1645 * The port identifier of the Ethernet device. 1646 * @param tx_queue_id 1647 * The index of the transmit queue to set up. 1648 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 1649 * to rte_eth_dev_configure(). 1650 * @param nb_tx_desc 1651 * The number of transmit descriptors to allocate for the transmit ring. 1652 * @param socket_id 1653 * The *socket_id* argument is the socket identifier in case of NUMA. 1654 * Its value can be *SOCKET_ID_ANY* if there is no NUMA constraint for 1655 * the DMA memory allocated for the transmit descriptors of the ring. 1656 * @param tx_conf 1657 * The pointer to the configuration data to be used for the transmit queue. 1658 * NULL value is allowed, in which case default TX configuration 1659 * will be used. 1660 * The *tx_conf* structure contains the following data: 1661 * - The *tx_thresh* structure with the values of the Prefetch, Host, and 1662 * Write-Back threshold registers of the transmit ring. 1663 * When setting Write-Back threshold to the value greater then zero, 1664 * *tx_rs_thresh* value should be explicitly set to one. 1665 * - The *tx_free_thresh* value indicates the [minimum] number of network 1666 * buffers that must be pending in the transmit ring to trigger their 1667 * [implicit] freeing by the driver transmit function. 1668 * - The *tx_rs_thresh* value indicates the [minimum] number of transmit 1669 * descriptors that must be pending in the transmit ring before setting the 1670 * RS bit on a descriptor by the driver transmit function. 1671 * The *tx_rs_thresh* value should be less or equal then 1672 * *tx_free_thresh* value, and both of them should be less then 1673 * *nb_tx_desc* - 3. 1674 * - The *offloads* member contains Tx offloads to be enabled. 1675 * If an offloading set in tx_conf->offloads 1676 * hasn't been set in the input argument eth_conf->txmode.offloads 1677 * to rte_eth_dev_configure(), it is a new added offloading, it must be 1678 * per-queue type and it is enabled for the queue. 1679 * No need to repeat any bit in tx_conf->offloads which has already been 1680 * enabled in rte_eth_dev_configure() at port level. An offloading enabled 1681 * at port level can't be disabled at queue level. 1682 * 1683 * Note that setting *tx_free_thresh* or *tx_rs_thresh* value to 0 forces 1684 * the transmit function to use default values. 1685 * @return 1686 * - 0: Success, the transmit queue is correctly set up. 1687 * - -ENOMEM: Unable to allocate the transmit ring descriptors. 1688 */ 1689 int rte_eth_tx_queue_setup(uint16_t port_id, uint16_t tx_queue_id, 1690 uint16_t nb_tx_desc, unsigned int socket_id, 1691 const struct rte_eth_txconf *tx_conf); 1692 1693 /** 1694 * Return the NUMA socket to which an Ethernet device is connected 1695 * 1696 * @param port_id 1697 * The port identifier of the Ethernet device 1698 * @return 1699 * The NUMA socket id to which the Ethernet device is connected or 1700 * a default of zero if the socket could not be determined. 1701 * -1 is returned is the port_id value is out of range. 1702 */ 1703 int rte_eth_dev_socket_id(uint16_t port_id); 1704 1705 /** 1706 * Check if port_id of device is attached 1707 * 1708 * @param port_id 1709 * The port identifier of the Ethernet device 1710 * @return 1711 * - 0 if port is out of range or not attached 1712 * - 1 if device is attached 1713 */ 1714 int rte_eth_dev_is_valid_port(uint16_t port_id); 1715 1716 /** 1717 * Start specified RX queue of a port. It is used when rx_deferred_start 1718 * flag of the specified queue is true. 1719 * 1720 * @param port_id 1721 * The port identifier of the Ethernet device 1722 * @param rx_queue_id 1723 * The index of the rx queue to update the ring. 1724 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 1725 * to rte_eth_dev_configure(). 1726 * @return 1727 * - 0: Success, the receive queue is started. 1728 * - -EINVAL: The port_id or the queue_id out of range. 1729 * - -EIO: if device is removed. 1730 * - -ENOTSUP: The function not supported in PMD driver. 1731 */ 1732 int rte_eth_dev_rx_queue_start(uint16_t port_id, uint16_t rx_queue_id); 1733 1734 /** 1735 * Stop specified RX queue of a port 1736 * 1737 * @param port_id 1738 * The port identifier of the Ethernet device 1739 * @param rx_queue_id 1740 * The index of the rx queue to update the ring. 1741 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 1742 * to rte_eth_dev_configure(). 1743 * @return 1744 * - 0: Success, the receive queue is stopped. 1745 * - -EINVAL: The port_id or the queue_id out of range. 1746 * - -EIO: if device is removed. 1747 * - -ENOTSUP: The function not supported in PMD driver. 1748 */ 1749 int rte_eth_dev_rx_queue_stop(uint16_t port_id, uint16_t rx_queue_id); 1750 1751 /** 1752 * Start TX for specified queue of a port. It is used when tx_deferred_start 1753 * flag of the specified queue is true. 1754 * 1755 * @param port_id 1756 * The port identifier of the Ethernet device 1757 * @param tx_queue_id 1758 * The index of the tx queue to update the ring. 1759 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 1760 * to rte_eth_dev_configure(). 1761 * @return 1762 * - 0: Success, the transmit queue is started. 1763 * - -EINVAL: The port_id or the queue_id out of range. 1764 * - -EIO: if device is removed. 1765 * - -ENOTSUP: The function not supported in PMD driver. 1766 */ 1767 int rte_eth_dev_tx_queue_start(uint16_t port_id, uint16_t tx_queue_id); 1768 1769 /** 1770 * Stop specified TX queue of a port 1771 * 1772 * @param port_id 1773 * The port identifier of the Ethernet device 1774 * @param tx_queue_id 1775 * The index of the tx queue to update the ring. 1776 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 1777 * to rte_eth_dev_configure(). 1778 * @return 1779 * - 0: Success, the transmit queue is stopped. 1780 * - -EINVAL: The port_id or the queue_id out of range. 1781 * - -EIO: if device is removed. 1782 * - -ENOTSUP: The function not supported in PMD driver. 1783 */ 1784 int rte_eth_dev_tx_queue_stop(uint16_t port_id, uint16_t tx_queue_id); 1785 1786 /** 1787 * Start an Ethernet device. 1788 * 1789 * The device start step is the last one and consists of setting the configured 1790 * offload features and in starting the transmit and the receive units of the 1791 * device. 1792 * 1793 * Device RTE_ETH_DEV_NOLIVE_MAC_ADDR flag causes MAC address to be set before 1794 * PMD port start callback function is invoked. 1795 * 1796 * On success, all basic functions exported by the Ethernet API (link status, 1797 * receive/transmit, and so on) can be invoked. 1798 * 1799 * @param port_id 1800 * The port identifier of the Ethernet device. 1801 * @return 1802 * - 0: Success, Ethernet device started. 1803 * - <0: Error code of the driver device start function. 1804 */ 1805 int rte_eth_dev_start(uint16_t port_id); 1806 1807 /** 1808 * Stop an Ethernet device. The device can be restarted with a call to 1809 * rte_eth_dev_start() 1810 * 1811 * @param port_id 1812 * The port identifier of the Ethernet device. 1813 */ 1814 void rte_eth_dev_stop(uint16_t port_id); 1815 1816 /** 1817 * Link up an Ethernet device. 1818 * 1819 * Set device link up will re-enable the device rx/tx 1820 * functionality after it is previously set device linked down. 1821 * 1822 * @param port_id 1823 * The port identifier of the Ethernet device. 1824 * @return 1825 * - 0: Success, Ethernet device linked up. 1826 * - <0: Error code of the driver device link up function. 1827 */ 1828 int rte_eth_dev_set_link_up(uint16_t port_id); 1829 1830 /** 1831 * Link down an Ethernet device. 1832 * The device rx/tx functionality will be disabled if success, 1833 * and it can be re-enabled with a call to 1834 * rte_eth_dev_set_link_up() 1835 * 1836 * @param port_id 1837 * The port identifier of the Ethernet device. 1838 */ 1839 int rte_eth_dev_set_link_down(uint16_t port_id); 1840 1841 /** 1842 * Close a stopped Ethernet device. The device cannot be restarted! 1843 * The function frees all port resources if the driver supports 1844 * the flag RTE_ETH_DEV_CLOSE_REMOVE. 1845 * 1846 * @param port_id 1847 * The port identifier of the Ethernet device. 1848 */ 1849 void rte_eth_dev_close(uint16_t port_id); 1850 1851 /** 1852 * Reset a Ethernet device and keep its port id. 1853 * 1854 * When a port has to be reset passively, the DPDK application can invoke 1855 * this function. For example when a PF is reset, all its VFs should also 1856 * be reset. Normally a DPDK application can invoke this function when 1857 * RTE_ETH_EVENT_INTR_RESET event is detected, but can also use it to start 1858 * a port reset in other circumstances. 1859 * 1860 * When this function is called, it first stops the port and then calls the 1861 * PMD specific dev_uninit( ) and dev_init( ) to return the port to initial 1862 * state, in which no Tx and Rx queues are setup, as if the port has been 1863 * reset and not started. The port keeps the port id it had before the 1864 * function call. 1865 * 1866 * After calling rte_eth_dev_reset( ), the application should use 1867 * rte_eth_dev_configure( ), rte_eth_rx_queue_setup( ), 1868 * rte_eth_tx_queue_setup( ), and rte_eth_dev_start( ) 1869 * to reconfigure the device as appropriate. 1870 * 1871 * Note: To avoid unexpected behavior, the application should stop calling 1872 * Tx and Rx functions before calling rte_eth_dev_reset( ). For thread 1873 * safety, all these controlling functions should be called from the same 1874 * thread. 1875 * 1876 * @param port_id 1877 * The port identifier of the Ethernet device. 1878 * 1879 * @return 1880 * - (0) if successful. 1881 * - (-EINVAL) if port identifier is invalid. 1882 * - (-ENOTSUP) if hardware doesn't support this function. 1883 * - (-EPERM) if not ran from the primary process. 1884 * - (-EIO) if re-initialisation failed or device is removed. 1885 * - (-ENOMEM) if the reset failed due to OOM. 1886 * - (-EAGAIN) if the reset temporarily failed and should be retried later. 1887 */ 1888 int rte_eth_dev_reset(uint16_t port_id); 1889 1890 /** 1891 * Enable receipt in promiscuous mode for an Ethernet device. 1892 * 1893 * @param port_id 1894 * The port identifier of the Ethernet device. 1895 */ 1896 void rte_eth_promiscuous_enable(uint16_t port_id); 1897 1898 /** 1899 * Disable receipt in promiscuous mode for an Ethernet device. 1900 * 1901 * @param port_id 1902 * The port identifier of the Ethernet device. 1903 */ 1904 void rte_eth_promiscuous_disable(uint16_t port_id); 1905 1906 /** 1907 * Return the value of promiscuous mode for an Ethernet device. 1908 * 1909 * @param port_id 1910 * The port identifier of the Ethernet device. 1911 * @return 1912 * - (1) if promiscuous is enabled 1913 * - (0) if promiscuous is disabled. 1914 * - (-1) on error 1915 */ 1916 int rte_eth_promiscuous_get(uint16_t port_id); 1917 1918 /** 1919 * Enable the receipt of any multicast frame by an Ethernet device. 1920 * 1921 * @param port_id 1922 * The port identifier of the Ethernet device. 1923 */ 1924 void rte_eth_allmulticast_enable(uint16_t port_id); 1925 1926 /** 1927 * Disable the receipt of all multicast frames by an Ethernet device. 1928 * 1929 * @param port_id 1930 * The port identifier of the Ethernet device. 1931 */ 1932 void rte_eth_allmulticast_disable(uint16_t port_id); 1933 1934 /** 1935 * Return the value of allmulticast mode for an Ethernet device. 1936 * 1937 * @param port_id 1938 * The port identifier of the Ethernet device. 1939 * @return 1940 * - (1) if allmulticast is enabled 1941 * - (0) if allmulticast is disabled. 1942 * - (-1) on error 1943 */ 1944 int rte_eth_allmulticast_get(uint16_t port_id); 1945 1946 /** 1947 * Retrieve the status (ON/OFF), the speed (in Mbps) and the mode (HALF-DUPLEX 1948 * or FULL-DUPLEX) of the physical link of an Ethernet device. It might need 1949 * to wait up to 9 seconds in it. 1950 * 1951 * @param port_id 1952 * The port identifier of the Ethernet device. 1953 * @param link 1954 * A pointer to an *rte_eth_link* structure to be filled with 1955 * the status, the speed and the mode of the Ethernet device link. 1956 */ 1957 void rte_eth_link_get(uint16_t port_id, struct rte_eth_link *link); 1958 1959 /** 1960 * Retrieve the status (ON/OFF), the speed (in Mbps) and the mode (HALF-DUPLEX 1961 * or FULL-DUPLEX) of the physical link of an Ethernet device. It is a no-wait 1962 * version of rte_eth_link_get(). 1963 * 1964 * @param port_id 1965 * The port identifier of the Ethernet device. 1966 * @param link 1967 * A pointer to an *rte_eth_link* structure to be filled with 1968 * the status, the speed and the mode of the Ethernet device link. 1969 */ 1970 void rte_eth_link_get_nowait(uint16_t port_id, struct rte_eth_link *link); 1971 1972 /** 1973 * Retrieve the general I/O statistics of an Ethernet device. 1974 * 1975 * @param port_id 1976 * The port identifier of the Ethernet device. 1977 * @param stats 1978 * A pointer to a structure of type *rte_eth_stats* to be filled with 1979 * the values of device counters for the following set of statistics: 1980 * - *ipackets* with the total of successfully received packets. 1981 * - *opackets* with the total of successfully transmitted packets. 1982 * - *ibytes* with the total of successfully received bytes. 1983 * - *obytes* with the total of successfully transmitted bytes. 1984 * - *ierrors* with the total of erroneous received packets. 1985 * - *oerrors* with the total of failed transmitted packets. 1986 * @return 1987 * Zero if successful. Non-zero otherwise. 1988 */ 1989 int rte_eth_stats_get(uint16_t port_id, struct rte_eth_stats *stats); 1990 1991 /** 1992 * Reset the general I/O statistics of an Ethernet device. 1993 * 1994 * @param port_id 1995 * The port identifier of the Ethernet device. 1996 * @return 1997 * - (0) if device notified to reset stats. 1998 * - (-ENOTSUP) if hardware doesn't support. 1999 * - (-ENODEV) if *port_id* invalid. 2000 */ 2001 int rte_eth_stats_reset(uint16_t port_id); 2002 2003 /** 2004 * Retrieve names of extended statistics of an Ethernet device. 2005 * 2006 * There is an assumption that 'xstat_names' and 'xstats' arrays are matched 2007 * by array index: 2008 * xstats_names[i].name => xstats[i].value 2009 * 2010 * And the array index is same with id field of 'struct rte_eth_xstat': 2011 * xstats[i].id == i 2012 * 2013 * This assumption makes key-value pair matching less flexible but simpler. 2014 * 2015 * @param port_id 2016 * The port identifier of the Ethernet device. 2017 * @param xstats_names 2018 * An rte_eth_xstat_name array of at least *size* elements to 2019 * be filled. If set to NULL, the function returns the required number 2020 * of elements. 2021 * @param size 2022 * The size of the xstats_names array (number of elements). 2023 * @return 2024 * - A positive value lower or equal to size: success. The return value 2025 * is the number of entries filled in the stats table. 2026 * - A positive value higher than size: error, the given statistics table 2027 * is too small. The return value corresponds to the size that should 2028 * be given to succeed. The entries in the table are not valid and 2029 * shall not be used by the caller. 2030 * - A negative value on error (invalid port id). 2031 */ 2032 int rte_eth_xstats_get_names(uint16_t port_id, 2033 struct rte_eth_xstat_name *xstats_names, 2034 unsigned int size); 2035 2036 /** 2037 * Retrieve extended statistics of an Ethernet device. 2038 * 2039 * There is an assumption that 'xstat_names' and 'xstats' arrays are matched 2040 * by array index: 2041 * xstats_names[i].name => xstats[i].value 2042 * 2043 * And the array index is same with id field of 'struct rte_eth_xstat': 2044 * xstats[i].id == i 2045 * 2046 * This assumption makes key-value pair matching less flexible but simpler. 2047 * 2048 * @param port_id 2049 * The port identifier of the Ethernet device. 2050 * @param xstats 2051 * A pointer to a table of structure of type *rte_eth_xstat* 2052 * to be filled with device statistics ids and values. 2053 * This parameter can be set to NULL if n is 0. 2054 * @param n 2055 * The size of the xstats array (number of elements). 2056 * @return 2057 * - A positive value lower or equal to n: success. The return value 2058 * is the number of entries filled in the stats table. 2059 * - A positive value higher than n: error, the given statistics table 2060 * is too small. The return value corresponds to the size that should 2061 * be given to succeed. The entries in the table are not valid and 2062 * shall not be used by the caller. 2063 * - A negative value on error (invalid port id). 2064 */ 2065 int rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats, 2066 unsigned int n); 2067 2068 /** 2069 * Retrieve names of extended statistics of an Ethernet device. 2070 * 2071 * @param port_id 2072 * The port identifier of the Ethernet device. 2073 * @param xstats_names 2074 * An rte_eth_xstat_name array of at least *size* elements to 2075 * be filled. If set to NULL, the function returns the required number 2076 * of elements. 2077 * @param ids 2078 * IDs array given by app to retrieve specific statistics 2079 * @param size 2080 * The size of the xstats_names array (number of elements). 2081 * @return 2082 * - A positive value lower or equal to size: success. The return value 2083 * is the number of entries filled in the stats table. 2084 * - A positive value higher than size: error, the given statistics table 2085 * is too small. The return value corresponds to the size that should 2086 * be given to succeed. The entries in the table are not valid and 2087 * shall not be used by the caller. 2088 * - A negative value on error (invalid port id). 2089 */ 2090 int 2091 rte_eth_xstats_get_names_by_id(uint16_t port_id, 2092 struct rte_eth_xstat_name *xstats_names, unsigned int size, 2093 uint64_t *ids); 2094 2095 /** 2096 * Retrieve extended statistics of an Ethernet device. 2097 * 2098 * @param port_id 2099 * The port identifier of the Ethernet device. 2100 * @param ids 2101 * A pointer to an ids array passed by application. This tells which 2102 * statistics values function should retrieve. This parameter 2103 * can be set to NULL if size is 0. In this case function will retrieve 2104 * all available statistics. 2105 * @param values 2106 * A pointer to a table to be filled with device statistics values. 2107 * @param size 2108 * The size of the ids array (number of elements). 2109 * @return 2110 * - A positive value lower or equal to size: success. The return value 2111 * is the number of entries filled in the stats table. 2112 * - A positive value higher than size: error, the given statistics table 2113 * is too small. The return value corresponds to the size that should 2114 * be given to succeed. The entries in the table are not valid and 2115 * shall not be used by the caller. 2116 * - A negative value on error (invalid port id). 2117 */ 2118 int rte_eth_xstats_get_by_id(uint16_t port_id, const uint64_t *ids, 2119 uint64_t *values, unsigned int size); 2120 2121 /** 2122 * Gets the ID of a statistic from its name. 2123 * 2124 * This function searches for the statistics using string compares, and 2125 * as such should not be used on the fast-path. For fast-path retrieval of 2126 * specific statistics, store the ID as provided in *id* from this function, 2127 * and pass the ID to rte_eth_xstats_get() 2128 * 2129 * @param port_id The port to look up statistics from 2130 * @param xstat_name The name of the statistic to return 2131 * @param[out] id A pointer to an app-supplied uint64_t which should be 2132 * set to the ID of the stat if the stat exists. 2133 * @return 2134 * 0 on success 2135 * -ENODEV for invalid port_id, 2136 * -EIO if device is removed, 2137 * -EINVAL if the xstat_name doesn't exist in port_id 2138 */ 2139 int rte_eth_xstats_get_id_by_name(uint16_t port_id, const char *xstat_name, 2140 uint64_t *id); 2141 2142 /** 2143 * Reset extended statistics of an Ethernet device. 2144 * 2145 * @param port_id 2146 * The port identifier of the Ethernet device. 2147 */ 2148 void rte_eth_xstats_reset(uint16_t port_id); 2149 2150 /** 2151 * Set a mapping for the specified transmit queue to the specified per-queue 2152 * statistics counter. 2153 * 2154 * @param port_id 2155 * The port identifier of the Ethernet device. 2156 * @param tx_queue_id 2157 * The index of the transmit queue for which a queue stats mapping is required. 2158 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 2159 * to rte_eth_dev_configure(). 2160 * @param stat_idx 2161 * The per-queue packet statistics functionality number that the transmit 2162 * queue is to be assigned. 2163 * The value must be in the range [0, RTE_ETHDEV_QUEUE_STAT_CNTRS - 1]. 2164 * @return 2165 * Zero if successful. Non-zero otherwise. 2166 */ 2167 int rte_eth_dev_set_tx_queue_stats_mapping(uint16_t port_id, 2168 uint16_t tx_queue_id, uint8_t stat_idx); 2169 2170 /** 2171 * Set a mapping for the specified receive queue to the specified per-queue 2172 * statistics counter. 2173 * 2174 * @param port_id 2175 * The port identifier of the Ethernet device. 2176 * @param rx_queue_id 2177 * The index of the receive queue for which a queue stats mapping is required. 2178 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 2179 * to rte_eth_dev_configure(). 2180 * @param stat_idx 2181 * The per-queue packet statistics functionality number that the receive 2182 * queue is to be assigned. 2183 * The value must be in the range [0, RTE_ETHDEV_QUEUE_STAT_CNTRS - 1]. 2184 * @return 2185 * Zero if successful. Non-zero otherwise. 2186 */ 2187 int rte_eth_dev_set_rx_queue_stats_mapping(uint16_t port_id, 2188 uint16_t rx_queue_id, 2189 uint8_t stat_idx); 2190 2191 /** 2192 * Retrieve the Ethernet address of an Ethernet device. 2193 * 2194 * @param port_id 2195 * The port identifier of the Ethernet device. 2196 * @param mac_addr 2197 * A pointer to a structure of type *ether_addr* to be filled with 2198 * the Ethernet address of the Ethernet device. 2199 */ 2200 void rte_eth_macaddr_get(uint16_t port_id, struct ether_addr *mac_addr); 2201 2202 /** 2203 * Retrieve the contextual information of an Ethernet device. 2204 * 2205 * @param port_id 2206 * The port identifier of the Ethernet device. 2207 * @param dev_info 2208 * A pointer to a structure of type *rte_eth_dev_info* to be filled with 2209 * the contextual information of the Ethernet device. 2210 */ 2211 void rte_eth_dev_info_get(uint16_t port_id, struct rte_eth_dev_info *dev_info); 2212 2213 /** 2214 * Retrieve the firmware version of a device. 2215 * 2216 * @param port_id 2217 * The port identifier of the device. 2218 * @param fw_version 2219 * A pointer to a string array storing the firmware version of a device, 2220 * the string includes terminating null. This pointer is allocated by caller. 2221 * @param fw_size 2222 * The size of the string array pointed by fw_version, which should be 2223 * large enough to store firmware version of the device. 2224 * @return 2225 * - (0) if successful. 2226 * - (-ENOTSUP) if operation is not supported. 2227 * - (-ENODEV) if *port_id* invalid. 2228 * - (-EIO) if device is removed. 2229 * - (>0) if *fw_size* is not enough to store firmware version, return 2230 * the size of the non truncated string. 2231 */ 2232 int rte_eth_dev_fw_version_get(uint16_t port_id, 2233 char *fw_version, size_t fw_size); 2234 2235 /** 2236 * Retrieve the supported packet types of an Ethernet device. 2237 * 2238 * When a packet type is announced as supported, it *must* be recognized by 2239 * the PMD. For instance, if RTE_PTYPE_L2_ETHER, RTE_PTYPE_L2_ETHER_VLAN 2240 * and RTE_PTYPE_L3_IPV4 are announced, the PMD must return the following 2241 * packet types for these packets: 2242 * - Ether/IPv4 -> RTE_PTYPE_L2_ETHER | RTE_PTYPE_L3_IPV4 2243 * - Ether/Vlan/IPv4 -> RTE_PTYPE_L2_ETHER_VLAN | RTE_PTYPE_L3_IPV4 2244 * - Ether/[anything else] -> RTE_PTYPE_L2_ETHER 2245 * - Ether/Vlan/[anything else] -> RTE_PTYPE_L2_ETHER_VLAN 2246 * 2247 * When a packet is received by a PMD, the most precise type must be 2248 * returned among the ones supported. However a PMD is allowed to set 2249 * packet type that is not in the supported list, at the condition that it 2250 * is more precise. Therefore, a PMD announcing no supported packet types 2251 * can still set a matching packet type in a received packet. 2252 * 2253 * @note 2254 * Better to invoke this API after the device is already started or rx burst 2255 * function is decided, to obtain correct supported ptypes. 2256 * @note 2257 * if a given PMD does not report what ptypes it supports, then the supported 2258 * ptype count is reported as 0. 2259 * @param port_id 2260 * The port identifier of the Ethernet device. 2261 * @param ptype_mask 2262 * A hint of what kind of packet type which the caller is interested in. 2263 * @param ptypes 2264 * An array pointer to store adequate packet types, allocated by caller. 2265 * @param num 2266 * Size of the array pointed by param ptypes. 2267 * @return 2268 * - (>=0) Number of supported ptypes. If the number of types exceeds num, 2269 * only num entries will be filled into the ptypes array, but the full 2270 * count of supported ptypes will be returned. 2271 * - (-ENODEV) if *port_id* invalid. 2272 */ 2273 int rte_eth_dev_get_supported_ptypes(uint16_t port_id, uint32_t ptype_mask, 2274 uint32_t *ptypes, int num); 2275 2276 /** 2277 * Retrieve the MTU of an Ethernet device. 2278 * 2279 * @param port_id 2280 * The port identifier of the Ethernet device. 2281 * @param mtu 2282 * A pointer to a uint16_t where the retrieved MTU is to be stored. 2283 * @return 2284 * - (0) if successful. 2285 * - (-ENODEV) if *port_id* invalid. 2286 */ 2287 int rte_eth_dev_get_mtu(uint16_t port_id, uint16_t *mtu); 2288 2289 /** 2290 * Change the MTU of an Ethernet device. 2291 * 2292 * @param port_id 2293 * The port identifier of the Ethernet device. 2294 * @param mtu 2295 * A uint16_t for the MTU to be applied. 2296 * @return 2297 * - (0) if successful. 2298 * - (-ENOTSUP) if operation is not supported. 2299 * - (-ENODEV) if *port_id* invalid. 2300 * - (-EIO) if device is removed. 2301 * - (-EINVAL) if *mtu* invalid. 2302 * - (-EBUSY) if operation is not allowed when the port is running 2303 */ 2304 int rte_eth_dev_set_mtu(uint16_t port_id, uint16_t mtu); 2305 2306 /** 2307 * Enable/Disable hardware filtering by an Ethernet device of received 2308 * VLAN packets tagged with a given VLAN Tag Identifier. 2309 * 2310 * @param port_id 2311 * The port identifier of the Ethernet device. 2312 * @param vlan_id 2313 * The VLAN Tag Identifier whose filtering must be enabled or disabled. 2314 * @param on 2315 * If > 0, enable VLAN filtering of VLAN packets tagged with *vlan_id*. 2316 * Otherwise, disable VLAN filtering of VLAN packets tagged with *vlan_id*. 2317 * @return 2318 * - (0) if successful. 2319 * - (-ENOSUP) if hardware-assisted VLAN filtering not configured. 2320 * - (-ENODEV) if *port_id* invalid. 2321 * - (-EIO) if device is removed. 2322 * - (-ENOSYS) if VLAN filtering on *port_id* disabled. 2323 * - (-EINVAL) if *vlan_id* > 4095. 2324 */ 2325 int rte_eth_dev_vlan_filter(uint16_t port_id, uint16_t vlan_id, int on); 2326 2327 /** 2328 * Enable/Disable hardware VLAN Strip by a rx queue of an Ethernet device. 2329 * 82599/X540/X550 can support VLAN stripping at the rx queue level 2330 * 2331 * @param port_id 2332 * The port identifier of the Ethernet device. 2333 * @param rx_queue_id 2334 * The index of the receive queue for which a queue stats mapping is required. 2335 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 2336 * to rte_eth_dev_configure(). 2337 * @param on 2338 * If 1, Enable VLAN Stripping of the receive queue of the Ethernet port. 2339 * If 0, Disable VLAN Stripping of the receive queue of the Ethernet port. 2340 * @return 2341 * - (0) if successful. 2342 * - (-ENOSUP) if hardware-assisted VLAN stripping not configured. 2343 * - (-ENODEV) if *port_id* invalid. 2344 * - (-EINVAL) if *rx_queue_id* invalid. 2345 */ 2346 int rte_eth_dev_set_vlan_strip_on_queue(uint16_t port_id, uint16_t rx_queue_id, 2347 int on); 2348 2349 /** 2350 * Set the Outer VLAN Ether Type by an Ethernet device, it can be inserted to 2351 * the VLAN Header. This is a register setup available on some Intel NIC, not 2352 * but all, please check the data sheet for availability. 2353 * 2354 * @param port_id 2355 * The port identifier of the Ethernet device. 2356 * @param vlan_type 2357 * The vlan type. 2358 * @param tag_type 2359 * The Tag Protocol ID 2360 * @return 2361 * - (0) if successful. 2362 * - (-ENOSUP) if hardware-assisted VLAN TPID setup is not supported. 2363 * - (-ENODEV) if *port_id* invalid. 2364 * - (-EIO) if device is removed. 2365 */ 2366 int rte_eth_dev_set_vlan_ether_type(uint16_t port_id, 2367 enum rte_vlan_type vlan_type, 2368 uint16_t tag_type); 2369 2370 /** 2371 * Set VLAN offload configuration on an Ethernet device 2372 * Enable/Disable Extended VLAN by an Ethernet device, This is a register setup 2373 * available on some Intel NIC, not but all, please check the data sheet for 2374 * availability. 2375 * Enable/Disable VLAN Strip can be done on rx queue for certain NIC, but here 2376 * the configuration is applied on the port level. 2377 * 2378 * @param port_id 2379 * The port identifier of the Ethernet device. 2380 * @param offload_mask 2381 * The VLAN Offload bit mask can be mixed use with "OR" 2382 * ETH_VLAN_STRIP_OFFLOAD 2383 * ETH_VLAN_FILTER_OFFLOAD 2384 * ETH_VLAN_EXTEND_OFFLOAD 2385 * @return 2386 * - (0) if successful. 2387 * - (-ENOSUP) if hardware-assisted VLAN filtering not configured. 2388 * - (-ENODEV) if *port_id* invalid. 2389 * - (-EIO) if device is removed. 2390 */ 2391 int rte_eth_dev_set_vlan_offload(uint16_t port_id, int offload_mask); 2392 2393 /** 2394 * Read VLAN Offload configuration from an Ethernet device 2395 * 2396 * @param port_id 2397 * The port identifier of the Ethernet device. 2398 * @return 2399 * - (>0) if successful. Bit mask to indicate 2400 * ETH_VLAN_STRIP_OFFLOAD 2401 * ETH_VLAN_FILTER_OFFLOAD 2402 * ETH_VLAN_EXTEND_OFFLOAD 2403 * - (-ENODEV) if *port_id* invalid. 2404 */ 2405 int rte_eth_dev_get_vlan_offload(uint16_t port_id); 2406 2407 /** 2408 * Set port based TX VLAN insertion on or off. 2409 * 2410 * @param port_id 2411 * The port identifier of the Ethernet device. 2412 * @param pvid 2413 * Port based TX VLAN identifier together with user priority. 2414 * @param on 2415 * Turn on or off the port based TX VLAN insertion. 2416 * 2417 * @return 2418 * - (0) if successful. 2419 * - negative if failed. 2420 */ 2421 int rte_eth_dev_set_vlan_pvid(uint16_t port_id, uint16_t pvid, int on); 2422 2423 typedef void (*buffer_tx_error_fn)(struct rte_mbuf **unsent, uint16_t count, 2424 void *userdata); 2425 2426 /** 2427 * Structure used to buffer packets for future TX 2428 * Used by APIs rte_eth_tx_buffer and rte_eth_tx_buffer_flush 2429 */ 2430 struct rte_eth_dev_tx_buffer { 2431 buffer_tx_error_fn error_callback; 2432 void *error_userdata; 2433 uint16_t size; /**< Size of buffer for buffered tx */ 2434 uint16_t length; /**< Number of packets in the array */ 2435 struct rte_mbuf *pkts[]; 2436 /**< Pending packets to be sent on explicit flush or when full */ 2437 }; 2438 2439 /** 2440 * Calculate the size of the tx buffer. 2441 * 2442 * @param sz 2443 * Number of stored packets. 2444 */ 2445 #define RTE_ETH_TX_BUFFER_SIZE(sz) \ 2446 (sizeof(struct rte_eth_dev_tx_buffer) + (sz) * sizeof(struct rte_mbuf *)) 2447 2448 /** 2449 * Initialize default values for buffered transmitting 2450 * 2451 * @param buffer 2452 * Tx buffer to be initialized. 2453 * @param size 2454 * Buffer size 2455 * @return 2456 * 0 if no error 2457 */ 2458 int 2459 rte_eth_tx_buffer_init(struct rte_eth_dev_tx_buffer *buffer, uint16_t size); 2460 2461 /** 2462 * Configure a callback for buffered packets which cannot be sent 2463 * 2464 * Register a specific callback to be called when an attempt is made to send 2465 * all packets buffered on an ethernet port, but not all packets can 2466 * successfully be sent. The callback registered here will be called only 2467 * from calls to rte_eth_tx_buffer() and rte_eth_tx_buffer_flush() APIs. 2468 * The default callback configured for each queue by default just frees the 2469 * packets back to the calling mempool. If additional behaviour is required, 2470 * for example, to count dropped packets, or to retry transmission of packets 2471 * which cannot be sent, this function should be used to register a suitable 2472 * callback function to implement the desired behaviour. 2473 * The example callback "rte_eth_count_unsent_packet_callback()" is also 2474 * provided as reference. 2475 * 2476 * @param buffer 2477 * The port identifier of the Ethernet device. 2478 * @param callback 2479 * The function to be used as the callback. 2480 * @param userdata 2481 * Arbitrary parameter to be passed to the callback function 2482 * @return 2483 * 0 on success, or -1 on error with rte_errno set appropriately 2484 */ 2485 int 2486 rte_eth_tx_buffer_set_err_callback(struct rte_eth_dev_tx_buffer *buffer, 2487 buffer_tx_error_fn callback, void *userdata); 2488 2489 /** 2490 * Callback function for silently dropping unsent buffered packets. 2491 * 2492 * This function can be passed to rte_eth_tx_buffer_set_err_callback() to 2493 * adjust the default behavior when buffered packets cannot be sent. This 2494 * function drops any unsent packets silently and is used by tx buffered 2495 * operations as default behavior. 2496 * 2497 * NOTE: this function should not be called directly, instead it should be used 2498 * as a callback for packet buffering. 2499 * 2500 * NOTE: when configuring this function as a callback with 2501 * rte_eth_tx_buffer_set_err_callback(), the final, userdata parameter 2502 * should point to an uint64_t value. 2503 * 2504 * @param pkts 2505 * The previously buffered packets which could not be sent 2506 * @param unsent 2507 * The number of unsent packets in the pkts array 2508 * @param userdata 2509 * Not used 2510 */ 2511 void 2512 rte_eth_tx_buffer_drop_callback(struct rte_mbuf **pkts, uint16_t unsent, 2513 void *userdata); 2514 2515 /** 2516 * Callback function for tracking unsent buffered packets. 2517 * 2518 * This function can be passed to rte_eth_tx_buffer_set_err_callback() to 2519 * adjust the default behavior when buffered packets cannot be sent. This 2520 * function drops any unsent packets, but also updates a user-supplied counter 2521 * to track the overall number of packets dropped. The counter should be an 2522 * uint64_t variable. 2523 * 2524 * NOTE: this function should not be called directly, instead it should be used 2525 * as a callback for packet buffering. 2526 * 2527 * NOTE: when configuring this function as a callback with 2528 * rte_eth_tx_buffer_set_err_callback(), the final, userdata parameter 2529 * should point to an uint64_t value. 2530 * 2531 * @param pkts 2532 * The previously buffered packets which could not be sent 2533 * @param unsent 2534 * The number of unsent packets in the pkts array 2535 * @param userdata 2536 * Pointer to an uint64_t value, which will be incremented by unsent 2537 */ 2538 void 2539 rte_eth_tx_buffer_count_callback(struct rte_mbuf **pkts, uint16_t unsent, 2540 void *userdata); 2541 2542 /** 2543 * Request the driver to free mbufs currently cached by the driver. The 2544 * driver will only free the mbuf if it is no longer in use. It is the 2545 * application's responsibility to ensure rte_eth_tx_buffer_flush(..) is 2546 * called if needed. 2547 * 2548 * @param port_id 2549 * The port identifier of the Ethernet device. 2550 * @param queue_id 2551 * The index of the transmit queue through which output packets must be 2552 * sent. 2553 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 2554 * to rte_eth_dev_configure(). 2555 * @param free_cnt 2556 * Maximum number of packets to free. Use 0 to indicate all possible packets 2557 * should be freed. Note that a packet may be using multiple mbufs. 2558 * @return 2559 * Failure: < 0 2560 * -ENODEV: Invalid interface 2561 * -EIO: device is removed 2562 * -ENOTSUP: Driver does not support function 2563 * Success: >= 0 2564 * 0-n: Number of packets freed. More packets may still remain in ring that 2565 * are in use. 2566 */ 2567 int 2568 rte_eth_tx_done_cleanup(uint16_t port_id, uint16_t queue_id, uint32_t free_cnt); 2569 2570 /** 2571 * Subtypes for IPsec offload event(@ref RTE_ETH_EVENT_IPSEC) raised by 2572 * eth device. 2573 */ 2574 enum rte_eth_event_ipsec_subtype { 2575 RTE_ETH_EVENT_IPSEC_UNKNOWN = 0, 2576 /**< Unknown event type */ 2577 RTE_ETH_EVENT_IPSEC_ESN_OVERFLOW, 2578 /**< Sequence number overflow */ 2579 RTE_ETH_EVENT_IPSEC_SA_TIME_EXPIRY, 2580 /**< Soft time expiry of SA */ 2581 RTE_ETH_EVENT_IPSEC_SA_BYTE_EXPIRY, 2582 /**< Soft byte expiry of SA */ 2583 RTE_ETH_EVENT_IPSEC_MAX 2584 /**< Max value of this enum */ 2585 }; 2586 2587 /** 2588 * Descriptor for @ref RTE_ETH_EVENT_IPSEC event. Used by eth dev to send extra 2589 * information of the IPsec offload event. 2590 */ 2591 struct rte_eth_event_ipsec_desc { 2592 enum rte_eth_event_ipsec_subtype subtype; 2593 /**< Type of RTE_ETH_EVENT_IPSEC_* event */ 2594 uint64_t metadata; 2595 /**< Event specific metadata 2596 * 2597 * For the following events, *userdata* registered 2598 * with the *rte_security_session* would be returned 2599 * as metadata, 2600 * 2601 * - @ref RTE_ETH_EVENT_IPSEC_ESN_OVERFLOW 2602 * - @ref RTE_ETH_EVENT_IPSEC_SA_TIME_EXPIRY 2603 * - @ref RTE_ETH_EVENT_IPSEC_SA_BYTE_EXPIRY 2604 * 2605 * @see struct rte_security_session_conf 2606 * 2607 */ 2608 }; 2609 2610 /** 2611 * The eth device event type for interrupt, and maybe others in the future. 2612 */ 2613 enum rte_eth_event_type { 2614 RTE_ETH_EVENT_UNKNOWN, /**< unknown event type */ 2615 RTE_ETH_EVENT_INTR_LSC, /**< lsc interrupt event */ 2616 RTE_ETH_EVENT_QUEUE_STATE, 2617 /**< queue state event (enabled/disabled) */ 2618 RTE_ETH_EVENT_INTR_RESET, 2619 /**< reset interrupt event, sent to VF on PF reset */ 2620 RTE_ETH_EVENT_VF_MBOX, /**< message from the VF received by PF */ 2621 RTE_ETH_EVENT_MACSEC, /**< MACsec offload related event */ 2622 RTE_ETH_EVENT_INTR_RMV, /**< device removal event */ 2623 RTE_ETH_EVENT_NEW, /**< port is probed */ 2624 RTE_ETH_EVENT_DESTROY, /**< port is released */ 2625 RTE_ETH_EVENT_IPSEC, /**< IPsec offload related event */ 2626 RTE_ETH_EVENT_MAX /**< max value of this enum */ 2627 }; 2628 2629 typedef int (*rte_eth_dev_cb_fn)(uint16_t port_id, 2630 enum rte_eth_event_type event, void *cb_arg, void *ret_param); 2631 /**< user application callback to be registered for interrupts */ 2632 2633 /** 2634 * Register a callback function for port event. 2635 * 2636 * @param port_id 2637 * Port id. 2638 * RTE_ETH_ALL means register the event for all port ids. 2639 * @param event 2640 * Event interested. 2641 * @param cb_fn 2642 * User supplied callback function to be called. 2643 * @param cb_arg 2644 * Pointer to the parameters for the registered callback. 2645 * 2646 * @return 2647 * - On success, zero. 2648 * - On failure, a negative value. 2649 */ 2650 int rte_eth_dev_callback_register(uint16_t port_id, 2651 enum rte_eth_event_type event, 2652 rte_eth_dev_cb_fn cb_fn, void *cb_arg); 2653 2654 /** 2655 * Unregister a callback function for port event. 2656 * 2657 * @param port_id 2658 * Port id. 2659 * RTE_ETH_ALL means unregister the event for all port ids. 2660 * @param event 2661 * Event interested. 2662 * @param cb_fn 2663 * User supplied callback function to be called. 2664 * @param cb_arg 2665 * Pointer to the parameters for the registered callback. -1 means to 2666 * remove all for the same callback address and same event. 2667 * 2668 * @return 2669 * - On success, zero. 2670 * - On failure, a negative value. 2671 */ 2672 int rte_eth_dev_callback_unregister(uint16_t port_id, 2673 enum rte_eth_event_type event, 2674 rte_eth_dev_cb_fn cb_fn, void *cb_arg); 2675 2676 /** 2677 * When there is no rx packet coming in Rx Queue for a long time, we can 2678 * sleep lcore related to RX Queue for power saving, and enable rx interrupt 2679 * to be triggered when Rx packet arrives. 2680 * 2681 * The rte_eth_dev_rx_intr_enable() function enables rx queue 2682 * interrupt on specific rx queue of a port. 2683 * 2684 * @param port_id 2685 * The port identifier of the Ethernet device. 2686 * @param queue_id 2687 * The index of the receive queue from which to retrieve input packets. 2688 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 2689 * to rte_eth_dev_configure(). 2690 * @return 2691 * - (0) if successful. 2692 * - (-ENOTSUP) if underlying hardware OR driver doesn't support 2693 * that operation. 2694 * - (-ENODEV) if *port_id* invalid. 2695 * - (-EIO) if device is removed. 2696 */ 2697 int rte_eth_dev_rx_intr_enable(uint16_t port_id, uint16_t queue_id); 2698 2699 /** 2700 * When lcore wakes up from rx interrupt indicating packet coming, disable rx 2701 * interrupt and returns to polling mode. 2702 * 2703 * The rte_eth_dev_rx_intr_disable() function disables rx queue 2704 * interrupt on specific rx queue of a port. 2705 * 2706 * @param port_id 2707 * The port identifier of the Ethernet device. 2708 * @param queue_id 2709 * The index of the receive queue from which to retrieve input packets. 2710 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 2711 * to rte_eth_dev_configure(). 2712 * @return 2713 * - (0) if successful. 2714 * - (-ENOTSUP) if underlying hardware OR driver doesn't support 2715 * that operation. 2716 * - (-ENODEV) if *port_id* invalid. 2717 * - (-EIO) if device is removed. 2718 */ 2719 int rte_eth_dev_rx_intr_disable(uint16_t port_id, uint16_t queue_id); 2720 2721 /** 2722 * RX Interrupt control per port. 2723 * 2724 * @param port_id 2725 * The port identifier of the Ethernet device. 2726 * @param epfd 2727 * Epoll instance fd which the intr vector associated to. 2728 * Using RTE_EPOLL_PER_THREAD allows to use per thread epoll instance. 2729 * @param op 2730 * The operation be performed for the vector. 2731 * Operation type of {RTE_INTR_EVENT_ADD, RTE_INTR_EVENT_DEL}. 2732 * @param data 2733 * User raw data. 2734 * @return 2735 * - On success, zero. 2736 * - On failure, a negative value. 2737 */ 2738 int rte_eth_dev_rx_intr_ctl(uint16_t port_id, int epfd, int op, void *data); 2739 2740 /** 2741 * RX Interrupt control per queue. 2742 * 2743 * @param port_id 2744 * The port identifier of the Ethernet device. 2745 * @param queue_id 2746 * The index of the receive queue from which to retrieve input packets. 2747 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 2748 * to rte_eth_dev_configure(). 2749 * @param epfd 2750 * Epoll instance fd which the intr vector associated to. 2751 * Using RTE_EPOLL_PER_THREAD allows to use per thread epoll instance. 2752 * @param op 2753 * The operation be performed for the vector. 2754 * Operation type of {RTE_INTR_EVENT_ADD, RTE_INTR_EVENT_DEL}. 2755 * @param data 2756 * User raw data. 2757 * @return 2758 * - On success, zero. 2759 * - On failure, a negative value. 2760 */ 2761 int rte_eth_dev_rx_intr_ctl_q(uint16_t port_id, uint16_t queue_id, 2762 int epfd, int op, void *data); 2763 2764 /** 2765 * @warning 2766 * @b EXPERIMENTAL: this API may change without prior notice. 2767 * 2768 * Get interrupt fd per Rx queue. 2769 * 2770 * @param port_id 2771 * The port identifier of the Ethernet device. 2772 * @param queue_id 2773 * The index of the receive queue from which to retrieve input packets. 2774 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 2775 * to rte_eth_dev_configure(). 2776 * @return 2777 * - (>=0) the interrupt fd associated to the requested Rx queue if 2778 * successful. 2779 * - (-1) on error. 2780 */ 2781 int __rte_experimental 2782 rte_eth_dev_rx_intr_ctl_q_get_fd(uint16_t port_id, uint16_t queue_id); 2783 2784 /** 2785 * Turn on the LED on the Ethernet device. 2786 * This function turns on the LED on the Ethernet device. 2787 * 2788 * @param port_id 2789 * The port identifier of the Ethernet device. 2790 * @return 2791 * - (0) if successful. 2792 * - (-ENOTSUP) if underlying hardware OR driver doesn't support 2793 * that operation. 2794 * - (-ENODEV) if *port_id* invalid. 2795 * - (-EIO) if device is removed. 2796 */ 2797 int rte_eth_led_on(uint16_t port_id); 2798 2799 /** 2800 * Turn off the LED on the Ethernet device. 2801 * This function turns off the LED on the Ethernet device. 2802 * 2803 * @param port_id 2804 * The port identifier of the Ethernet device. 2805 * @return 2806 * - (0) if successful. 2807 * - (-ENOTSUP) if underlying hardware OR driver doesn't support 2808 * that operation. 2809 * - (-ENODEV) if *port_id* invalid. 2810 * - (-EIO) if device is removed. 2811 */ 2812 int rte_eth_led_off(uint16_t port_id); 2813 2814 /** 2815 * Get current status of the Ethernet link flow control for Ethernet device 2816 * 2817 * @param port_id 2818 * The port identifier of the Ethernet device. 2819 * @param fc_conf 2820 * The pointer to the structure where to store the flow control parameters. 2821 * @return 2822 * - (0) if successful. 2823 * - (-ENOTSUP) if hardware doesn't support flow control. 2824 * - (-ENODEV) if *port_id* invalid. 2825 * - (-EIO) if device is removed. 2826 */ 2827 int rte_eth_dev_flow_ctrl_get(uint16_t port_id, 2828 struct rte_eth_fc_conf *fc_conf); 2829 2830 /** 2831 * Configure the Ethernet link flow control for Ethernet device 2832 * 2833 * @param port_id 2834 * The port identifier of the Ethernet device. 2835 * @param fc_conf 2836 * The pointer to the structure of the flow control parameters. 2837 * @return 2838 * - (0) if successful. 2839 * - (-ENOTSUP) if hardware doesn't support flow control mode. 2840 * - (-ENODEV) if *port_id* invalid. 2841 * - (-EINVAL) if bad parameter 2842 * - (-EIO) if flow control setup failure or device is removed. 2843 */ 2844 int rte_eth_dev_flow_ctrl_set(uint16_t port_id, 2845 struct rte_eth_fc_conf *fc_conf); 2846 2847 /** 2848 * Configure the Ethernet priority flow control under DCB environment 2849 * for Ethernet device. 2850 * 2851 * @param port_id 2852 * The port identifier of the Ethernet device. 2853 * @param pfc_conf 2854 * The pointer to the structure of the priority flow control parameters. 2855 * @return 2856 * - (0) if successful. 2857 * - (-ENOTSUP) if hardware doesn't support priority flow control mode. 2858 * - (-ENODEV) if *port_id* invalid. 2859 * - (-EINVAL) if bad parameter 2860 * - (-EIO) if flow control setup failure or device is removed. 2861 */ 2862 int rte_eth_dev_priority_flow_ctrl_set(uint16_t port_id, 2863 struct rte_eth_pfc_conf *pfc_conf); 2864 2865 /** 2866 * Add a MAC address to an internal array of addresses used to enable whitelist 2867 * filtering to accept packets only if the destination MAC address matches. 2868 * 2869 * @param port_id 2870 * The port identifier of the Ethernet device. 2871 * @param mac_addr 2872 * The MAC address to add. 2873 * @param pool 2874 * VMDq pool index to associate address with (if VMDq is enabled). If VMDq is 2875 * not enabled, this should be set to 0. 2876 * @return 2877 * - (0) if successfully added or *mac_addr* was already added. 2878 * - (-ENOTSUP) if hardware doesn't support this feature. 2879 * - (-ENODEV) if *port* is invalid. 2880 * - (-EIO) if device is removed. 2881 * - (-ENOSPC) if no more MAC addresses can be added. 2882 * - (-EINVAL) if MAC address is invalid. 2883 */ 2884 int rte_eth_dev_mac_addr_add(uint16_t port_id, struct ether_addr *mac_addr, 2885 uint32_t pool); 2886 2887 /** 2888 * Remove a MAC address from the internal array of addresses. 2889 * 2890 * @param port_id 2891 * The port identifier of the Ethernet device. 2892 * @param mac_addr 2893 * MAC address to remove. 2894 * @return 2895 * - (0) if successful, or *mac_addr* didn't exist. 2896 * - (-ENOTSUP) if hardware doesn't support. 2897 * - (-ENODEV) if *port* invalid. 2898 * - (-EADDRINUSE) if attempting to remove the default MAC address 2899 */ 2900 int rte_eth_dev_mac_addr_remove(uint16_t port_id, struct ether_addr *mac_addr); 2901 2902 /** 2903 * Set the default MAC address. 2904 * 2905 * @param port_id 2906 * The port identifier of the Ethernet device. 2907 * @param mac_addr 2908 * New default MAC address. 2909 * @return 2910 * - (0) if successful, or *mac_addr* didn't exist. 2911 * - (-ENOTSUP) if hardware doesn't support. 2912 * - (-ENODEV) if *port* invalid. 2913 * - (-EINVAL) if MAC address is invalid. 2914 */ 2915 int rte_eth_dev_default_mac_addr_set(uint16_t port_id, 2916 struct ether_addr *mac_addr); 2917 2918 /** 2919 * Update Redirection Table(RETA) of Receive Side Scaling of Ethernet device. 2920 * 2921 * @param port_id 2922 * The port identifier of the Ethernet device. 2923 * @param reta_conf 2924 * RETA to update. 2925 * @param reta_size 2926 * Redirection table size. The table size can be queried by 2927 * rte_eth_dev_info_get(). 2928 * @return 2929 * - (0) if successful. 2930 * - (-ENOTSUP) if hardware doesn't support. 2931 * - (-EINVAL) if bad parameter. 2932 * - (-EIO) if device is removed. 2933 */ 2934 int rte_eth_dev_rss_reta_update(uint16_t port_id, 2935 struct rte_eth_rss_reta_entry64 *reta_conf, 2936 uint16_t reta_size); 2937 2938 /** 2939 * Query Redirection Table(RETA) of Receive Side Scaling of Ethernet device. 2940 * 2941 * @param port_id 2942 * The port identifier of the Ethernet device. 2943 * @param reta_conf 2944 * RETA to query. 2945 * @param reta_size 2946 * Redirection table size. The table size can be queried by 2947 * rte_eth_dev_info_get(). 2948 * @return 2949 * - (0) if successful. 2950 * - (-ENOTSUP) if hardware doesn't support. 2951 * - (-EINVAL) if bad parameter. 2952 * - (-EIO) if device is removed. 2953 */ 2954 int rte_eth_dev_rss_reta_query(uint16_t port_id, 2955 struct rte_eth_rss_reta_entry64 *reta_conf, 2956 uint16_t reta_size); 2957 2958 /** 2959 * Updates unicast hash table for receiving packet with the given destination 2960 * MAC address, and the packet is routed to all VFs for which the RX mode is 2961 * accept packets that match the unicast hash table. 2962 * 2963 * @param port_id 2964 * The port identifier of the Ethernet device. 2965 * @param addr 2966 * Unicast MAC address. 2967 * @param on 2968 * 1 - Set an unicast hash bit for receiving packets with the MAC address. 2969 * 0 - Clear an unicast hash bit. 2970 * @return 2971 * - (0) if successful. 2972 * - (-ENOTSUP) if hardware doesn't support. 2973 * - (-ENODEV) if *port_id* invalid. 2974 * - (-EIO) if device is removed. 2975 * - (-EINVAL) if bad parameter. 2976 */ 2977 int rte_eth_dev_uc_hash_table_set(uint16_t port_id, struct ether_addr *addr, 2978 uint8_t on); 2979 2980 /** 2981 * Updates all unicast hash bitmaps for receiving packet with any Unicast 2982 * Ethernet MAC addresses,the packet is routed to all VFs for which the RX 2983 * mode is accept packets that match the unicast hash table. 2984 * 2985 * @param port_id 2986 * The port identifier of the Ethernet device. 2987 * @param on 2988 * 1 - Set all unicast hash bitmaps for receiving all the Ethernet 2989 * MAC addresses 2990 * 0 - Clear all unicast hash bitmaps 2991 * @return 2992 * - (0) if successful. 2993 * - (-ENOTSUP) if hardware doesn't support. 2994 * - (-ENODEV) if *port_id* invalid. 2995 * - (-EIO) if device is removed. 2996 * - (-EINVAL) if bad parameter. 2997 */ 2998 int rte_eth_dev_uc_all_hash_table_set(uint16_t port_id, uint8_t on); 2999 3000 /** 3001 * Set a traffic mirroring rule on an Ethernet device 3002 * 3003 * @param port_id 3004 * The port identifier of the Ethernet device. 3005 * @param mirror_conf 3006 * The pointer to the traffic mirroring structure describing the mirroring rule. 3007 * The *rte_eth_vm_mirror_conf* structure includes the type of mirroring rule, 3008 * destination pool and the value of rule if enable vlan or pool mirroring. 3009 * 3010 * @param rule_id 3011 * The index of traffic mirroring rule, we support four separated rules. 3012 * @param on 3013 * 1 - Enable a mirroring rule. 3014 * 0 - Disable a mirroring rule. 3015 * @return 3016 * - (0) if successful. 3017 * - (-ENOTSUP) if hardware doesn't support this feature. 3018 * - (-ENODEV) if *port_id* invalid. 3019 * - (-EIO) if device is removed. 3020 * - (-EINVAL) if the mr_conf information is not correct. 3021 */ 3022 int rte_eth_mirror_rule_set(uint16_t port_id, 3023 struct rte_eth_mirror_conf *mirror_conf, 3024 uint8_t rule_id, 3025 uint8_t on); 3026 3027 /** 3028 * Reset a traffic mirroring rule on an Ethernet device. 3029 * 3030 * @param port_id 3031 * The port identifier of the Ethernet device. 3032 * @param rule_id 3033 * The index of traffic mirroring rule, we support four separated rules. 3034 * @return 3035 * - (0) if successful. 3036 * - (-ENOTSUP) if hardware doesn't support this feature. 3037 * - (-ENODEV) if *port_id* invalid. 3038 * - (-EIO) if device is removed. 3039 * - (-EINVAL) if bad parameter. 3040 */ 3041 int rte_eth_mirror_rule_reset(uint16_t port_id, 3042 uint8_t rule_id); 3043 3044 /** 3045 * Set the rate limitation for a queue on an Ethernet device. 3046 * 3047 * @param port_id 3048 * The port identifier of the Ethernet device. 3049 * @param queue_idx 3050 * The queue id. 3051 * @param tx_rate 3052 * The tx rate in Mbps. Allocated from the total port link speed. 3053 * @return 3054 * - (0) if successful. 3055 * - (-ENOTSUP) if hardware doesn't support this feature. 3056 * - (-ENODEV) if *port_id* invalid. 3057 * - (-EIO) if device is removed. 3058 * - (-EINVAL) if bad parameter. 3059 */ 3060 int rte_eth_set_queue_rate_limit(uint16_t port_id, uint16_t queue_idx, 3061 uint16_t tx_rate); 3062 3063 /** 3064 * Configuration of Receive Side Scaling hash computation of Ethernet device. 3065 * 3066 * @param port_id 3067 * The port identifier of the Ethernet device. 3068 * @param rss_conf 3069 * The new configuration to use for RSS hash computation on the port. 3070 * @return 3071 * - (0) if successful. 3072 * - (-ENODEV) if port identifier is invalid. 3073 * - (-EIO) if device is removed. 3074 * - (-ENOTSUP) if hardware doesn't support. 3075 * - (-EINVAL) if bad parameter. 3076 */ 3077 int rte_eth_dev_rss_hash_update(uint16_t port_id, 3078 struct rte_eth_rss_conf *rss_conf); 3079 3080 /** 3081 * Retrieve current configuration of Receive Side Scaling hash computation 3082 * of Ethernet device. 3083 * 3084 * @param port_id 3085 * The port identifier of the Ethernet device. 3086 * @param rss_conf 3087 * Where to store the current RSS hash configuration of the Ethernet device. 3088 * @return 3089 * - (0) if successful. 3090 * - (-ENODEV) if port identifier is invalid. 3091 * - (-EIO) if device is removed. 3092 * - (-ENOTSUP) if hardware doesn't support RSS. 3093 */ 3094 int 3095 rte_eth_dev_rss_hash_conf_get(uint16_t port_id, 3096 struct rte_eth_rss_conf *rss_conf); 3097 3098 /** 3099 * Add UDP tunneling port for a specific type of tunnel. 3100 * The packets with this UDP port will be identified as this type of tunnel. 3101 * Before enabling any offloading function for a tunnel, users can call this API 3102 * to change or add more UDP port for the tunnel. So the offloading function 3103 * can take effect on the packets with the specific UDP port. 3104 * 3105 * @param port_id 3106 * The port identifier of the Ethernet device. 3107 * @param tunnel_udp 3108 * UDP tunneling configuration. 3109 * 3110 * @return 3111 * - (0) if successful. 3112 * - (-ENODEV) if port identifier is invalid. 3113 * - (-EIO) if device is removed. 3114 * - (-ENOTSUP) if hardware doesn't support tunnel type. 3115 */ 3116 int 3117 rte_eth_dev_udp_tunnel_port_add(uint16_t port_id, 3118 struct rte_eth_udp_tunnel *tunnel_udp); 3119 3120 /** 3121 * Delete UDP tunneling port a specific type of tunnel. 3122 * The packets with this UDP port will not be identified as this type of tunnel 3123 * any more. 3124 * Before enabling any offloading function for a tunnel, users can call this API 3125 * to delete a UDP port for the tunnel. So the offloading function will not take 3126 * effect on the packets with the specific UDP port. 3127 * 3128 * @param port_id 3129 * The port identifier of the Ethernet device. 3130 * @param tunnel_udp 3131 * UDP tunneling configuration. 3132 * 3133 * @return 3134 * - (0) if successful. 3135 * - (-ENODEV) if port identifier is invalid. 3136 * - (-EIO) if device is removed. 3137 * - (-ENOTSUP) if hardware doesn't support tunnel type. 3138 */ 3139 int 3140 rte_eth_dev_udp_tunnel_port_delete(uint16_t port_id, 3141 struct rte_eth_udp_tunnel *tunnel_udp); 3142 3143 /** 3144 * Check whether the filter type is supported on an Ethernet device. 3145 * All the supported filter types are defined in 'rte_eth_ctrl.h'. 3146 * 3147 * @param port_id 3148 * The port identifier of the Ethernet device. 3149 * @param filter_type 3150 * Filter type. 3151 * @return 3152 * - (0) if successful. 3153 * - (-ENOTSUP) if hardware doesn't support this filter type. 3154 * - (-ENODEV) if *port_id* invalid. 3155 * - (-EIO) if device is removed. 3156 */ 3157 int rte_eth_dev_filter_supported(uint16_t port_id, 3158 enum rte_filter_type filter_type); 3159 3160 /** 3161 * Take operations to assigned filter type on an Ethernet device. 3162 * All the supported operations and filter types are defined in 'rte_eth_ctrl.h'. 3163 * 3164 * @param port_id 3165 * The port identifier of the Ethernet device. 3166 * @param filter_type 3167 * Filter type. 3168 * @param filter_op 3169 * Type of operation. 3170 * @param arg 3171 * A pointer to arguments defined specifically for the operation. 3172 * @return 3173 * - (0) if successful. 3174 * - (-ENOTSUP) if hardware doesn't support. 3175 * - (-ENODEV) if *port_id* invalid. 3176 * - (-EIO) if device is removed. 3177 * - others depends on the specific operations implementation. 3178 */ 3179 int rte_eth_dev_filter_ctrl(uint16_t port_id, enum rte_filter_type filter_type, 3180 enum rte_filter_op filter_op, void *arg); 3181 3182 /** 3183 * Get DCB information on an Ethernet device. 3184 * 3185 * @param port_id 3186 * The port identifier of the Ethernet device. 3187 * @param dcb_info 3188 * dcb information. 3189 * @return 3190 * - (0) if successful. 3191 * - (-ENODEV) if port identifier is invalid. 3192 * - (-EIO) if device is removed. 3193 * - (-ENOTSUP) if hardware doesn't support. 3194 */ 3195 int rte_eth_dev_get_dcb_info(uint16_t port_id, 3196 struct rte_eth_dcb_info *dcb_info); 3197 3198 struct rte_eth_rxtx_callback; 3199 3200 /** 3201 * Add a callback to be called on packet RX on a given port and queue. 3202 * 3203 * This API configures a function to be called for each burst of 3204 * packets received on a given NIC port queue. The return value is a pointer 3205 * that can be used to later remove the callback using 3206 * rte_eth_remove_rx_callback(). 3207 * 3208 * Multiple functions are called in the order that they are added. 3209 * 3210 * @param port_id 3211 * The port identifier of the Ethernet device. 3212 * @param queue_id 3213 * The queue on the Ethernet device on which the callback is to be added. 3214 * @param fn 3215 * The callback function 3216 * @param user_param 3217 * A generic pointer parameter which will be passed to each invocation of the 3218 * callback function on this port and queue. 3219 * 3220 * @return 3221 * NULL on error. 3222 * On success, a pointer value which can later be used to remove the callback. 3223 */ 3224 const struct rte_eth_rxtx_callback * 3225 rte_eth_add_rx_callback(uint16_t port_id, uint16_t queue_id, 3226 rte_rx_callback_fn fn, void *user_param); 3227 3228 /** 3229 * Add a callback that must be called first on packet RX on a given port 3230 * and queue. 3231 * 3232 * This API configures a first function to be called for each burst of 3233 * packets received on a given NIC port queue. The return value is a pointer 3234 * that can be used to later remove the callback using 3235 * rte_eth_remove_rx_callback(). 3236 * 3237 * Multiple functions are called in the order that they are added. 3238 * 3239 * @param port_id 3240 * The port identifier of the Ethernet device. 3241 * @param queue_id 3242 * The queue on the Ethernet device on which the callback is to be added. 3243 * @param fn 3244 * The callback function 3245 * @param user_param 3246 * A generic pointer parameter which will be passed to each invocation of the 3247 * callback function on this port and queue. 3248 * 3249 * @return 3250 * NULL on error. 3251 * On success, a pointer value which can later be used to remove the callback. 3252 */ 3253 const struct rte_eth_rxtx_callback * 3254 rte_eth_add_first_rx_callback(uint16_t port_id, uint16_t queue_id, 3255 rte_rx_callback_fn fn, void *user_param); 3256 3257 /** 3258 * Add a callback to be called on packet TX on a given port and queue. 3259 * 3260 * This API configures a function to be called for each burst of 3261 * packets sent on a given NIC port queue. The return value is a pointer 3262 * that can be used to later remove the callback using 3263 * rte_eth_remove_tx_callback(). 3264 * 3265 * Multiple functions are called in the order that they are added. 3266 * 3267 * @param port_id 3268 * The port identifier of the Ethernet device. 3269 * @param queue_id 3270 * The queue on the Ethernet device on which the callback is to be added. 3271 * @param fn 3272 * The callback function 3273 * @param user_param 3274 * A generic pointer parameter which will be passed to each invocation of the 3275 * callback function on this port and queue. 3276 * 3277 * @return 3278 * NULL on error. 3279 * On success, a pointer value which can later be used to remove the callback. 3280 */ 3281 const struct rte_eth_rxtx_callback * 3282 rte_eth_add_tx_callback(uint16_t port_id, uint16_t queue_id, 3283 rte_tx_callback_fn fn, void *user_param); 3284 3285 /** 3286 * Remove an RX packet callback from a given port and queue. 3287 * 3288 * This function is used to removed callbacks that were added to a NIC port 3289 * queue using rte_eth_add_rx_callback(). 3290 * 3291 * Note: the callback is removed from the callback list but it isn't freed 3292 * since the it may still be in use. The memory for the callback can be 3293 * subsequently freed back by the application by calling rte_free(): 3294 * 3295 * - Immediately - if the port is stopped, or the user knows that no 3296 * callbacks are in flight e.g. if called from the thread doing RX/TX 3297 * on that queue. 3298 * 3299 * - After a short delay - where the delay is sufficient to allow any 3300 * in-flight callbacks to complete. 3301 * 3302 * @param port_id 3303 * The port identifier of the Ethernet device. 3304 * @param queue_id 3305 * The queue on the Ethernet device from which the callback is to be removed. 3306 * @param user_cb 3307 * User supplied callback created via rte_eth_add_rx_callback(). 3308 * 3309 * @return 3310 * - 0: Success. Callback was removed. 3311 * - -ENOTSUP: Callback support is not available. 3312 * - -EINVAL: The port_id or the queue_id is out of range, or the callback 3313 * is NULL or not found for the port/queue. 3314 */ 3315 int rte_eth_remove_rx_callback(uint16_t port_id, uint16_t queue_id, 3316 const struct rte_eth_rxtx_callback *user_cb); 3317 3318 /** 3319 * Remove a TX packet callback from a given port and queue. 3320 * 3321 * This function is used to removed callbacks that were added to a NIC port 3322 * queue using rte_eth_add_tx_callback(). 3323 * 3324 * Note: the callback is removed from the callback list but it isn't freed 3325 * since the it may still be in use. The memory for the callback can be 3326 * subsequently freed back by the application by calling rte_free(): 3327 * 3328 * - Immediately - if the port is stopped, or the user knows that no 3329 * callbacks are in flight e.g. if called from the thread doing RX/TX 3330 * on that queue. 3331 * 3332 * - After a short delay - where the delay is sufficient to allow any 3333 * in-flight callbacks to complete. 3334 * 3335 * @param port_id 3336 * The port identifier of the Ethernet device. 3337 * @param queue_id 3338 * The queue on the Ethernet device from which the callback is to be removed. 3339 * @param user_cb 3340 * User supplied callback created via rte_eth_add_tx_callback(). 3341 * 3342 * @return 3343 * - 0: Success. Callback was removed. 3344 * - -ENOTSUP: Callback support is not available. 3345 * - -EINVAL: The port_id or the queue_id is out of range, or the callback 3346 * is NULL or not found for the port/queue. 3347 */ 3348 int rte_eth_remove_tx_callback(uint16_t port_id, uint16_t queue_id, 3349 const struct rte_eth_rxtx_callback *user_cb); 3350 3351 /** 3352 * Retrieve information about given port's RX queue. 3353 * 3354 * @param port_id 3355 * The port identifier of the Ethernet device. 3356 * @param queue_id 3357 * The RX queue on the Ethernet device for which information 3358 * will be retrieved. 3359 * @param qinfo 3360 * A pointer to a structure of type *rte_eth_rxq_info_info* to be filled with 3361 * the information of the Ethernet device. 3362 * 3363 * @return 3364 * - 0: Success 3365 * - -ENOTSUP: routine is not supported by the device PMD. 3366 * - -EINVAL: The port_id or the queue_id is out of range. 3367 */ 3368 int rte_eth_rx_queue_info_get(uint16_t port_id, uint16_t queue_id, 3369 struct rte_eth_rxq_info *qinfo); 3370 3371 /** 3372 * Retrieve information about given port's TX queue. 3373 * 3374 * @param port_id 3375 * The port identifier of the Ethernet device. 3376 * @param queue_id 3377 * The TX queue on the Ethernet device for which information 3378 * will be retrieved. 3379 * @param qinfo 3380 * A pointer to a structure of type *rte_eth_txq_info_info* to be filled with 3381 * the information of the Ethernet device. 3382 * 3383 * @return 3384 * - 0: Success 3385 * - -ENOTSUP: routine is not supported by the device PMD. 3386 * - -EINVAL: The port_id or the queue_id is out of range. 3387 */ 3388 int rte_eth_tx_queue_info_get(uint16_t port_id, uint16_t queue_id, 3389 struct rte_eth_txq_info *qinfo); 3390 3391 /** 3392 * Retrieve device registers and register attributes (number of registers and 3393 * register size) 3394 * 3395 * @param port_id 3396 * The port identifier of the Ethernet device. 3397 * @param info 3398 * Pointer to rte_dev_reg_info structure to fill in. If info->data is 3399 * NULL the function fills in the width and length fields. If non-NULL 3400 * the registers are put into the buffer pointed at by the data field. 3401 * @return 3402 * - (0) if successful. 3403 * - (-ENOTSUP) if hardware doesn't support. 3404 * - (-ENODEV) if *port_id* invalid. 3405 * - (-EIO) if device is removed. 3406 * - others depends on the specific operations implementation. 3407 */ 3408 int rte_eth_dev_get_reg_info(uint16_t port_id, struct rte_dev_reg_info *info); 3409 3410 /** 3411 * Retrieve size of device EEPROM 3412 * 3413 * @param port_id 3414 * The port identifier of the Ethernet device. 3415 * @return 3416 * - (>=0) EEPROM size if successful. 3417 * - (-ENOTSUP) if hardware doesn't support. 3418 * - (-ENODEV) if *port_id* invalid. 3419 * - (-EIO) if device is removed. 3420 * - others depends on the specific operations implementation. 3421 */ 3422 int rte_eth_dev_get_eeprom_length(uint16_t port_id); 3423 3424 /** 3425 * Retrieve EEPROM and EEPROM attribute 3426 * 3427 * @param port_id 3428 * The port identifier of the Ethernet device. 3429 * @param info 3430 * The template includes buffer for return EEPROM data and 3431 * EEPROM attributes to be filled. 3432 * @return 3433 * - (0) if successful. 3434 * - (-ENOTSUP) if hardware doesn't support. 3435 * - (-ENODEV) if *port_id* invalid. 3436 * - (-EIO) if device is removed. 3437 * - others depends on the specific operations implementation. 3438 */ 3439 int rte_eth_dev_get_eeprom(uint16_t port_id, struct rte_dev_eeprom_info *info); 3440 3441 /** 3442 * Program EEPROM with provided data 3443 * 3444 * @param port_id 3445 * The port identifier of the Ethernet device. 3446 * @param info 3447 * The template includes EEPROM data for programming and 3448 * EEPROM attributes to be filled 3449 * @return 3450 * - (0) if successful. 3451 * - (-ENOTSUP) if hardware doesn't support. 3452 * - (-ENODEV) if *port_id* invalid. 3453 * - (-EIO) if device is removed. 3454 * - others depends on the specific operations implementation. 3455 */ 3456 int rte_eth_dev_set_eeprom(uint16_t port_id, struct rte_dev_eeprom_info *info); 3457 3458 /** 3459 * @warning 3460 * @b EXPERIMENTAL: this API may change without prior notice. 3461 * 3462 * Retrieve the type and size of plugin module EEPROM 3463 * 3464 * @param port_id 3465 * The port identifier of the Ethernet device. 3466 * @param modinfo 3467 * The type and size of plugin module EEPROM. 3468 * @return 3469 * - (0) if successful. 3470 * - (-ENOTSUP) if hardware doesn't support. 3471 * - (-ENODEV) if *port_id* invalid. 3472 * - (-EIO) if device is removed. 3473 * - others depends on the specific operations implementation. 3474 */ 3475 int __rte_experimental 3476 rte_eth_dev_get_module_info(uint16_t port_id, 3477 struct rte_eth_dev_module_info *modinfo); 3478 3479 /** 3480 * @warning 3481 * @b EXPERIMENTAL: this API may change without prior notice. 3482 * 3483 * Retrieve the data of plugin module EEPROM 3484 * 3485 * @param port_id 3486 * The port identifier of the Ethernet device. 3487 * @param info 3488 * The template includes the plugin module EEPROM attributes, and the 3489 * buffer for return plugin module EEPROM data. 3490 * @return 3491 * - (0) if successful. 3492 * - (-ENOTSUP) if hardware doesn't support. 3493 * - (-ENODEV) if *port_id* invalid. 3494 * - (-EIO) if device is removed. 3495 * - others depends on the specific operations implementation. 3496 */ 3497 int __rte_experimental 3498 rte_eth_dev_get_module_eeprom(uint16_t port_id, 3499 struct rte_dev_eeprom_info *info); 3500 3501 /** 3502 * Set the list of multicast addresses to filter on an Ethernet device. 3503 * 3504 * @param port_id 3505 * The port identifier of the Ethernet device. 3506 * @param mc_addr_set 3507 * The array of multicast addresses to set. Equal to NULL when the function 3508 * is invoked to flush the set of filtered addresses. 3509 * @param nb_mc_addr 3510 * The number of multicast addresses in the *mc_addr_set* array. Equal to 0 3511 * when the function is invoked to flush the set of filtered addresses. 3512 * @return 3513 * - (0) if successful. 3514 * - (-ENODEV) if *port_id* invalid. 3515 * - (-EIO) if device is removed. 3516 * - (-ENOTSUP) if PMD of *port_id* doesn't support multicast filtering. 3517 * - (-ENOSPC) if *port_id* has not enough multicast filtering resources. 3518 */ 3519 int rte_eth_dev_set_mc_addr_list(uint16_t port_id, 3520 struct ether_addr *mc_addr_set, 3521 uint32_t nb_mc_addr); 3522 3523 /** 3524 * Enable IEEE1588/802.1AS timestamping for an Ethernet device. 3525 * 3526 * @param port_id 3527 * The port identifier of the Ethernet device. 3528 * 3529 * @return 3530 * - 0: Success. 3531 * - -ENODEV: The port ID is invalid. 3532 * - -EIO: if device is removed. 3533 * - -ENOTSUP: The function is not supported by the Ethernet driver. 3534 */ 3535 int rte_eth_timesync_enable(uint16_t port_id); 3536 3537 /** 3538 * Disable IEEE1588/802.1AS timestamping for an Ethernet device. 3539 * 3540 * @param port_id 3541 * The port identifier of the Ethernet device. 3542 * 3543 * @return 3544 * - 0: Success. 3545 * - -ENODEV: The port ID is invalid. 3546 * - -EIO: if device is removed. 3547 * - -ENOTSUP: The function is not supported by the Ethernet driver. 3548 */ 3549 int rte_eth_timesync_disable(uint16_t port_id); 3550 3551 /** 3552 * Read an IEEE1588/802.1AS RX timestamp from an Ethernet device. 3553 * 3554 * @param port_id 3555 * The port identifier of the Ethernet device. 3556 * @param timestamp 3557 * Pointer to the timestamp struct. 3558 * @param flags 3559 * Device specific flags. Used to pass the RX timesync register index to 3560 * i40e. Unused in igb/ixgbe, pass 0 instead. 3561 * 3562 * @return 3563 * - 0: Success. 3564 * - -EINVAL: No timestamp is available. 3565 * - -ENODEV: The port ID is invalid. 3566 * - -EIO: if device is removed. 3567 * - -ENOTSUP: The function is not supported by the Ethernet driver. 3568 */ 3569 int rte_eth_timesync_read_rx_timestamp(uint16_t port_id, 3570 struct timespec *timestamp, uint32_t flags); 3571 3572 /** 3573 * Read an IEEE1588/802.1AS TX timestamp from an Ethernet device. 3574 * 3575 * @param port_id 3576 * The port identifier of the Ethernet device. 3577 * @param timestamp 3578 * Pointer to the timestamp struct. 3579 * 3580 * @return 3581 * - 0: Success. 3582 * - -EINVAL: No timestamp is available. 3583 * - -ENODEV: The port ID is invalid. 3584 * - -EIO: if device is removed. 3585 * - -ENOTSUP: The function is not supported by the Ethernet driver. 3586 */ 3587 int rte_eth_timesync_read_tx_timestamp(uint16_t port_id, 3588 struct timespec *timestamp); 3589 3590 /** 3591 * Adjust the timesync clock on an Ethernet device. 3592 * 3593 * This is usually used in conjunction with other Ethdev timesync functions to 3594 * synchronize the device time using the IEEE1588/802.1AS protocol. 3595 * 3596 * @param port_id 3597 * The port identifier of the Ethernet device. 3598 * @param delta 3599 * The adjustment in nanoseconds. 3600 * 3601 * @return 3602 * - 0: Success. 3603 * - -ENODEV: The port ID is invalid. 3604 * - -EIO: if device is removed. 3605 * - -ENOTSUP: The function is not supported by the Ethernet driver. 3606 */ 3607 int rte_eth_timesync_adjust_time(uint16_t port_id, int64_t delta); 3608 3609 /** 3610 * Read the time from the timesync clock on an Ethernet device. 3611 * 3612 * This is usually used in conjunction with other Ethdev timesync functions to 3613 * synchronize the device time using the IEEE1588/802.1AS protocol. 3614 * 3615 * @param port_id 3616 * The port identifier of the Ethernet device. 3617 * @param time 3618 * Pointer to the timespec struct that holds the time. 3619 * 3620 * @return 3621 * - 0: Success. 3622 */ 3623 int rte_eth_timesync_read_time(uint16_t port_id, struct timespec *time); 3624 3625 /** 3626 * Set the time of the timesync clock on an Ethernet device. 3627 * 3628 * This is usually used in conjunction with other Ethdev timesync functions to 3629 * synchronize the device time using the IEEE1588/802.1AS protocol. 3630 * 3631 * @param port_id 3632 * The port identifier of the Ethernet device. 3633 * @param time 3634 * Pointer to the timespec struct that holds the time. 3635 * 3636 * @return 3637 * - 0: Success. 3638 * - -EINVAL: No timestamp is available. 3639 * - -ENODEV: The port ID is invalid. 3640 * - -EIO: if device is removed. 3641 * - -ENOTSUP: The function is not supported by the Ethernet driver. 3642 */ 3643 int rte_eth_timesync_write_time(uint16_t port_id, const struct timespec *time); 3644 3645 /** 3646 * Config l2 tunnel ether type of an Ethernet device for filtering specific 3647 * tunnel packets by ether type. 3648 * 3649 * @param port_id 3650 * The port identifier of the Ethernet device. 3651 * @param l2_tunnel 3652 * l2 tunnel configuration. 3653 * 3654 * @return 3655 * - (0) if successful. 3656 * - (-ENODEV) if port identifier is invalid. 3657 * - (-EIO) if device is removed. 3658 * - (-ENOTSUP) if hardware doesn't support tunnel type. 3659 */ 3660 int 3661 rte_eth_dev_l2_tunnel_eth_type_conf(uint16_t port_id, 3662 struct rte_eth_l2_tunnel_conf *l2_tunnel); 3663 3664 /** 3665 * Enable/disable l2 tunnel offload functions. Include, 3666 * 1, The ability of parsing a type of l2 tunnel of an Ethernet device. 3667 * Filtering, forwarding and offloading this type of tunnel packets depend on 3668 * this ability. 3669 * 2, Stripping the l2 tunnel tag. 3670 * 3, Insertion of the l2 tunnel tag. 3671 * 4, Forwarding the packets based on the l2 tunnel tag. 3672 * 3673 * @param port_id 3674 * The port identifier of the Ethernet device. 3675 * @param l2_tunnel 3676 * l2 tunnel parameters. 3677 * @param mask 3678 * Indicate the offload function. 3679 * @param en 3680 * Enable or disable this function. 3681 * 3682 * @return 3683 * - (0) if successful. 3684 * - (-ENODEV) if port identifier is invalid. 3685 * - (-EIO) if device is removed. 3686 * - (-ENOTSUP) if hardware doesn't support tunnel type. 3687 */ 3688 int 3689 rte_eth_dev_l2_tunnel_offload_set(uint16_t port_id, 3690 struct rte_eth_l2_tunnel_conf *l2_tunnel, 3691 uint32_t mask, 3692 uint8_t en); 3693 3694 /** 3695 * Get the port id from device name. The device name should be specified 3696 * as below: 3697 * - PCIe address (Domain:Bus:Device.Function), for example- 0000:2:00.0 3698 * - SoC device name, for example- fsl-gmac0 3699 * - vdev dpdk name, for example- net_[pcap0|null0|tap0] 3700 * 3701 * @param name 3702 * pci address or name of the device 3703 * @param port_id 3704 * pointer to port identifier of the device 3705 * @return 3706 * - (0) if successful and port_id is filled. 3707 * - (-ENODEV or -EINVAL) on failure. 3708 */ 3709 int 3710 rte_eth_dev_get_port_by_name(const char *name, uint16_t *port_id); 3711 3712 /** 3713 * Get the device name from port id. The device name is specified as below: 3714 * - PCIe address (Domain:Bus:Device.Function), for example- 0000:02:00.0 3715 * - SoC device name, for example- fsl-gmac0 3716 * - vdev dpdk name, for example- net_[pcap0|null0|tun0|tap0] 3717 * 3718 * @param port_id 3719 * Port identifier of the device. 3720 * @param name 3721 * Buffer of size RTE_ETH_NAME_MAX_LEN to store the name. 3722 * @return 3723 * - (0) if successful. 3724 * - (-EINVAL) on failure. 3725 */ 3726 int 3727 rte_eth_dev_get_name_by_port(uint16_t port_id, char *name); 3728 3729 /** 3730 * Check that numbers of Rx and Tx descriptors satisfy descriptors limits from 3731 * the ethernet device information, otherwise adjust them to boundaries. 3732 * 3733 * @param port_id 3734 * The port identifier of the Ethernet device. 3735 * @param nb_rx_desc 3736 * A pointer to a uint16_t where the number of receive 3737 * descriptors stored. 3738 * @param nb_tx_desc 3739 * A pointer to a uint16_t where the number of transmit 3740 * descriptors stored. 3741 * @return 3742 * - (0) if successful. 3743 * - (-ENOTSUP, -ENODEV or -EINVAL) on failure. 3744 */ 3745 int rte_eth_dev_adjust_nb_rx_tx_desc(uint16_t port_id, 3746 uint16_t *nb_rx_desc, 3747 uint16_t *nb_tx_desc); 3748 3749 /** 3750 * Test if a port supports specific mempool ops. 3751 * 3752 * @param port_id 3753 * Port identifier of the Ethernet device. 3754 * @param [in] pool 3755 * The name of the pool operations to test. 3756 * @return 3757 * - 0: best mempool ops choice for this port. 3758 * - 1: mempool ops are supported for this port. 3759 * - -ENOTSUP: mempool ops not supported for this port. 3760 * - -ENODEV: Invalid port Identifier. 3761 * - -EINVAL: Pool param is null. 3762 */ 3763 int 3764 rte_eth_dev_pool_ops_supported(uint16_t port_id, const char *pool); 3765 3766 /** 3767 * Get the security context for the Ethernet device. 3768 * 3769 * @param port_id 3770 * Port identifier of the Ethernet device 3771 * @return 3772 * - NULL on error. 3773 * - pointer to security context on success. 3774 */ 3775 void * 3776 rte_eth_dev_get_sec_ctx(uint16_t port_id); 3777 3778 3779 #include <rte_ethdev_core.h> 3780 3781 /** 3782 * 3783 * Retrieve a burst of input packets from a receive queue of an Ethernet 3784 * device. The retrieved packets are stored in *rte_mbuf* structures whose 3785 * pointers are supplied in the *rx_pkts* array. 3786 * 3787 * The rte_eth_rx_burst() function loops, parsing the RX ring of the 3788 * receive queue, up to *nb_pkts* packets, and for each completed RX 3789 * descriptor in the ring, it performs the following operations: 3790 * 3791 * - Initialize the *rte_mbuf* data structure associated with the 3792 * RX descriptor according to the information provided by the NIC into 3793 * that RX descriptor. 3794 * 3795 * - Store the *rte_mbuf* data structure into the next entry of the 3796 * *rx_pkts* array. 3797 * 3798 * - Replenish the RX descriptor with a new *rte_mbuf* buffer 3799 * allocated from the memory pool associated with the receive queue at 3800 * initialization time. 3801 * 3802 * When retrieving an input packet that was scattered by the controller 3803 * into multiple receive descriptors, the rte_eth_rx_burst() function 3804 * appends the associated *rte_mbuf* buffers to the first buffer of the 3805 * packet. 3806 * 3807 * The rte_eth_rx_burst() function returns the number of packets 3808 * actually retrieved, which is the number of *rte_mbuf* data structures 3809 * effectively supplied into the *rx_pkts* array. 3810 * A return value equal to *nb_pkts* indicates that the RX queue contained 3811 * at least *rx_pkts* packets, and this is likely to signify that other 3812 * received packets remain in the input queue. Applications implementing 3813 * a "retrieve as much received packets as possible" policy can check this 3814 * specific case and keep invoking the rte_eth_rx_burst() function until 3815 * a value less than *nb_pkts* is returned. 3816 * 3817 * This receive method has the following advantages: 3818 * 3819 * - It allows a run-to-completion network stack engine to retrieve and 3820 * to immediately process received packets in a fast burst-oriented 3821 * approach, avoiding the overhead of unnecessary intermediate packet 3822 * queue/dequeue operations. 3823 * 3824 * - Conversely, it also allows an asynchronous-oriented processing 3825 * method to retrieve bursts of received packets and to immediately 3826 * queue them for further parallel processing by another logical core, 3827 * for instance. However, instead of having received packets being 3828 * individually queued by the driver, this approach allows the caller 3829 * of the rte_eth_rx_burst() function to queue a burst of retrieved 3830 * packets at a time and therefore dramatically reduce the cost of 3831 * enqueue/dequeue operations per packet. 3832 * 3833 * - It allows the rte_eth_rx_burst() function of the driver to take 3834 * advantage of burst-oriented hardware features (CPU cache, 3835 * prefetch instructions, and so on) to minimize the number of CPU 3836 * cycles per packet. 3837 * 3838 * To summarize, the proposed receive API enables many 3839 * burst-oriented optimizations in both synchronous and asynchronous 3840 * packet processing environments with no overhead in both cases. 3841 * 3842 * The rte_eth_rx_burst() function does not provide any error 3843 * notification to avoid the corresponding overhead. As a hint, the 3844 * upper-level application might check the status of the device link once 3845 * being systematically returned a 0 value for a given number of tries. 3846 * 3847 * @param port_id 3848 * The port identifier of the Ethernet device. 3849 * @param queue_id 3850 * The index of the receive queue from which to retrieve input packets. 3851 * The value must be in the range [0, nb_rx_queue - 1] previously supplied 3852 * to rte_eth_dev_configure(). 3853 * @param rx_pkts 3854 * The address of an array of pointers to *rte_mbuf* structures that 3855 * must be large enough to store *nb_pkts* pointers in it. 3856 * @param nb_pkts 3857 * The maximum number of packets to retrieve. 3858 * @return 3859 * The number of packets actually retrieved, which is the number 3860 * of pointers to *rte_mbuf* structures effectively supplied to the 3861 * *rx_pkts* array. 3862 */ 3863 static inline uint16_t 3864 rte_eth_rx_burst(uint16_t port_id, uint16_t queue_id, 3865 struct rte_mbuf **rx_pkts, const uint16_t nb_pkts) 3866 { 3867 struct rte_eth_dev *dev = &rte_eth_devices[port_id]; 3868 uint16_t nb_rx; 3869 3870 #ifdef RTE_LIBRTE_ETHDEV_DEBUG 3871 RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, 0); 3872 RTE_FUNC_PTR_OR_ERR_RET(*dev->rx_pkt_burst, 0); 3873 3874 if (queue_id >= dev->data->nb_rx_queues) { 3875 RTE_ETHDEV_LOG(ERR, "Invalid RX queue_id=%u\n", queue_id); 3876 return 0; 3877 } 3878 #endif 3879 nb_rx = (*dev->rx_pkt_burst)(dev->data->rx_queues[queue_id], 3880 rx_pkts, nb_pkts); 3881 3882 #ifdef RTE_ETHDEV_RXTX_CALLBACKS 3883 if (unlikely(dev->post_rx_burst_cbs[queue_id] != NULL)) { 3884 struct rte_eth_rxtx_callback *cb = 3885 dev->post_rx_burst_cbs[queue_id]; 3886 3887 do { 3888 nb_rx = cb->fn.rx(port_id, queue_id, rx_pkts, nb_rx, 3889 nb_pkts, cb->param); 3890 cb = cb->next; 3891 } while (cb != NULL); 3892 } 3893 #endif 3894 3895 return nb_rx; 3896 } 3897 3898 /** 3899 * Get the number of used descriptors of a rx queue 3900 * 3901 * @param port_id 3902 * The port identifier of the Ethernet device. 3903 * @param queue_id 3904 * The queue id on the specific port. 3905 * @return 3906 * The number of used descriptors in the specific queue, or: 3907 * (-EINVAL) if *port_id* or *queue_id* is invalid 3908 * (-ENOTSUP) if the device does not support this function 3909 */ 3910 static inline int 3911 rte_eth_rx_queue_count(uint16_t port_id, uint16_t queue_id) 3912 { 3913 struct rte_eth_dev *dev; 3914 3915 RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -EINVAL); 3916 dev = &rte_eth_devices[port_id]; 3917 RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_queue_count, -ENOTSUP); 3918 if (queue_id >= dev->data->nb_rx_queues) 3919 return -EINVAL; 3920 3921 return (int)(*dev->dev_ops->rx_queue_count)(dev, queue_id); 3922 } 3923 3924 /** 3925 * Check if the DD bit of the specific RX descriptor in the queue has been set 3926 * 3927 * @param port_id 3928 * The port identifier of the Ethernet device. 3929 * @param queue_id 3930 * The queue id on the specific port. 3931 * @param offset 3932 * The offset of the descriptor ID from tail. 3933 * @return 3934 * - (1) if the specific DD bit is set. 3935 * - (0) if the specific DD bit is not set. 3936 * - (-ENODEV) if *port_id* invalid. 3937 * - (-ENOTSUP) if the device does not support this function 3938 */ 3939 static inline int 3940 rte_eth_rx_descriptor_done(uint16_t port_id, uint16_t queue_id, uint16_t offset) 3941 { 3942 struct rte_eth_dev *dev = &rte_eth_devices[port_id]; 3943 RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); 3944 RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_descriptor_done, -ENOTSUP); 3945 return (*dev->dev_ops->rx_descriptor_done)( \ 3946 dev->data->rx_queues[queue_id], offset); 3947 } 3948 3949 #define RTE_ETH_RX_DESC_AVAIL 0 /**< Desc available for hw. */ 3950 #define RTE_ETH_RX_DESC_DONE 1 /**< Desc done, filled by hw. */ 3951 #define RTE_ETH_RX_DESC_UNAVAIL 2 /**< Desc used by driver or hw. */ 3952 3953 /** 3954 * Check the status of a Rx descriptor in the queue 3955 * 3956 * It should be called in a similar context than the Rx function: 3957 * - on a dataplane core 3958 * - not concurrently on the same queue 3959 * 3960 * Since it's a dataplane function, no check is performed on port_id and 3961 * queue_id. The caller must therefore ensure that the port is enabled 3962 * and the queue is configured and running. 3963 * 3964 * Note: accessing to a random descriptor in the ring may trigger cache 3965 * misses and have a performance impact. 3966 * 3967 * @param port_id 3968 * A valid port identifier of the Ethernet device which. 3969 * @param queue_id 3970 * A valid Rx queue identifier on this port. 3971 * @param offset 3972 * The offset of the descriptor starting from tail (0 is the next 3973 * packet to be received by the driver). 3974 * 3975 * @return 3976 * - (RTE_ETH_RX_DESC_AVAIL): Descriptor is available for the hardware to 3977 * receive a packet. 3978 * - (RTE_ETH_RX_DESC_DONE): Descriptor is done, it is filled by hw, but 3979 * not yet processed by the driver (i.e. in the receive queue). 3980 * - (RTE_ETH_RX_DESC_UNAVAIL): Descriptor is unavailable, either hold by 3981 * the driver and not yet returned to hw, or reserved by the hw. 3982 * - (-EINVAL) bad descriptor offset. 3983 * - (-ENOTSUP) if the device does not support this function. 3984 * - (-ENODEV) bad port or queue (only if compiled with debug). 3985 */ 3986 static inline int 3987 rte_eth_rx_descriptor_status(uint16_t port_id, uint16_t queue_id, 3988 uint16_t offset) 3989 { 3990 struct rte_eth_dev *dev; 3991 void *rxq; 3992 3993 #ifdef RTE_LIBRTE_ETHDEV_DEBUG 3994 RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); 3995 #endif 3996 dev = &rte_eth_devices[port_id]; 3997 #ifdef RTE_LIBRTE_ETHDEV_DEBUG 3998 if (queue_id >= dev->data->nb_rx_queues) 3999 return -ENODEV; 4000 #endif 4001 RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_descriptor_status, -ENOTSUP); 4002 rxq = dev->data->rx_queues[queue_id]; 4003 4004 return (*dev->dev_ops->rx_descriptor_status)(rxq, offset); 4005 } 4006 4007 #define RTE_ETH_TX_DESC_FULL 0 /**< Desc filled for hw, waiting xmit. */ 4008 #define RTE_ETH_TX_DESC_DONE 1 /**< Desc done, packet is transmitted. */ 4009 #define RTE_ETH_TX_DESC_UNAVAIL 2 /**< Desc used by driver or hw. */ 4010 4011 /** 4012 * Check the status of a Tx descriptor in the queue. 4013 * 4014 * It should be called in a similar context than the Tx function: 4015 * - on a dataplane core 4016 * - not concurrently on the same queue 4017 * 4018 * Since it's a dataplane function, no check is performed on port_id and 4019 * queue_id. The caller must therefore ensure that the port is enabled 4020 * and the queue is configured and running. 4021 * 4022 * Note: accessing to a random descriptor in the ring may trigger cache 4023 * misses and have a performance impact. 4024 * 4025 * @param port_id 4026 * A valid port identifier of the Ethernet device which. 4027 * @param queue_id 4028 * A valid Tx queue identifier on this port. 4029 * @param offset 4030 * The offset of the descriptor starting from tail (0 is the place where 4031 * the next packet will be send). 4032 * 4033 * @return 4034 * - (RTE_ETH_TX_DESC_FULL) Descriptor is being processed by the hw, i.e. 4035 * in the transmit queue. 4036 * - (RTE_ETH_TX_DESC_DONE) Hardware is done with this descriptor, it can 4037 * be reused by the driver. 4038 * - (RTE_ETH_TX_DESC_UNAVAIL): Descriptor is unavailable, reserved by the 4039 * driver or the hardware. 4040 * - (-EINVAL) bad descriptor offset. 4041 * - (-ENOTSUP) if the device does not support this function. 4042 * - (-ENODEV) bad port or queue (only if compiled with debug). 4043 */ 4044 static inline int rte_eth_tx_descriptor_status(uint16_t port_id, 4045 uint16_t queue_id, uint16_t offset) 4046 { 4047 struct rte_eth_dev *dev; 4048 void *txq; 4049 4050 #ifdef RTE_LIBRTE_ETHDEV_DEBUG 4051 RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); 4052 #endif 4053 dev = &rte_eth_devices[port_id]; 4054 #ifdef RTE_LIBRTE_ETHDEV_DEBUG 4055 if (queue_id >= dev->data->nb_tx_queues) 4056 return -ENODEV; 4057 #endif 4058 RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->tx_descriptor_status, -ENOTSUP); 4059 txq = dev->data->tx_queues[queue_id]; 4060 4061 return (*dev->dev_ops->tx_descriptor_status)(txq, offset); 4062 } 4063 4064 /** 4065 * Send a burst of output packets on a transmit queue of an Ethernet device. 4066 * 4067 * The rte_eth_tx_burst() function is invoked to transmit output packets 4068 * on the output queue *queue_id* of the Ethernet device designated by its 4069 * *port_id*. 4070 * The *nb_pkts* parameter is the number of packets to send which are 4071 * supplied in the *tx_pkts* array of *rte_mbuf* structures, each of them 4072 * allocated from a pool created with rte_pktmbuf_pool_create(). 4073 * The rte_eth_tx_burst() function loops, sending *nb_pkts* packets, 4074 * up to the number of transmit descriptors available in the TX ring of the 4075 * transmit queue. 4076 * For each packet to send, the rte_eth_tx_burst() function performs 4077 * the following operations: 4078 * 4079 * - Pick up the next available descriptor in the transmit ring. 4080 * 4081 * - Free the network buffer previously sent with that descriptor, if any. 4082 * 4083 * - Initialize the transmit descriptor with the information provided 4084 * in the *rte_mbuf data structure. 4085 * 4086 * In the case of a segmented packet composed of a list of *rte_mbuf* buffers, 4087 * the rte_eth_tx_burst() function uses several transmit descriptors 4088 * of the ring. 4089 * 4090 * The rte_eth_tx_burst() function returns the number of packets it 4091 * actually sent. A return value equal to *nb_pkts* means that all packets 4092 * have been sent, and this is likely to signify that other output packets 4093 * could be immediately transmitted again. Applications that implement a 4094 * "send as many packets to transmit as possible" policy can check this 4095 * specific case and keep invoking the rte_eth_tx_burst() function until 4096 * a value less than *nb_pkts* is returned. 4097 * 4098 * It is the responsibility of the rte_eth_tx_burst() function to 4099 * transparently free the memory buffers of packets previously sent. 4100 * This feature is driven by the *tx_free_thresh* value supplied to the 4101 * rte_eth_dev_configure() function at device configuration time. 4102 * When the number of free TX descriptors drops below this threshold, the 4103 * rte_eth_tx_burst() function must [attempt to] free the *rte_mbuf* buffers 4104 * of those packets whose transmission was effectively completed. 4105 * 4106 * If the PMD is DEV_TX_OFFLOAD_MT_LOCKFREE capable, multiple threads can 4107 * invoke this function concurrently on the same tx queue without SW lock. 4108 * @see rte_eth_dev_info_get, struct rte_eth_txconf::offloads 4109 * 4110 * @see rte_eth_tx_prepare to perform some prior checks or adjustments 4111 * for offloads. 4112 * 4113 * @param port_id 4114 * The port identifier of the Ethernet device. 4115 * @param queue_id 4116 * The index of the transmit queue through which output packets must be 4117 * sent. 4118 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 4119 * to rte_eth_dev_configure(). 4120 * @param tx_pkts 4121 * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures 4122 * which contain the output packets. 4123 * @param nb_pkts 4124 * The maximum number of packets to transmit. 4125 * @return 4126 * The number of output packets actually stored in transmit descriptors of 4127 * the transmit ring. The return value can be less than the value of the 4128 * *tx_pkts* parameter when the transmit ring is full or has been filled up. 4129 */ 4130 static inline uint16_t 4131 rte_eth_tx_burst(uint16_t port_id, uint16_t queue_id, 4132 struct rte_mbuf **tx_pkts, uint16_t nb_pkts) 4133 { 4134 struct rte_eth_dev *dev = &rte_eth_devices[port_id]; 4135 4136 #ifdef RTE_LIBRTE_ETHDEV_DEBUG 4137 RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, 0); 4138 RTE_FUNC_PTR_OR_ERR_RET(*dev->tx_pkt_burst, 0); 4139 4140 if (queue_id >= dev->data->nb_tx_queues) { 4141 RTE_ETHDEV_LOG(ERR, "Invalid TX queue_id=%u\n", queue_id); 4142 return 0; 4143 } 4144 #endif 4145 4146 #ifdef RTE_ETHDEV_RXTX_CALLBACKS 4147 struct rte_eth_rxtx_callback *cb = dev->pre_tx_burst_cbs[queue_id]; 4148 4149 if (unlikely(cb != NULL)) { 4150 do { 4151 nb_pkts = cb->fn.tx(port_id, queue_id, tx_pkts, nb_pkts, 4152 cb->param); 4153 cb = cb->next; 4154 } while (cb != NULL); 4155 } 4156 #endif 4157 4158 return (*dev->tx_pkt_burst)(dev->data->tx_queues[queue_id], tx_pkts, nb_pkts); 4159 } 4160 4161 /** 4162 * Process a burst of output packets on a transmit queue of an Ethernet device. 4163 * 4164 * The rte_eth_tx_prepare() function is invoked to prepare output packets to be 4165 * transmitted on the output queue *queue_id* of the Ethernet device designated 4166 * by its *port_id*. 4167 * The *nb_pkts* parameter is the number of packets to be prepared which are 4168 * supplied in the *tx_pkts* array of *rte_mbuf* structures, each of them 4169 * allocated from a pool created with rte_pktmbuf_pool_create(). 4170 * For each packet to send, the rte_eth_tx_prepare() function performs 4171 * the following operations: 4172 * 4173 * - Check if packet meets devices requirements for tx offloads. 4174 * 4175 * - Check limitations about number of segments. 4176 * 4177 * - Check additional requirements when debug is enabled. 4178 * 4179 * - Update and/or reset required checksums when tx offload is set for packet. 4180 * 4181 * Since this function can modify packet data, provided mbufs must be safely 4182 * writable (e.g. modified data cannot be in shared segment). 4183 * 4184 * The rte_eth_tx_prepare() function returns the number of packets ready to be 4185 * sent. A return value equal to *nb_pkts* means that all packets are valid and 4186 * ready to be sent, otherwise stops processing on the first invalid packet and 4187 * leaves the rest packets untouched. 4188 * 4189 * When this functionality is not implemented in the driver, all packets are 4190 * are returned untouched. 4191 * 4192 * @param port_id 4193 * The port identifier of the Ethernet device. 4194 * The value must be a valid port id. 4195 * @param queue_id 4196 * The index of the transmit queue through which output packets must be 4197 * sent. 4198 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 4199 * to rte_eth_dev_configure(). 4200 * @param tx_pkts 4201 * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures 4202 * which contain the output packets. 4203 * @param nb_pkts 4204 * The maximum number of packets to process. 4205 * @return 4206 * The number of packets correct and ready to be sent. The return value can be 4207 * less than the value of the *tx_pkts* parameter when some packet doesn't 4208 * meet devices requirements with rte_errno set appropriately: 4209 * - EINVAL: offload flags are not correctly set 4210 * - ENOTSUP: the offload feature is not supported by the hardware 4211 * 4212 */ 4213 4214 #ifndef RTE_ETHDEV_TX_PREPARE_NOOP 4215 4216 static inline uint16_t 4217 rte_eth_tx_prepare(uint16_t port_id, uint16_t queue_id, 4218 struct rte_mbuf **tx_pkts, uint16_t nb_pkts) 4219 { 4220 struct rte_eth_dev *dev; 4221 4222 #ifdef RTE_LIBRTE_ETHDEV_DEBUG 4223 if (!rte_eth_dev_is_valid_port(port_id)) { 4224 RTE_ETHDEV_LOG(ERR, "Invalid TX port_id=%u\n", port_id); 4225 rte_errno = EINVAL; 4226 return 0; 4227 } 4228 #endif 4229 4230 dev = &rte_eth_devices[port_id]; 4231 4232 #ifdef RTE_LIBRTE_ETHDEV_DEBUG 4233 if (queue_id >= dev->data->nb_tx_queues) { 4234 RTE_ETHDEV_LOG(ERR, "Invalid TX queue_id=%u\n", queue_id); 4235 rte_errno = EINVAL; 4236 return 0; 4237 } 4238 #endif 4239 4240 if (!dev->tx_pkt_prepare) 4241 return nb_pkts; 4242 4243 return (*dev->tx_pkt_prepare)(dev->data->tx_queues[queue_id], 4244 tx_pkts, nb_pkts); 4245 } 4246 4247 #else 4248 4249 /* 4250 * Native NOOP operation for compilation targets which doesn't require any 4251 * preparations steps, and functional NOOP may introduce unnecessary performance 4252 * drop. 4253 * 4254 * Generally this is not a good idea to turn it on globally and didn't should 4255 * be used if behavior of tx_preparation can change. 4256 */ 4257 4258 static inline uint16_t 4259 rte_eth_tx_prepare(__rte_unused uint16_t port_id, 4260 __rte_unused uint16_t queue_id, 4261 __rte_unused struct rte_mbuf **tx_pkts, uint16_t nb_pkts) 4262 { 4263 return nb_pkts; 4264 } 4265 4266 #endif 4267 4268 /** 4269 * Send any packets queued up for transmission on a port and HW queue 4270 * 4271 * This causes an explicit flush of packets previously buffered via the 4272 * rte_eth_tx_buffer() function. It returns the number of packets successfully 4273 * sent to the NIC, and calls the error callback for any unsent packets. Unless 4274 * explicitly set up otherwise, the default callback simply frees the unsent 4275 * packets back to the owning mempool. 4276 * 4277 * @param port_id 4278 * The port identifier of the Ethernet device. 4279 * @param queue_id 4280 * The index of the transmit queue through which output packets must be 4281 * sent. 4282 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 4283 * to rte_eth_dev_configure(). 4284 * @param buffer 4285 * Buffer of packets to be transmit. 4286 * @return 4287 * The number of packets successfully sent to the Ethernet device. The error 4288 * callback is called for any packets which could not be sent. 4289 */ 4290 static inline uint16_t 4291 rte_eth_tx_buffer_flush(uint16_t port_id, uint16_t queue_id, 4292 struct rte_eth_dev_tx_buffer *buffer) 4293 { 4294 uint16_t sent; 4295 uint16_t to_send = buffer->length; 4296 4297 if (to_send == 0) 4298 return 0; 4299 4300 sent = rte_eth_tx_burst(port_id, queue_id, buffer->pkts, to_send); 4301 4302 buffer->length = 0; 4303 4304 /* All packets sent, or to be dealt with by callback below */ 4305 if (unlikely(sent != to_send)) 4306 buffer->error_callback(&buffer->pkts[sent], 4307 (uint16_t)(to_send - sent), 4308 buffer->error_userdata); 4309 4310 return sent; 4311 } 4312 4313 /** 4314 * Buffer a single packet for future transmission on a port and queue 4315 * 4316 * This function takes a single mbuf/packet and buffers it for later 4317 * transmission on the particular port and queue specified. Once the buffer is 4318 * full of packets, an attempt will be made to transmit all the buffered 4319 * packets. In case of error, where not all packets can be transmitted, a 4320 * callback is called with the unsent packets as a parameter. If no callback 4321 * is explicitly set up, the unsent packets are just freed back to the owning 4322 * mempool. The function returns the number of packets actually sent i.e. 4323 * 0 if no buffer flush occurred, otherwise the number of packets successfully 4324 * flushed 4325 * 4326 * @param port_id 4327 * The port identifier of the Ethernet device. 4328 * @param queue_id 4329 * The index of the transmit queue through which output packets must be 4330 * sent. 4331 * The value must be in the range [0, nb_tx_queue - 1] previously supplied 4332 * to rte_eth_dev_configure(). 4333 * @param buffer 4334 * Buffer used to collect packets to be sent. 4335 * @param tx_pkt 4336 * Pointer to the packet mbuf to be sent. 4337 * @return 4338 * 0 = packet has been buffered for later transmission 4339 * N > 0 = packet has been buffered, and the buffer was subsequently flushed, 4340 * causing N packets to be sent, and the error callback to be called for 4341 * the rest. 4342 */ 4343 static __rte_always_inline uint16_t 4344 rte_eth_tx_buffer(uint16_t port_id, uint16_t queue_id, 4345 struct rte_eth_dev_tx_buffer *buffer, struct rte_mbuf *tx_pkt) 4346 { 4347 buffer->pkts[buffer->length++] = tx_pkt; 4348 if (buffer->length < buffer->size) 4349 return 0; 4350 4351 return rte_eth_tx_buffer_flush(port_id, queue_id, buffer); 4352 } 4353 4354 #ifdef __cplusplus 4355 } 4356 #endif 4357 4358 #endif /* _RTE_ETHDEV_H_ */ 4359