From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 0442B1B1C4; Tue, 9 Jan 2018 17:23:52 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga004.fm.intel.com ([10.253.24.48]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 09 Jan 2018 08:23:51 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,336,1511856000"; d="scan'208";a="19583862" Received: from silpixa00372839.ir.intel.com (HELO silpixa00372839.ger.corp.intel.com) ([10.237.222.154]) by fmsmga004.fm.intel.com with ESMTP; 09 Jan 2018 08:23:48 -0800 From: Ferruh Yigit To: Ferruh Yigit , Thomas Monjalon Cc: dev@dpdk.org, stable@dpdk.org, declan.doherty@intel.com, Boris Pismenny , Aviad Yehezkel , Radu Nicolau Date: Tue, 9 Jan 2018 16:23:15 +0000 Message-Id: <20180109162317.18183-4-ferruh.yigit@intel.com> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180109162317.18183-1-ferruh.yigit@intel.com> References: <20171201022957.64329-1-ferruh.yigit@intel.com> <20180109162317.18183-1-ferruh.yigit@intel.com> Subject: [dpdk-dev] [PATCH v2 4/6] ethdev: reorder inline functions X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 09 Jan 2018 16:23:54 -0000 Move all inline function to the end of the ethdev.h header file and move the ethdev_core.h just before inline functions. Since inline functions need data structures in ethdev_core.h, this reorder is to group them and make it clear where put further inline functions. Signed-off-by: Ferruh Yigit --- lib/librte_ether/rte_ethdev.h | 2688 +++++++++++++++++++++-------------------- 1 file changed, 1345 insertions(+), 1343 deletions(-) diff --git a/lib/librte_ether/rte_ethdev.h b/lib/librte_ether/rte_ethdev.h index 7cf177fb2..fc7ce29bf 100644 --- a/lib/librte_ether/rte_ethdev.h +++ b/lib/librte_ether/rte_ethdev.h @@ -1189,6 +1189,8 @@ typedef uint16_t (*rte_rx_callback_fn)(uint16_t port, uint16_t queue, typedef uint16_t (*rte_tx_callback_fn)(uint16_t port, uint16_t queue, struct rte_mbuf *pkts[], uint16_t nb_pkts, void *user_param); +struct rte_eth_rxtx_callback; + /** * A set of values to describe the possible states of an eth device. */ @@ -1211,8 +1213,6 @@ struct rte_eth_dev_sriov { #define RTE_ETH_NAME_MAX_LEN RTE_DEV_NAME_MAX_LEN -#include - /** Device supports link state interrupt */ #define RTE_ETH_DEV_INTR_LSC 0x0002 /** Device is a bonded slave */ @@ -2131,1768 +2131,1770 @@ int rte_eth_dev_get_vlan_offload(uint16_t port_id); */ int rte_eth_dev_set_vlan_pvid(uint16_t port_id, uint16_t pvid, int on); +typedef void (*buffer_tx_error_fn)(struct rte_mbuf **unsent, uint16_t count, + void *userdata); + /** + * Structure used to buffer packets for future TX + * Used by APIs rte_eth_tx_buffer and rte_eth_tx_buffer_flush + */ +struct rte_eth_dev_tx_buffer { + buffer_tx_error_fn error_callback; + void *error_userdata; + uint16_t size; /**< Size of buffer for buffered tx */ + uint16_t length; /**< Number of packets in the array */ + struct rte_mbuf *pkts[]; + /**< Pending packets to be sent on explicit flush or when full */ +}; + +/** + * Calculate the size of the tx buffer. * - * Retrieve a burst of input packets from a receive queue of an Ethernet - * device. The retrieved packets are stored in *rte_mbuf* structures whose - * pointers are supplied in the *rx_pkts* array. - * - * The rte_eth_rx_burst() function loops, parsing the RX ring of the - * receive queue, up to *nb_pkts* packets, and for each completed RX - * descriptor in the ring, it performs the following operations: + * @param sz + * Number of stored packets. + */ +#define RTE_ETH_TX_BUFFER_SIZE(sz) \ + (sizeof(struct rte_eth_dev_tx_buffer) + (sz) * sizeof(struct rte_mbuf *)) + +/** + * Initialize default values for buffered transmitting * - * - Initialize the *rte_mbuf* data structure associated with the - * RX descriptor according to the information provided by the NIC into - * that RX descriptor. + * @param buffer + * Tx buffer to be initialized. + * @param size + * Buffer size + * @return + * 0 if no error + */ +int +rte_eth_tx_buffer_init(struct rte_eth_dev_tx_buffer *buffer, uint16_t size); + +/** + * Configure a callback for buffered packets which cannot be sent * - * - Store the *rte_mbuf* data structure into the next entry of the - * *rx_pkts* array. + * Register a specific callback to be called when an attempt is made to send + * all packets buffered on an ethernet port, but not all packets can + * successfully be sent. The callback registered here will be called only + * from calls to rte_eth_tx_buffer() and rte_eth_tx_buffer_flush() APIs. + * The default callback configured for each queue by default just frees the + * packets back to the calling mempool. If additional behaviour is required, + * for example, to count dropped packets, or to retry transmission of packets + * which cannot be sent, this function should be used to register a suitable + * callback function to implement the desired behaviour. + * The example callback "rte_eth_count_unsent_packet_callback()" is also + * provided as reference. * - * - Replenish the RX descriptor with a new *rte_mbuf* buffer - * allocated from the memory pool associated with the receive queue at - * initialization time. + * @param buffer + * The port identifier of the Ethernet device. + * @param callback + * The function to be used as the callback. + * @param userdata + * Arbitrary parameter to be passed to the callback function + * @return + * 0 on success, or -1 on error with rte_errno set appropriately + */ +int +rte_eth_tx_buffer_set_err_callback(struct rte_eth_dev_tx_buffer *buffer, + buffer_tx_error_fn callback, void *userdata); + +/** + * Callback function for silently dropping unsent buffered packets. * - * When retrieving an input packet that was scattered by the controller - * into multiple receive descriptors, the rte_eth_rx_burst() function - * appends the associated *rte_mbuf* buffers to the first buffer of the - * packet. + * This function can be passed to rte_eth_tx_buffer_set_err_callback() to + * adjust the default behavior when buffered packets cannot be sent. This + * function drops any unsent packets silently and is used by tx buffered + * operations as default behavior. * - * The rte_eth_rx_burst() function returns the number of packets - * actually retrieved, which is the number of *rte_mbuf* data structures - * effectively supplied into the *rx_pkts* array. - * A return value equal to *nb_pkts* indicates that the RX queue contained - * at least *rx_pkts* packets, and this is likely to signify that other - * received packets remain in the input queue. Applications implementing - * a "retrieve as much received packets as possible" policy can check this - * specific case and keep invoking the rte_eth_rx_burst() function until - * a value less than *nb_pkts* is returned. + * NOTE: this function should not be called directly, instead it should be used + * as a callback for packet buffering. * - * This receive method has the following advantages: + * NOTE: when configuring this function as a callback with + * rte_eth_tx_buffer_set_err_callback(), the final, userdata parameter + * should point to an uint64_t value. * - * - It allows a run-to-completion network stack engine to retrieve and - * to immediately process received packets in a fast burst-oriented - * approach, avoiding the overhead of unnecessary intermediate packet - * queue/dequeue operations. + * @param pkts + * The previously buffered packets which could not be sent + * @param unsent + * The number of unsent packets in the pkts array + * @param userdata + * Not used + */ +void +rte_eth_tx_buffer_drop_callback(struct rte_mbuf **pkts, uint16_t unsent, + void *userdata); + +/** + * Callback function for tracking unsent buffered packets. * - * - Conversely, it also allows an asynchronous-oriented processing - * method to retrieve bursts of received packets and to immediately - * queue them for further parallel processing by another logical core, - * for instance. However, instead of having received packets being - * individually queued by the driver, this approach allows the caller - * of the rte_eth_rx_burst() function to queue a burst of retrieved - * packets at a time and therefore dramatically reduce the cost of - * enqueue/dequeue operations per packet. + * This function can be passed to rte_eth_tx_buffer_set_err_callback() to + * adjust the default behavior when buffered packets cannot be sent. This + * function drops any unsent packets, but also updates a user-supplied counter + * to track the overall number of packets dropped. The counter should be an + * uint64_t variable. * - * - It allows the rte_eth_rx_burst() function of the driver to take - * advantage of burst-oriented hardware features (CPU cache, - * prefetch instructions, and so on) to minimize the number of CPU - * cycles per packet. + * NOTE: this function should not be called directly, instead it should be used + * as a callback for packet buffering. * - * To summarize, the proposed receive API enables many - * burst-oriented optimizations in both synchronous and asynchronous - * packet processing environments with no overhead in both cases. + * NOTE: when configuring this function as a callback with + * rte_eth_tx_buffer_set_err_callback(), the final, userdata parameter + * should point to an uint64_t value. * - * The rte_eth_rx_burst() function does not provide any error - * notification to avoid the corresponding overhead. As a hint, the - * upper-level application might check the status of the device link once - * being systematically returned a 0 value for a given number of tries. + * @param pkts + * The previously buffered packets which could not be sent + * @param unsent + * The number of unsent packets in the pkts array + * @param userdata + * Pointer to an uint64_t value, which will be incremented by unsent + */ +void +rte_eth_tx_buffer_count_callback(struct rte_mbuf **pkts, uint16_t unsent, + void *userdata); + +/** + * Request the driver to free mbufs currently cached by the driver. The + * driver will only free the mbuf if it is no longer in use. It is the + * application's responsibity to ensure rte_eth_tx_buffer_flush(..) is + * called if needed. * * @param port_id * The port identifier of the Ethernet device. * @param queue_id - * The index of the receive queue from which to retrieve input packets. - * The value must be in the range [0, nb_rx_queue - 1] previously supplied + * The index of the transmit queue through which output packets must be + * sent. + * The value must be in the range [0, nb_tx_queue - 1] previously supplied * to rte_eth_dev_configure(). - * @param rx_pkts - * The address of an array of pointers to *rte_mbuf* structures that - * must be large enough to store *nb_pkts* pointers in it. - * @param nb_pkts - * The maximum number of packets to retrieve. + * @param free_cnt + * Maximum number of packets to free. Use 0 to indicate all possible packets + * should be freed. Note that a packet may be using multiple mbufs. * @return - * The number of packets actually retrieved, which is the number - * of pointers to *rte_mbuf* structures effectively supplied to the - * *rx_pkts* array. + * Failure: < 0 + * -ENODEV: Invalid interface + * -ENOTSUP: Driver does not support function + * Success: >= 0 + * 0-n: Number of packets freed. More packets may still remain in ring that + * are in use. */ -static inline uint16_t -rte_eth_rx_burst(uint16_t port_id, uint16_t queue_id, - struct rte_mbuf **rx_pkts, const uint16_t nb_pkts) -{ - struct rte_eth_dev *dev = &rte_eth_devices[port_id]; - -#ifdef RTE_LIBRTE_ETHDEV_DEBUG - RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, 0); - RTE_FUNC_PTR_OR_ERR_RET(*dev->rx_pkt_burst, 0); +int +rte_eth_tx_done_cleanup(uint16_t port_id, uint16_t queue_id, uint32_t free_cnt); - if (queue_id >= dev->data->nb_rx_queues) { - RTE_PMD_DEBUG_TRACE("Invalid RX queue_id=%d\n", queue_id); - return 0; - } -#endif - int16_t nb_rx = (*dev->rx_pkt_burst)(dev->data->rx_queues[queue_id], - rx_pkts, nb_pkts); +/** + * The eth device event type for interrupt, and maybe others in the future. + */ +enum rte_eth_event_type { + RTE_ETH_EVENT_UNKNOWN, /**< unknown event type */ + RTE_ETH_EVENT_INTR_LSC, /**< lsc interrupt event */ + RTE_ETH_EVENT_QUEUE_STATE, + /**< queue state event (enabled/disabled) */ + RTE_ETH_EVENT_INTR_RESET, + /**< reset interrupt event, sent to VF on PF reset */ + RTE_ETH_EVENT_VF_MBOX, /**< message from the VF received by PF */ + RTE_ETH_EVENT_MACSEC, /**< MACsec offload related event */ + RTE_ETH_EVENT_INTR_RMV, /**< device removal event */ + RTE_ETH_EVENT_MAX /**< max value of this enum */ +}; -#ifdef RTE_ETHDEV_RXTX_CALLBACKS - struct rte_eth_rxtx_callback *cb = dev->post_rx_burst_cbs[queue_id]; +typedef int (*rte_eth_dev_cb_fn)(uint16_t port_id, + enum rte_eth_event_type event, void *cb_arg, void *ret_param); +/**< user application callback to be registered for interrupts */ - if (unlikely(cb != NULL)) { - do { - nb_rx = cb->fn.rx(port_id, queue_id, rx_pkts, nb_rx, - nb_pkts, cb->param); - cb = cb->next; - } while (cb != NULL); - } -#endif - return nb_rx; -} /** - * Get the number of used descriptors of a rx queue + * Register a callback function for specific port id. * * @param port_id - * The port identifier of the Ethernet device. - * @param queue_id - * The queue id on the specific port. + * Port id. + * @param event + * Event interested. + * @param cb_fn + * User supplied callback function to be called. + * @param cb_arg + * Pointer to the parameters for the registered callback. + * * @return - * The number of used descriptors in the specific queue, or: - * (-EINVAL) if *port_id* or *queue_id* is invalid - * (-ENOTSUP) if the device does not support this function + * - On success, zero. + * - On failure, a negative value. */ -static inline int -rte_eth_rx_queue_count(uint16_t port_id, uint16_t queue_id) -{ - struct rte_eth_dev *dev; - - RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -EINVAL); - dev = &rte_eth_devices[port_id]; - RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_queue_count, -ENOTSUP); - if (queue_id >= dev->data->nb_rx_queues) - return -EINVAL; - - return (*dev->dev_ops->rx_queue_count)(dev, queue_id); -} +int rte_eth_dev_callback_register(uint16_t port_id, + enum rte_eth_event_type event, + rte_eth_dev_cb_fn cb_fn, void *cb_arg); /** - * Check if the DD bit of the specific RX descriptor in the queue has been set + * Unregister a callback function for specific port id. * * @param port_id - * The port identifier of the Ethernet device. - * @param queue_id - * The queue id on the specific port. - * @param offset - * The offset of the descriptor ID from tail. + * Port id. + * @param event + * Event interested. + * @param cb_fn + * User supplied callback function to be called. + * @param cb_arg + * Pointer to the parameters for the registered callback. -1 means to + * remove all for the same callback address and same event. + * * @return - * - (1) if the specific DD bit is set. - * - (0) if the specific DD bit is not set. - * - (-ENODEV) if *port_id* invalid. - * - (-ENOTSUP) if the device does not support this function + * - On success, zero. + * - On failure, a negative value. */ -static inline int -rte_eth_rx_descriptor_done(uint16_t port_id, uint16_t queue_id, uint16_t offset) -{ - struct rte_eth_dev *dev = &rte_eth_devices[port_id]; - RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); - RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_descriptor_done, -ENOTSUP); - return (*dev->dev_ops->rx_descriptor_done)( \ - dev->data->rx_queues[queue_id], offset); -} - -#define RTE_ETH_RX_DESC_AVAIL 0 /**< Desc available for hw. */ -#define RTE_ETH_RX_DESC_DONE 1 /**< Desc done, filled by hw. */ -#define RTE_ETH_RX_DESC_UNAVAIL 2 /**< Desc used by driver or hw. */ +int rte_eth_dev_callback_unregister(uint16_t port_id, + enum rte_eth_event_type event, + rte_eth_dev_cb_fn cb_fn, void *cb_arg); /** - * Check the status of a Rx descriptor in the queue - * - * It should be called in a similar context than the Rx function: - * - on a dataplane core - * - not concurrently on the same queue - * - * Since it's a dataplane function, no check is performed on port_id and - * queue_id. The caller must therefore ensure that the port is enabled - * and the queue is configured and running. + * When there is no rx packet coming in Rx Queue for a long time, we can + * sleep lcore related to RX Queue for power saving, and enable rx interrupt + * to be triggered when Rx packet arrives. * - * Note: accessing to a random descriptor in the ring may trigger cache - * misses and have a performance impact. + * The rte_eth_dev_rx_intr_enable() function enables rx queue + * interrupt on specific rx queue of a port. * * @param port_id - * A valid port identifier of the Ethernet device which. + * The port identifier of the Ethernet device. * @param queue_id - * A valid Rx queue identifier on this port. - * @param offset - * The offset of the descriptor starting from tail (0 is the next - * packet to be received by the driver). - * + * The index of the receive queue from which to retrieve input packets. + * The value must be in the range [0, nb_rx_queue - 1] previously supplied + * to rte_eth_dev_configure(). * @return - * - (RTE_ETH_RX_DESC_AVAIL): Descriptor is available for the hardware to - * receive a packet. - * - (RTE_ETH_RX_DESC_DONE): Descriptor is done, it is filled by hw, but - * not yet processed by the driver (i.e. in the receive queue). - * - (RTE_ETH_RX_DESC_UNAVAIL): Descriptor is unavailable, either hold by - * the driver and not yet returned to hw, or reserved by the hw. - * - (-EINVAL) bad descriptor offset. - * - (-ENOTSUP) if the device does not support this function. - * - (-ENODEV) bad port or queue (only if compiled with debug). + * - (0) if successful. + * - (-ENOTSUP) if underlying hardware OR driver doesn't support + * that operation. + * - (-ENODEV) if *port_id* invalid. */ -static inline int -rte_eth_rx_descriptor_status(uint16_t port_id, uint16_t queue_id, - uint16_t offset) -{ - struct rte_eth_dev *dev; - void *rxq; - -#ifdef RTE_LIBRTE_ETHDEV_DEBUG - RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); -#endif - dev = &rte_eth_devices[port_id]; -#ifdef RTE_LIBRTE_ETHDEV_DEBUG - if (queue_id >= dev->data->nb_rx_queues) - return -ENODEV; -#endif - RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_descriptor_status, -ENOTSUP); - rxq = dev->data->rx_queues[queue_id]; - - return (*dev->dev_ops->rx_descriptor_status)(rxq, offset); -} - -#define RTE_ETH_TX_DESC_FULL 0 /**< Desc filled for hw, waiting xmit. */ -#define RTE_ETH_TX_DESC_DONE 1 /**< Desc done, packet is transmitted. */ -#define RTE_ETH_TX_DESC_UNAVAIL 2 /**< Desc used by driver or hw. */ +int rte_eth_dev_rx_intr_enable(uint16_t port_id, uint16_t queue_id); /** - * Check the status of a Tx descriptor in the queue. - * - * It should be called in a similar context than the Tx function: - * - on a dataplane core - * - not concurrently on the same queue - * - * Since it's a dataplane function, no check is performed on port_id and - * queue_id. The caller must therefore ensure that the port is enabled - * and the queue is configured and running. + * When lcore wakes up from rx interrupt indicating packet coming, disable rx + * interrupt and returns to polling mode. * - * Note: accessing to a random descriptor in the ring may trigger cache - * misses and have a performance impact. + * The rte_eth_dev_rx_intr_disable() function disables rx queue + * interrupt on specific rx queue of a port. * * @param port_id - * A valid port identifier of the Ethernet device which. + * The port identifier of the Ethernet device. * @param queue_id - * A valid Tx queue identifier on this port. - * @param offset - * The offset of the descriptor starting from tail (0 is the place where - * the next packet will be send). - * + * The index of the receive queue from which to retrieve input packets. + * The value must be in the range [0, nb_rx_queue - 1] previously supplied + * to rte_eth_dev_configure(). * @return - * - (RTE_ETH_TX_DESC_FULL) Descriptor is being processed by the hw, i.e. - * in the transmit queue. - * - (RTE_ETH_TX_DESC_DONE) Hardware is done with this descriptor, it can - * be reused by the driver. - * - (RTE_ETH_TX_DESC_UNAVAIL): Descriptor is unavailable, reserved by the - * driver or the hardware. - * - (-EINVAL) bad descriptor offset. - * - (-ENOTSUP) if the device does not support this function. - * - (-ENODEV) bad port or queue (only if compiled with debug). + * - (0) if successful. + * - (-ENOTSUP) if underlying hardware OR driver doesn't support + * that operation. + * - (-ENODEV) if *port_id* invalid. */ -static inline int rte_eth_tx_descriptor_status(uint16_t port_id, - uint16_t queue_id, uint16_t offset) -{ - struct rte_eth_dev *dev; - void *txq; - -#ifdef RTE_LIBRTE_ETHDEV_DEBUG - RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); -#endif - dev = &rte_eth_devices[port_id]; -#ifdef RTE_LIBRTE_ETHDEV_DEBUG - if (queue_id >= dev->data->nb_tx_queues) - return -ENODEV; -#endif - RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->tx_descriptor_status, -ENOTSUP); - txq = dev->data->tx_queues[queue_id]; - - return (*dev->dev_ops->tx_descriptor_status)(txq, offset); -} +int rte_eth_dev_rx_intr_disable(uint16_t port_id, uint16_t queue_id); /** - * Send a burst of output packets on a transmit queue of an Ethernet device. - * - * The rte_eth_tx_burst() function is invoked to transmit output packets - * on the output queue *queue_id* of the Ethernet device designated by its - * *port_id*. - * The *nb_pkts* parameter is the number of packets to send which are - * supplied in the *tx_pkts* array of *rte_mbuf* structures, each of them - * allocated from a pool created with rte_pktmbuf_pool_create(). - * The rte_eth_tx_burst() function loops, sending *nb_pkts* packets, - * up to the number of transmit descriptors available in the TX ring of the - * transmit queue. - * For each packet to send, the rte_eth_tx_burst() function performs - * the following operations: - * - * - Pick up the next available descriptor in the transmit ring. - * - * - Free the network buffer previously sent with that descriptor, if any. - * - * - Initialize the transmit descriptor with the information provided - * in the *rte_mbuf data structure. - * - * In the case of a segmented packet composed of a list of *rte_mbuf* buffers, - * the rte_eth_tx_burst() function uses several transmit descriptors - * of the ring. - * - * The rte_eth_tx_burst() function returns the number of packets it - * actually sent. A return value equal to *nb_pkts* means that all packets - * have been sent, and this is likely to signify that other output packets - * could be immediately transmitted again. Applications that implement a - * "send as many packets to transmit as possible" policy can check this - * specific case and keep invoking the rte_eth_tx_burst() function until - * a value less than *nb_pkts* is returned. - * - * It is the responsibility of the rte_eth_tx_burst() function to - * transparently free the memory buffers of packets previously sent. - * This feature is driven by the *tx_free_thresh* value supplied to the - * rte_eth_dev_configure() function at device configuration time. - * When the number of free TX descriptors drops below this threshold, the - * rte_eth_tx_burst() function must [attempt to] free the *rte_mbuf* buffers - * of those packets whose transmission was effectively completed. + * RX Interrupt control per port. * - * If the PMD is DEV_TX_OFFLOAD_MT_LOCKFREE capable, multiple threads can - * invoke this function concurrently on the same tx queue without SW lock. - * @see rte_eth_dev_info_get, struct rte_eth_txconf::txq_flags + * @param port_id + * The port identifier of the Ethernet device. + * @param epfd + * Epoll instance fd which the intr vector associated to. + * Using RTE_EPOLL_PER_THREAD allows to use per thread epoll instance. + * @param op + * The operation be performed for the vector. + * Operation type of {RTE_INTR_EVENT_ADD, RTE_INTR_EVENT_DEL}. + * @param data + * User raw data. + * @return + * - On success, zero. + * - On failure, a negative value. + */ +int rte_eth_dev_rx_intr_ctl(uint16_t port_id, int epfd, int op, void *data); + +/** + * RX Interrupt control per queue. * * @param port_id * The port identifier of the Ethernet device. * @param queue_id - * The index of the transmit queue through which output packets must be - * sent. - * The value must be in the range [0, nb_tx_queue - 1] previously supplied + * The index of the receive queue from which to retrieve input packets. + * The value must be in the range [0, nb_rx_queue - 1] previously supplied * to rte_eth_dev_configure(). - * @param tx_pkts - * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures - * which contain the output packets. - * @param nb_pkts - * The maximum number of packets to transmit. + * @param epfd + * Epoll instance fd which the intr vector associated to. + * Using RTE_EPOLL_PER_THREAD allows to use per thread epoll instance. + * @param op + * The operation be performed for the vector. + * Operation type of {RTE_INTR_EVENT_ADD, RTE_INTR_EVENT_DEL}. + * @param data + * User raw data. * @return - * The number of output packets actually stored in transmit descriptors of - * the transmit ring. The return value can be less than the value of the - * *tx_pkts* parameter when the transmit ring is full or has been filled up. + * - On success, zero. + * - On failure, a negative value. */ -static inline uint16_t -rte_eth_tx_burst(uint16_t port_id, uint16_t queue_id, - struct rte_mbuf **tx_pkts, uint16_t nb_pkts) -{ - struct rte_eth_dev *dev = &rte_eth_devices[port_id]; - -#ifdef RTE_LIBRTE_ETHDEV_DEBUG - RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, 0); - RTE_FUNC_PTR_OR_ERR_RET(*dev->tx_pkt_burst, 0); - - if (queue_id >= dev->data->nb_tx_queues) { - RTE_PMD_DEBUG_TRACE("Invalid TX queue_id=%d\n", queue_id); - return 0; - } -#endif - -#ifdef RTE_ETHDEV_RXTX_CALLBACKS - struct rte_eth_rxtx_callback *cb = dev->pre_tx_burst_cbs[queue_id]; - - if (unlikely(cb != NULL)) { - do { - nb_pkts = cb->fn.tx(port_id, queue_id, tx_pkts, nb_pkts, - cb->param); - cb = cb->next; - } while (cb != NULL); - } -#endif - - return (*dev->tx_pkt_burst)(dev->data->tx_queues[queue_id], tx_pkts, nb_pkts); -} +int rte_eth_dev_rx_intr_ctl_q(uint16_t port_id, uint16_t queue_id, + int epfd, int op, void *data); /** - * @warning - * @b EXPERIMENTAL: this API may change without prior notice - * - * Process a burst of output packets on a transmit queue of an Ethernet device. - * - * The rte_eth_tx_prepare() function is invoked to prepare output packets to be - * transmitted on the output queue *queue_id* of the Ethernet device designated - * by its *port_id*. - * The *nb_pkts* parameter is the number of packets to be prepared which are - * supplied in the *tx_pkts* array of *rte_mbuf* structures, each of them - * allocated from a pool created with rte_pktmbuf_pool_create(). - * For each packet to send, the rte_eth_tx_prepare() function performs - * the following operations: - * - * - Check if packet meets devices requirements for tx offloads. - * - * - Check limitations about number of segments. - * - * - Check additional requirements when debug is enabled. - * - * - Update and/or reset required checksums when tx offload is set for packet. - * - * Since this function can modify packet data, provided mbufs must be safely - * writable (e.g. modified data cannot be in shared segment). - * - * The rte_eth_tx_prepare() function returns the number of packets ready to be - * sent. A return value equal to *nb_pkts* means that all packets are valid and - * ready to be sent, otherwise stops processing on the first invalid packet and - * leaves the rest packets untouched. - * - * When this functionality is not implemented in the driver, all packets are - * are returned untouched. + * Turn on the LED on the Ethernet device. + * This function turns on the LED on the Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * The value must be a valid port id. - * @param queue_id - * The index of the transmit queue through which output packets must be - * sent. - * The value must be in the range [0, nb_tx_queue - 1] previously supplied - * to rte_eth_dev_configure(). - * @param tx_pkts - * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures - * which contain the output packets. - * @param nb_pkts - * The maximum number of packets to process. * @return - * The number of packets correct and ready to be sent. The return value can be - * less than the value of the *tx_pkts* parameter when some packet doesn't - * meet devices requirements with rte_errno set appropriately: - * - -EINVAL: offload flags are not correctly set - * - -ENOTSUP: the offload feature is not supported by the hardware - * + * - (0) if successful. + * - (-ENOTSUP) if underlying hardware OR driver doesn't support + * that operation. + * - (-ENODEV) if *port_id* invalid. */ +int rte_eth_led_on(uint16_t port_id); -#ifndef RTE_ETHDEV_TX_PREPARE_NOOP - -static inline uint16_t -rte_eth_tx_prepare(uint16_t port_id, uint16_t queue_id, - struct rte_mbuf **tx_pkts, uint16_t nb_pkts) -{ - struct rte_eth_dev *dev; - -#ifdef RTE_LIBRTE_ETHDEV_DEBUG - if (!rte_eth_dev_is_valid_port(port_id)) { - RTE_PMD_DEBUG_TRACE("Invalid TX port_id=%d\n", port_id); - rte_errno = -EINVAL; - return 0; - } -#endif - - dev = &rte_eth_devices[port_id]; - -#ifdef RTE_LIBRTE_ETHDEV_DEBUG - if (queue_id >= dev->data->nb_tx_queues) { - RTE_PMD_DEBUG_TRACE("Invalid TX queue_id=%d\n", queue_id); - rte_errno = -EINVAL; - return 0; - } -#endif - - if (!dev->tx_pkt_prepare) - return nb_pkts; - - return (*dev->tx_pkt_prepare)(dev->data->tx_queues[queue_id], - tx_pkts, nb_pkts); -} - -#else - -/* - * Native NOOP operation for compilation targets which doesn't require any - * preparations steps, and functional NOOP may introduce unnecessary performance - * drop. +/** + * Turn off the LED on the Ethernet device. + * This function turns off the LED on the Ethernet device. * - * Generally this is not a good idea to turn it on globally and didn't should - * be used if behavior of tx_preparation can change. + * @param port_id + * The port identifier of the Ethernet device. + * @return + * - (0) if successful. + * - (-ENOTSUP) if underlying hardware OR driver doesn't support + * that operation. + * - (-ENODEV) if *port_id* invalid. */ - -static inline uint16_t -rte_eth_tx_prepare(__rte_unused uint16_t port_id, - __rte_unused uint16_t queue_id, - __rte_unused struct rte_mbuf **tx_pkts, uint16_t nb_pkts) -{ - return nb_pkts; -} - -#endif - -typedef void (*buffer_tx_error_fn)(struct rte_mbuf **unsent, uint16_t count, - void *userdata); +int rte_eth_led_off(uint16_t port_id); /** - * Structure used to buffer packets for future TX - * Used by APIs rte_eth_tx_buffer and rte_eth_tx_buffer_flush + * Get current status of the Ethernet link flow control for Ethernet device + * + * @param port_id + * The port identifier of the Ethernet device. + * @param fc_conf + * The pointer to the structure where to store the flow control parameters. + * @return + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support flow control. + * - (-ENODEV) if *port_id* invalid. */ -struct rte_eth_dev_tx_buffer { - buffer_tx_error_fn error_callback; - void *error_userdata; - uint16_t size; /**< Size of buffer for buffered tx */ - uint16_t length; /**< Number of packets in the array */ - struct rte_mbuf *pkts[]; - /**< Pending packets to be sent on explicit flush or when full */ -}; +int rte_eth_dev_flow_ctrl_get(uint16_t port_id, + struct rte_eth_fc_conf *fc_conf); /** - * Calculate the size of the tx buffer. + * Configure the Ethernet link flow control for Ethernet device * - * @param sz - * Number of stored packets. + * @param port_id + * The port identifier of the Ethernet device. + * @param fc_conf + * The pointer to the structure of the flow control parameters. + * @return + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support flow control mode. + * - (-ENODEV) if *port_id* invalid. + * - (-EINVAL) if bad parameter + * - (-EIO) if flow control setup failure */ -#define RTE_ETH_TX_BUFFER_SIZE(sz) \ - (sizeof(struct rte_eth_dev_tx_buffer) + (sz) * sizeof(struct rte_mbuf *)) +int rte_eth_dev_flow_ctrl_set(uint16_t port_id, + struct rte_eth_fc_conf *fc_conf); /** - * Initialize default values for buffered transmitting + * Configure the Ethernet priority flow control under DCB environment + * for Ethernet device. * - * @param buffer - * Tx buffer to be initialized. - * @param size - * Buffer size + * @param port_id + * The port identifier of the Ethernet device. + * @param pfc_conf + * The pointer to the structure of the priority flow control parameters. * @return - * 0 if no error + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support priority flow control mode. + * - (-ENODEV) if *port_id* invalid. + * - (-EINVAL) if bad parameter + * - (-EIO) if flow control setup failure */ -int -rte_eth_tx_buffer_init(struct rte_eth_dev_tx_buffer *buffer, uint16_t size); +int rte_eth_dev_priority_flow_ctrl_set(uint16_t port_id, + struct rte_eth_pfc_conf *pfc_conf); /** - * Send any packets queued up for transmission on a port and HW queue - * - * This causes an explicit flush of packets previously buffered via the - * rte_eth_tx_buffer() function. It returns the number of packets successfully - * sent to the NIC, and calls the error callback for any unsent packets. Unless - * explicitly set up otherwise, the default callback simply frees the unsent - * packets back to the owning mempool. + * Add a MAC address to an internal array of addresses used to enable whitelist + * filtering to accept packets only if the destination MAC address matches. * - * @param port_id + * @param port * The port identifier of the Ethernet device. - * @param queue_id - * The index of the transmit queue through which output packets must be - * sent. - * The value must be in the range [0, nb_tx_queue - 1] previously supplied - * to rte_eth_dev_configure(). - * @param buffer - * Buffer of packets to be transmit. + * @param mac_addr + * The MAC address to add. + * @param pool + * VMDq pool index to associate address with (if VMDq is enabled). If VMDq is + * not enabled, this should be set to 0. * @return - * The number of packets successfully sent to the Ethernet device. The error - * callback is called for any packets which could not be sent. + * - (0) if successfully added or *mac_addr" was already added. + * - (-ENOTSUP) if hardware doesn't support this feature. + * - (-ENODEV) if *port* is invalid. + * - (-ENOSPC) if no more MAC addresses can be added. + * - (-EINVAL) if MAC address is invalid. */ -static inline uint16_t -rte_eth_tx_buffer_flush(uint16_t port_id, uint16_t queue_id, - struct rte_eth_dev_tx_buffer *buffer) -{ - uint16_t sent; - uint16_t to_send = buffer->length; - - if (to_send == 0) - return 0; - - sent = rte_eth_tx_burst(port_id, queue_id, buffer->pkts, to_send); - - buffer->length = 0; - - /* All packets sent, or to be dealt with by callback below */ - if (unlikely(sent != to_send)) - buffer->error_callback(&buffer->pkts[sent], to_send - sent, - buffer->error_userdata); - - return sent; -} +int rte_eth_dev_mac_addr_add(uint16_t port, struct ether_addr *mac_addr, + uint32_t pool); /** - * Buffer a single packet for future transmission on a port and queue - * - * This function takes a single mbuf/packet and buffers it for later - * transmission on the particular port and queue specified. Once the buffer is - * full of packets, an attempt will be made to transmit all the buffered - * packets. In case of error, where not all packets can be transmitted, a - * callback is called with the unsent packets as a parameter. If no callback - * is explicitly set up, the unsent packets are just freed back to the owning - * mempool. The function returns the number of packets actually sent i.e. - * 0 if no buffer flush occurred, otherwise the number of packets successfully - * flushed + * Remove a MAC address from the internal array of addresses. * - * @param port_id + * @param port * The port identifier of the Ethernet device. - * @param queue_id - * The index of the transmit queue through which output packets must be - * sent. - * The value must be in the range [0, nb_tx_queue - 1] previously supplied - * to rte_eth_dev_configure(). - * @param buffer - * Buffer used to collect packets to be sent. - * @param tx_pkt - * Pointer to the packet mbuf to be sent. + * @param mac_addr + * MAC address to remove. * @return - * 0 = packet has been buffered for later transmission - * N > 0 = packet has been buffered, and the buffer was subsequently flushed, - * causing N packets to be sent, and the error callback to be called for - * the rest. + * - (0) if successful, or *mac_addr* didn't exist. + * - (-ENOTSUP) if hardware doesn't support. + * - (-ENODEV) if *port* invalid. + * - (-EADDRINUSE) if attempting to remove the default MAC address */ -static __rte_always_inline uint16_t -rte_eth_tx_buffer(uint16_t port_id, uint16_t queue_id, - struct rte_eth_dev_tx_buffer *buffer, struct rte_mbuf *tx_pkt) -{ - buffer->pkts[buffer->length++] = tx_pkt; - if (buffer->length < buffer->size) - return 0; - - return rte_eth_tx_buffer_flush(port_id, queue_id, buffer); -} +int rte_eth_dev_mac_addr_remove(uint16_t port, struct ether_addr *mac_addr); /** - * Configure a callback for buffered packets which cannot be sent - * - * Register a specific callback to be called when an attempt is made to send - * all packets buffered on an ethernet port, but not all packets can - * successfully be sent. The callback registered here will be called only - * from calls to rte_eth_tx_buffer() and rte_eth_tx_buffer_flush() APIs. - * The default callback configured for each queue by default just frees the - * packets back to the calling mempool. If additional behaviour is required, - * for example, to count dropped packets, or to retry transmission of packets - * which cannot be sent, this function should be used to register a suitable - * callback function to implement the desired behaviour. - * The example callback "rte_eth_count_unsent_packet_callback()" is also - * provided as reference. + * Set the default MAC address. * - * @param buffer + * @param port * The port identifier of the Ethernet device. - * @param callback - * The function to be used as the callback. - * @param userdata - * Arbitrary parameter to be passed to the callback function + * @param mac_addr + * New default MAC address. * @return - * 0 on success, or -1 on error with rte_errno set appropriately + * - (0) if successful, or *mac_addr* didn't exist. + * - (-ENOTSUP) if hardware doesn't support. + * - (-ENODEV) if *port* invalid. + * - (-EINVAL) if MAC address is invalid. */ -int -rte_eth_tx_buffer_set_err_callback(struct rte_eth_dev_tx_buffer *buffer, - buffer_tx_error_fn callback, void *userdata); +int rte_eth_dev_default_mac_addr_set(uint16_t port, + struct ether_addr *mac_addr); /** - * Callback function for silently dropping unsent buffered packets. + * Update Redirection Table(RETA) of Receive Side Scaling of Ethernet device. * - * This function can be passed to rte_eth_tx_buffer_set_err_callback() to - * adjust the default behavior when buffered packets cannot be sent. This - * function drops any unsent packets silently and is used by tx buffered - * operations as default behavior. + * @param port + * The port identifier of the Ethernet device. + * @param reta_conf + * RETA to update. + * @param reta_size + * Redirection table size. The table size can be queried by + * rte_eth_dev_info_get(). + * @return + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support. + * - (-EINVAL) if bad parameter. + */ +int rte_eth_dev_rss_reta_update(uint16_t port, + struct rte_eth_rss_reta_entry64 *reta_conf, + uint16_t reta_size); + + /** + * Query Redirection Table(RETA) of Receive Side Scaling of Ethernet device. * - * NOTE: this function should not be called directly, instead it should be used - * as a callback for packet buffering. + * @param port + * The port identifier of the Ethernet device. + * @param reta_conf + * RETA to query. + * @param reta_size + * Redirection table size. The table size can be queried by + * rte_eth_dev_info_get(). + * @return + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support. + * - (-EINVAL) if bad parameter. + */ +int rte_eth_dev_rss_reta_query(uint16_t port, + struct rte_eth_rss_reta_entry64 *reta_conf, + uint16_t reta_size); + + /** + * Updates unicast hash table for receiving packet with the given destination + * MAC address, and the packet is routed to all VFs for which the RX mode is + * accept packets that match the unicast hash table. * - * NOTE: when configuring this function as a callback with - * rte_eth_tx_buffer_set_err_callback(), the final, userdata parameter - * should point to an uint64_t value. + * @param port + * The port identifier of the Ethernet device. + * @param addr + * Unicast MAC address. + * @param on + * 1 - Set an unicast hash bit for receiving packets with the MAC address. + * 0 - Clear an unicast hash bit. + * @return + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support. + * - (-ENODEV) if *port_id* invalid. + * - (-EINVAL) if bad parameter. + */ +int rte_eth_dev_uc_hash_table_set(uint16_t port, struct ether_addr *addr, + uint8_t on); + + /** + * Updates all unicast hash bitmaps for receiving packet with any Unicast + * Ethernet MAC addresses,the packet is routed to all VFs for which the RX + * mode is accept packets that match the unicast hash table. * - * @param pkts - * The previously buffered packets which could not be sent - * @param unsent - * The number of unsent packets in the pkts array - * @param userdata - * Not used + * @param port + * The port identifier of the Ethernet device. + * @param on + * 1 - Set all unicast hash bitmaps for receiving all the Ethernet + * MAC addresses + * 0 - Clear all unicast hash bitmaps + * @return + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support. + * - (-ENODEV) if *port_id* invalid. + * - (-EINVAL) if bad parameter. */ -void -rte_eth_tx_buffer_drop_callback(struct rte_mbuf **pkts, uint16_t unsent, - void *userdata); +int rte_eth_dev_uc_all_hash_table_set(uint16_t port, uint8_t on); /** - * Callback function for tracking unsent buffered packets. - * - * This function can be passed to rte_eth_tx_buffer_set_err_callback() to - * adjust the default behavior when buffered packets cannot be sent. This - * function drops any unsent packets, but also updates a user-supplied counter - * to track the overall number of packets dropped. The counter should be an - * uint64_t variable. - * - * NOTE: this function should not be called directly, instead it should be used - * as a callback for packet buffering. + * Set a traffic mirroring rule on an Ethernet device * - * NOTE: when configuring this function as a callback with - * rte_eth_tx_buffer_set_err_callback(), the final, userdata parameter - * should point to an uint64_t value. + * @param port_id + * The port identifier of the Ethernet device. + * @param mirror_conf + * The pointer to the traffic mirroring structure describing the mirroring rule. + * The *rte_eth_vm_mirror_conf* structure includes the type of mirroring rule, + * destination pool and the value of rule if enable vlan or pool mirroring. * - * @param pkts - * The previously buffered packets which could not be sent - * @param unsent - * The number of unsent packets in the pkts array - * @param userdata - * Pointer to an uint64_t value, which will be incremented by unsent + * @param rule_id + * The index of traffic mirroring rule, we support four separated rules. + * @param on + * 1 - Enable a mirroring rule. + * 0 - Disable a mirroring rule. + * @return + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support this feature. + * - (-ENODEV) if *port_id* invalid. + * - (-EINVAL) if the mr_conf information is not correct. */ -void -rte_eth_tx_buffer_count_callback(struct rte_mbuf **pkts, uint16_t unsent, - void *userdata); +int rte_eth_mirror_rule_set(uint16_t port_id, + struct rte_eth_mirror_conf *mirror_conf, + uint8_t rule_id, + uint8_t on); /** - * Request the driver to free mbufs currently cached by the driver. The - * driver will only free the mbuf if it is no longer in use. It is the - * application's responsibity to ensure rte_eth_tx_buffer_flush(..) is - * called if needed. + * Reset a traffic mirroring rule on an Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_id - * The index of the transmit queue through which output packets must be - * sent. - * The value must be in the range [0, nb_tx_queue - 1] previously supplied - * to rte_eth_dev_configure(). - * @param free_cnt - * Maximum number of packets to free. Use 0 to indicate all possible packets - * should be freed. Note that a packet may be using multiple mbufs. + * @param rule_id + * The index of traffic mirroring rule, we support four separated rules. * @return - * Failure: < 0 - * -ENODEV: Invalid interface - * -ENOTSUP: Driver does not support function - * Success: >= 0 - * 0-n: Number of packets freed. More packets may still remain in ring that - * are in use. + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support this feature. + * - (-ENODEV) if *port_id* invalid. + * - (-EINVAL) if bad parameter. */ -int -rte_eth_tx_done_cleanup(uint16_t port_id, uint16_t queue_id, uint32_t free_cnt); +int rte_eth_mirror_rule_reset(uint16_t port_id, + uint8_t rule_id); /** - * The eth device event type for interrupt, and maybe others in the future. - */ -enum rte_eth_event_type { - RTE_ETH_EVENT_UNKNOWN, /**< unknown event type */ - RTE_ETH_EVENT_INTR_LSC, /**< lsc interrupt event */ - RTE_ETH_EVENT_QUEUE_STATE, - /**< queue state event (enabled/disabled) */ - RTE_ETH_EVENT_INTR_RESET, - /**< reset interrupt event, sent to VF on PF reset */ - RTE_ETH_EVENT_VF_MBOX, /**< message from the VF received by PF */ - RTE_ETH_EVENT_MACSEC, /**< MACsec offload related event */ - RTE_ETH_EVENT_INTR_RMV, /**< device removal event */ - RTE_ETH_EVENT_MAX /**< max value of this enum */ -}; - -typedef int (*rte_eth_dev_cb_fn)(uint16_t port_id, - enum rte_eth_event_type event, void *cb_arg, void *ret_param); -/**< user application callback to be registered for interrupts */ - - - -/** - * Register a callback function for specific port id. - * - * @param port_id - * Port id. - * @param event - * Event interested. - * @param cb_fn - * User supplied callback function to be called. - * @param cb_arg - * Pointer to the parameters for the registered callback. - * - * @return - * - On success, zero. - * - On failure, a negative value. - */ -int rte_eth_dev_callback_register(uint16_t port_id, - enum rte_eth_event_type event, - rte_eth_dev_cb_fn cb_fn, void *cb_arg); - -/** - * Unregister a callback function for specific port id. + * Set the rate limitation for a queue on an Ethernet device. * * @param port_id - * Port id. - * @param event - * Event interested. - * @param cb_fn - * User supplied callback function to be called. - * @param cb_arg - * Pointer to the parameters for the registered callback. -1 means to - * remove all for the same callback address and same event. - * + * The port identifier of the Ethernet device. + * @param queue_idx + * The queue id. + * @param tx_rate + * The tx rate in Mbps. Allocated from the total port link speed. * @return - * - On success, zero. - * - On failure, a negative value. + * - (0) if successful. + * - (-ENOTSUP) if hardware doesn't support this feature. + * - (-ENODEV) if *port_id* invalid. + * - (-EINVAL) if bad parameter. */ -int rte_eth_dev_callback_unregister(uint16_t port_id, - enum rte_eth_event_type event, - rte_eth_dev_cb_fn cb_fn, void *cb_arg); +int rte_eth_set_queue_rate_limit(uint16_t port_id, uint16_t queue_idx, + uint16_t tx_rate); -/** - * When there is no rx packet coming in Rx Queue for a long time, we can - * sleep lcore related to RX Queue for power saving, and enable rx interrupt - * to be triggered when Rx packet arrives. - * - * The rte_eth_dev_rx_intr_enable() function enables rx queue - * interrupt on specific rx queue of a port. + /** + * Configuration of Receive Side Scaling hash computation of Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_id - * The index of the receive queue from which to retrieve input packets. - * The value must be in the range [0, nb_rx_queue - 1] previously supplied - * to rte_eth_dev_configure(). + * @param rss_conf + * The new configuration to use for RSS hash computation on the port. * @return * - (0) if successful. - * - (-ENOTSUP) if underlying hardware OR driver doesn't support - * that operation. - * - (-ENODEV) if *port_id* invalid. + * - (-ENODEV) if port identifier is invalid. + * - (-ENOTSUP) if hardware doesn't support. + * - (-EINVAL) if bad parameter. */ -int rte_eth_dev_rx_intr_enable(uint16_t port_id, uint16_t queue_id); +int rte_eth_dev_rss_hash_update(uint16_t port_id, + struct rte_eth_rss_conf *rss_conf); -/** - * When lcore wakes up from rx interrupt indicating packet coming, disable rx - * interrupt and returns to polling mode. - * - * The rte_eth_dev_rx_intr_disable() function disables rx queue - * interrupt on specific rx queue of a port. + /** + * Retrieve current configuration of Receive Side Scaling hash computation + * of Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_id - * The index of the receive queue from which to retrieve input packets. - * The value must be in the range [0, nb_rx_queue - 1] previously supplied - * to rte_eth_dev_configure(). + * @param rss_conf + * Where to store the current RSS hash configuration of the Ethernet device. * @return * - (0) if successful. - * - (-ENOTSUP) if underlying hardware OR driver doesn't support - * that operation. - * - (-ENODEV) if *port_id* invalid. + * - (-ENODEV) if port identifier is invalid. + * - (-ENOTSUP) if hardware doesn't support RSS. */ -int rte_eth_dev_rx_intr_disable(uint16_t port_id, uint16_t queue_id); +int +rte_eth_dev_rss_hash_conf_get(uint16_t port_id, + struct rte_eth_rss_conf *rss_conf); -/** - * RX Interrupt control per port. + /** + * Add UDP tunneling port for a specific type of tunnel. + * The packets with this UDP port will be identified as this type of tunnel. + * Before enabling any offloading function for a tunnel, users can call this API + * to change or add more UDP port for the tunnel. So the offloading function + * can take effect on the packets with the specific UDP port. * * @param port_id * The port identifier of the Ethernet device. - * @param epfd - * Epoll instance fd which the intr vector associated to. - * Using RTE_EPOLL_PER_THREAD allows to use per thread epoll instance. - * @param op - * The operation be performed for the vector. - * Operation type of {RTE_INTR_EVENT_ADD, RTE_INTR_EVENT_DEL}. - * @param data - * User raw data. + * @param tunnel_udp + * UDP tunneling configuration. + * * @return - * - On success, zero. - * - On failure, a negative value. + * - (0) if successful. + * - (-ENODEV) if port identifier is invalid. + * - (-ENOTSUP) if hardware doesn't support tunnel type. */ -int rte_eth_dev_rx_intr_ctl(uint16_t port_id, int epfd, int op, void *data); +int +rte_eth_dev_udp_tunnel_port_add(uint16_t port_id, + struct rte_eth_udp_tunnel *tunnel_udp); -/** - * RX Interrupt control per queue. + /** + * Delete UDP tunneling port a specific type of tunnel. + * The packets with this UDP port will not be identified as this type of tunnel + * any more. + * Before enabling any offloading function for a tunnel, users can call this API + * to delete a UDP port for the tunnel. So the offloading function will not take + * effect on the packets with the specific UDP port. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_id - * The index of the receive queue from which to retrieve input packets. - * The value must be in the range [0, nb_rx_queue - 1] previously supplied - * to rte_eth_dev_configure(). - * @param epfd - * Epoll instance fd which the intr vector associated to. - * Using RTE_EPOLL_PER_THREAD allows to use per thread epoll instance. - * @param op - * The operation be performed for the vector. - * Operation type of {RTE_INTR_EVENT_ADD, RTE_INTR_EVENT_DEL}. - * @param data - * User raw data. + * @param tunnel_udp + * UDP tunneling configuration. + * * @return - * - On success, zero. - * - On failure, a negative value. + * - (0) if successful. + * - (-ENODEV) if port identifier is invalid. + * - (-ENOTSUP) if hardware doesn't support tunnel type. */ -int rte_eth_dev_rx_intr_ctl_q(uint16_t port_id, uint16_t queue_id, - int epfd, int op, void *data); +int +rte_eth_dev_udp_tunnel_port_delete(uint16_t port_id, + struct rte_eth_udp_tunnel *tunnel_udp); /** - * Turn on the LED on the Ethernet device. - * This function turns on the LED on the Ethernet device. + * Check whether the filter type is supported on an Ethernet device. + * All the supported filter types are defined in 'rte_eth_ctrl.h'. * * @param port_id * The port identifier of the Ethernet device. + * @param filter_type + * Filter type. * @return * - (0) if successful. - * - (-ENOTSUP) if underlying hardware OR driver doesn't support - * that operation. + * - (-ENOTSUP) if hardware doesn't support this filter type. * - (-ENODEV) if *port_id* invalid. */ -int rte_eth_led_on(uint16_t port_id); +int rte_eth_dev_filter_supported(uint16_t port_id, + enum rte_filter_type filter_type); /** - * Turn off the LED on the Ethernet device. - * This function turns off the LED on the Ethernet device. + * Take operations to assigned filter type on an Ethernet device. + * All the supported operations and filter types are defined in 'rte_eth_ctrl.h'. * * @param port_id * The port identifier of the Ethernet device. + * @param filter_type + * Filter type. + * @param filter_op + * Type of operation. + * @param arg + * A pointer to arguments defined specifically for the operation. * @return * - (0) if successful. - * - (-ENOTSUP) if underlying hardware OR driver doesn't support - * that operation. + * - (-ENOTSUP) if hardware doesn't support. * - (-ENODEV) if *port_id* invalid. + * - others depends on the specific operations implementation. */ -int rte_eth_led_off(uint16_t port_id); +int rte_eth_dev_filter_ctrl(uint16_t port_id, enum rte_filter_type filter_type, + enum rte_filter_op filter_op, void *arg); /** - * Get current status of the Ethernet link flow control for Ethernet device + * Get DCB information on an Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param fc_conf - * The pointer to the structure where to store the flow control parameters. + * @param dcb_info + * dcb information. * @return * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support flow control. - * - (-ENODEV) if *port_id* invalid. + * - (-ENODEV) if port identifier is invalid. + * - (-ENOTSUP) if hardware doesn't support. */ -int rte_eth_dev_flow_ctrl_get(uint16_t port_id, - struct rte_eth_fc_conf *fc_conf); +int rte_eth_dev_get_dcb_info(uint16_t port_id, + struct rte_eth_dcb_info *dcb_info); /** - * Configure the Ethernet link flow control for Ethernet device + * Add a callback to be called on packet RX on a given port and queue. + * + * This API configures a function to be called for each burst of + * packets received on a given NIC port queue. The return value is a pointer + * that can be used to later remove the callback using + * rte_eth_remove_rx_callback(). + * + * Multiple functions are called in the order that they are added. * * @param port_id * The port identifier of the Ethernet device. - * @param fc_conf - * The pointer to the structure of the flow control parameters. + * @param queue_id + * The queue on the Ethernet device on which the callback is to be added. + * @param fn + * The callback function + * @param user_param + * A generic pointer parameter which will be passed to each invocation of the + * callback function on this port and queue. + * * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support flow control mode. - * - (-ENODEV) if *port_id* invalid. - * - (-EINVAL) if bad parameter - * - (-EIO) if flow control setup failure + * NULL on error. + * On success, a pointer value which can later be used to remove the callback. */ -int rte_eth_dev_flow_ctrl_set(uint16_t port_id, - struct rte_eth_fc_conf *fc_conf); +void *rte_eth_add_rx_callback(uint16_t port_id, uint16_t queue_id, + rte_rx_callback_fn fn, void *user_param); /** - * Configure the Ethernet priority flow control under DCB environment - * for Ethernet device. + * Add a callback that must be called first on packet RX on a given port + * and queue. + * + * This API configures a first function to be called for each burst of + * packets received on a given NIC port queue. The return value is a pointer + * that can be used to later remove the callback using + * rte_eth_remove_rx_callback(). + * + * Multiple functions are called in the order that they are added. + * + * @param port_id + * The port identifier of the Ethernet device. + * @param queue_id + * The queue on the Ethernet device on which the callback is to be added. + * @param fn + * The callback function + * @param user_param + * A generic pointer parameter which will be passed to each invocation of the + * callback function on this port and queue. * - * @param port_id - * The port identifier of the Ethernet device. - * @param pfc_conf - * The pointer to the structure of the priority flow control parameters. * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support priority flow control mode. - * - (-ENODEV) if *port_id* invalid. - * - (-EINVAL) if bad parameter - * - (-EIO) if flow control setup failure + * NULL on error. + * On success, a pointer value which can later be used to remove the callback. */ -int rte_eth_dev_priority_flow_ctrl_set(uint16_t port_id, - struct rte_eth_pfc_conf *pfc_conf); +void *rte_eth_add_first_rx_callback(uint16_t port_id, uint16_t queue_id, + rte_rx_callback_fn fn, void *user_param); /** - * Add a MAC address to an internal array of addresses used to enable whitelist - * filtering to accept packets only if the destination MAC address matches. + * Add a callback to be called on packet TX on a given port and queue. * - * @param port + * This API configures a function to be called for each burst of + * packets sent on a given NIC port queue. The return value is a pointer + * that can be used to later remove the callback using + * rte_eth_remove_tx_callback(). + * + * Multiple functions are called in the order that they are added. + * + * @param port_id * The port identifier of the Ethernet device. - * @param mac_addr - * The MAC address to add. - * @param pool - * VMDq pool index to associate address with (if VMDq is enabled). If VMDq is - * not enabled, this should be set to 0. + * @param queue_id + * The queue on the Ethernet device on which the callback is to be added. + * @param fn + * The callback function + * @param user_param + * A generic pointer parameter which will be passed to each invocation of the + * callback function on this port and queue. + * * @return - * - (0) if successfully added or *mac_addr" was already added. - * - (-ENOTSUP) if hardware doesn't support this feature. - * - (-ENODEV) if *port* is invalid. - * - (-ENOSPC) if no more MAC addresses can be added. - * - (-EINVAL) if MAC address is invalid. + * NULL on error. + * On success, a pointer value which can later be used to remove the callback. */ -int rte_eth_dev_mac_addr_add(uint16_t port, struct ether_addr *mac_addr, - uint32_t pool); +void *rte_eth_add_tx_callback(uint16_t port_id, uint16_t queue_id, + rte_tx_callback_fn fn, void *user_param); /** - * Remove a MAC address from the internal array of addresses. + * Remove an RX packet callback from a given port and queue. * - * @param port + * This function is used to removed callbacks that were added to a NIC port + * queue using rte_eth_add_rx_callback(). + * + * Note: the callback is removed from the callback list but it isn't freed + * since the it may still be in use. The memory for the callback can be + * subsequently freed back by the application by calling rte_free(): + * + * - Immediately - if the port is stopped, or the user knows that no + * callbacks are in flight e.g. if called from the thread doing RX/TX + * on that queue. + * + * - After a short delay - where the delay is sufficient to allow any + * in-flight callbacks to complete. + * + * @param port_id * The port identifier of the Ethernet device. - * @param mac_addr - * MAC address to remove. + * @param queue_id + * The queue on the Ethernet device from which the callback is to be removed. + * @param user_cb + * User supplied callback created via rte_eth_add_rx_callback(). + * * @return - * - (0) if successful, or *mac_addr* didn't exist. - * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port* invalid. - * - (-EADDRINUSE) if attempting to remove the default MAC address + * - 0: Success. Callback was removed. + * - -ENOTSUP: Callback support is not available. + * - -EINVAL: The port_id or the queue_id is out of range, or the callback + * is NULL or not found for the port/queue. */ -int rte_eth_dev_mac_addr_remove(uint16_t port, struct ether_addr *mac_addr); +int rte_eth_remove_rx_callback(uint16_t port_id, uint16_t queue_id, + struct rte_eth_rxtx_callback *user_cb); /** - * Set the default MAC address. + * Remove a TX packet callback from a given port and queue. * - * @param port + * This function is used to removed callbacks that were added to a NIC port + * queue using rte_eth_add_tx_callback(). + * + * Note: the callback is removed from the callback list but it isn't freed + * since the it may still be in use. The memory for the callback can be + * subsequently freed back by the application by calling rte_free(): + * + * - Immediately - if the port is stopped, or the user knows that no + * callbacks are in flight e.g. if called from the thread doing RX/TX + * on that queue. + * + * - After a short delay - where the delay is sufficient to allow any + * in-flight callbacks to complete. + * + * @param port_id * The port identifier of the Ethernet device. - * @param mac_addr - * New default MAC address. + * @param queue_id + * The queue on the Ethernet device from which the callback is to be removed. + * @param user_cb + * User supplied callback created via rte_eth_add_tx_callback(). + * * @return - * - (0) if successful, or *mac_addr* didn't exist. - * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port* invalid. - * - (-EINVAL) if MAC address is invalid. + * - 0: Success. Callback was removed. + * - -ENOTSUP: Callback support is not available. + * - -EINVAL: The port_id or the queue_id is out of range, or the callback + * is NULL or not found for the port/queue. */ -int rte_eth_dev_default_mac_addr_set(uint16_t port, - struct ether_addr *mac_addr); +int rte_eth_remove_tx_callback(uint16_t port_id, uint16_t queue_id, + struct rte_eth_rxtx_callback *user_cb); /** - * Update Redirection Table(RETA) of Receive Side Scaling of Ethernet device. + * Retrieve information about given port's RX queue. * - * @param port + * @param port_id * The port identifier of the Ethernet device. - * @param reta_conf - * RETA to update. - * @param reta_size - * Redirection table size. The table size can be queried by - * rte_eth_dev_info_get(). + * @param queue_id + * The RX queue on the Ethernet device for which information + * will be retrieved. + * @param qinfo + * A pointer to a structure of type *rte_eth_rxq_info_info* to be filled with + * the information of the Ethernet device. + * * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support. - * - (-EINVAL) if bad parameter. + * - 0: Success + * - -ENOTSUP: routine is not supported by the device PMD. + * - -EINVAL: The port_id or the queue_id is out of range. */ -int rte_eth_dev_rss_reta_update(uint16_t port, - struct rte_eth_rss_reta_entry64 *reta_conf, - uint16_t reta_size); +int rte_eth_rx_queue_info_get(uint16_t port_id, uint16_t queue_id, + struct rte_eth_rxq_info *qinfo); - /** - * Query Redirection Table(RETA) of Receive Side Scaling of Ethernet device. +/** + * Retrieve information about given port's TX queue. * - * @param port + * @param port_id * The port identifier of the Ethernet device. - * @param reta_conf - * RETA to query. - * @param reta_size - * Redirection table size. The table size can be queried by - * rte_eth_dev_info_get(). + * @param queue_id + * The TX queue on the Ethernet device for which information + * will be retrieved. + * @param qinfo + * A pointer to a structure of type *rte_eth_txq_info_info* to be filled with + * the information of the Ethernet device. + * * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support. - * - (-EINVAL) if bad parameter. + * - 0: Success + * - -ENOTSUP: routine is not supported by the device PMD. + * - -EINVAL: The port_id or the queue_id is out of range. */ -int rte_eth_dev_rss_reta_query(uint16_t port, - struct rte_eth_rss_reta_entry64 *reta_conf, - uint16_t reta_size); +int rte_eth_tx_queue_info_get(uint16_t port_id, uint16_t queue_id, + struct rte_eth_txq_info *qinfo); - /** - * Updates unicast hash table for receiving packet with the given destination - * MAC address, and the packet is routed to all VFs for which the RX mode is - * accept packets that match the unicast hash table. +/** + * Retrieve device registers and register attributes (number of registers and + * register size) * - * @param port + * @param port_id * The port identifier of the Ethernet device. - * @param addr - * Unicast MAC address. - * @param on - * 1 - Set an unicast hash bit for receiving packets with the MAC address. - * 0 - Clear an unicast hash bit. + * @param info + * Pointer to rte_dev_reg_info structure to fill in. If info->data is + * NULL the function fills in the width and length fields. If non-NULL + * the registers are put into the buffer pointed at by the data field. * @return * - (0) if successful. * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port_id* invalid. - * - (-EINVAL) if bad parameter. + * - (-ENODEV) if *port_id* invalid. + * - others depends on the specific operations implementation. */ -int rte_eth_dev_uc_hash_table_set(uint16_t port, struct ether_addr *addr, - uint8_t on); +int rte_eth_dev_get_reg_info(uint16_t port_id, struct rte_dev_reg_info *info); - /** - * Updates all unicast hash bitmaps for receiving packet with any Unicast - * Ethernet MAC addresses,the packet is routed to all VFs for which the RX - * mode is accept packets that match the unicast hash table. +/** + * Retrieve size of device EEPROM * - * @param port + * @param port_id * The port identifier of the Ethernet device. - * @param on - * 1 - Set all unicast hash bitmaps for receiving all the Ethernet - * MAC addresses - * 0 - Clear all unicast hash bitmaps * @return - * - (0) if successful. + * - (>=0) EEPROM size if successful. * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port_id* invalid. - * - (-EINVAL) if bad parameter. + * - (-ENODEV) if *port_id* invalid. + * - others depends on the specific operations implementation. */ -int rte_eth_dev_uc_all_hash_table_set(uint16_t port, uint8_t on); +int rte_eth_dev_get_eeprom_length(uint16_t port_id); /** - * Set a traffic mirroring rule on an Ethernet device + * Retrieve EEPROM and EEPROM attribute * * @param port_id * The port identifier of the Ethernet device. - * @param mirror_conf - * The pointer to the traffic mirroring structure describing the mirroring rule. - * The *rte_eth_vm_mirror_conf* structure includes the type of mirroring rule, - * destination pool and the value of rule if enable vlan or pool mirroring. - * - * @param rule_id - * The index of traffic mirroring rule, we support four separated rules. - * @param on - * 1 - Enable a mirroring rule. - * 0 - Disable a mirroring rule. + * @param info + * The template includes buffer for return EEPROM data and + * EEPROM attributes to be filled. * @return * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support this feature. + * - (-ENOTSUP) if hardware doesn't support. * - (-ENODEV) if *port_id* invalid. - * - (-EINVAL) if the mr_conf information is not correct. + * - others depends on the specific operations implementation. */ -int rte_eth_mirror_rule_set(uint16_t port_id, - struct rte_eth_mirror_conf *mirror_conf, - uint8_t rule_id, - uint8_t on); +int rte_eth_dev_get_eeprom(uint16_t port_id, struct rte_dev_eeprom_info *info); /** - * Reset a traffic mirroring rule on an Ethernet device. + * Program EEPROM with provided data * * @param port_id * The port identifier of the Ethernet device. - * @param rule_id - * The index of traffic mirroring rule, we support four separated rules. + * @param info + * The template includes EEPROM data for programming and + * EEPROM attributes to be filled * @return * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support this feature. + * - (-ENOTSUP) if hardware doesn't support. * - (-ENODEV) if *port_id* invalid. - * - (-EINVAL) if bad parameter. + * - others depends on the specific operations implementation. */ -int rte_eth_mirror_rule_reset(uint16_t port_id, - uint8_t rule_id); +int rte_eth_dev_set_eeprom(uint16_t port_id, struct rte_dev_eeprom_info *info); /** - * Set the rate limitation for a queue on an Ethernet device. + * Set the list of multicast addresses to filter on an Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_idx - * The queue id. - * @param tx_rate - * The tx rate in Mbps. Allocated from the total port link speed. + * @param mc_addr_set + * The array of multicast addresses to set. Equal to NULL when the function + * is invoked to flush the set of filtered addresses. + * @param nb_mc_addr + * The number of multicast addresses in the *mc_addr_set* array. Equal to 0 + * when the function is invoked to flush the set of filtered addresses. * @return * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support this feature. * - (-ENODEV) if *port_id* invalid. - * - (-EINVAL) if bad parameter. + * - (-ENOTSUP) if PMD of *port_id* doesn't support multicast filtering. + * - (-ENOSPC) if *port_id* has not enough multicast filtering resources. */ -int rte_eth_set_queue_rate_limit(uint16_t port_id, uint16_t queue_idx, - uint16_t tx_rate); +int rte_eth_dev_set_mc_addr_list(uint16_t port_id, + struct ether_addr *mc_addr_set, + uint32_t nb_mc_addr); - /** - * Configuration of Receive Side Scaling hash computation of Ethernet device. +/** + * Enable IEEE1588/802.1AS timestamping for an Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param rss_conf - * The new configuration to use for RSS hash computation on the port. - * @return - * - (0) if successful. - * - (-ENODEV) if port identifier is invalid. - * - (-ENOTSUP) if hardware doesn't support. - * - (-EINVAL) if bad parameter. - */ -int rte_eth_dev_rss_hash_update(uint16_t port_id, - struct rte_eth_rss_conf *rss_conf); - - /** - * Retrieve current configuration of Receive Side Scaling hash computation - * of Ethernet device. * - * @param port_id - * The port identifier of the Ethernet device. - * @param rss_conf - * Where to store the current RSS hash configuration of the Ethernet device. * @return - * - (0) if successful. - * - (-ENODEV) if port identifier is invalid. - * - (-ENOTSUP) if hardware doesn't support RSS. + * - 0: Success. + * - -ENODEV: The port ID is invalid. + * - -ENOTSUP: The function is not supported by the Ethernet driver. */ -int -rte_eth_dev_rss_hash_conf_get(uint16_t port_id, - struct rte_eth_rss_conf *rss_conf); +int rte_eth_timesync_enable(uint16_t port_id); - /** - * Add UDP tunneling port for a specific type of tunnel. - * The packets with this UDP port will be identified as this type of tunnel. - * Before enabling any offloading function for a tunnel, users can call this API - * to change or add more UDP port for the tunnel. So the offloading function - * can take effect on the packets with the specific UDP port. +/** + * Disable IEEE1588/802.1AS timestamping for an Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param tunnel_udp - * UDP tunneling configuration. * * @return - * - (0) if successful. - * - (-ENODEV) if port identifier is invalid. - * - (-ENOTSUP) if hardware doesn't support tunnel type. + * - 0: Success. + * - -ENODEV: The port ID is invalid. + * - -ENOTSUP: The function is not supported by the Ethernet driver. */ -int -rte_eth_dev_udp_tunnel_port_add(uint16_t port_id, - struct rte_eth_udp_tunnel *tunnel_udp); +int rte_eth_timesync_disable(uint16_t port_id); - /** - * Delete UDP tunneling port a specific type of tunnel. - * The packets with this UDP port will not be identified as this type of tunnel - * any more. - * Before enabling any offloading function for a tunnel, users can call this API - * to delete a UDP port for the tunnel. So the offloading function will not take - * effect on the packets with the specific UDP port. +/** + * Read an IEEE1588/802.1AS RX timestamp from an Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param tunnel_udp - * UDP tunneling configuration. + * @param timestamp + * Pointer to the timestamp struct. + * @param flags + * Device specific flags. Used to pass the RX timesync register index to + * i40e. Unused in igb/ixgbe, pass 0 instead. * * @return - * - (0) if successful. - * - (-ENODEV) if port identifier is invalid. - * - (-ENOTSUP) if hardware doesn't support tunnel type. + * - 0: Success. + * - -EINVAL: No timestamp is available. + * - -ENODEV: The port ID is invalid. + * - -ENOTSUP: The function is not supported by the Ethernet driver. */ -int -rte_eth_dev_udp_tunnel_port_delete(uint16_t port_id, - struct rte_eth_udp_tunnel *tunnel_udp); +int rte_eth_timesync_read_rx_timestamp(uint16_t port_id, + struct timespec *timestamp, uint32_t flags); /** - * Check whether the filter type is supported on an Ethernet device. - * All the supported filter types are defined in 'rte_eth_ctrl.h'. + * Read an IEEE1588/802.1AS TX timestamp from an Ethernet device. * * @param port_id * The port identifier of the Ethernet device. - * @param filter_type - * Filter type. + * @param timestamp + * Pointer to the timestamp struct. + * * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support this filter type. - * - (-ENODEV) if *port_id* invalid. + * - 0: Success. + * - -EINVAL: No timestamp is available. + * - -ENODEV: The port ID is invalid. + * - -ENOTSUP: The function is not supported by the Ethernet driver. */ -int rte_eth_dev_filter_supported(uint16_t port_id, - enum rte_filter_type filter_type); +int rte_eth_timesync_read_tx_timestamp(uint16_t port_id, + struct timespec *timestamp); /** - * Take operations to assigned filter type on an Ethernet device. - * All the supported operations and filter types are defined in 'rte_eth_ctrl.h'. + * Adjust the timesync clock on an Ethernet device. + * + * This is usually used in conjunction with other Ethdev timesync functions to + * synchronize the device time using the IEEE1588/802.1AS protocol. * * @param port_id * The port identifier of the Ethernet device. - * @param filter_type - * Filter type. - * @param filter_op - * Type of operation. - * @param arg - * A pointer to arguments defined specifically for the operation. + * @param delta + * The adjustment in nanoseconds. + * * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port_id* invalid. - * - others depends on the specific operations implementation. + * - 0: Success. + * - -ENODEV: The port ID is invalid. + * - -ENOTSUP: The function is not supported by the Ethernet driver. */ -int rte_eth_dev_filter_ctrl(uint16_t port_id, enum rte_filter_type filter_type, - enum rte_filter_op filter_op, void *arg); +int rte_eth_timesync_adjust_time(uint16_t port_id, int64_t delta); /** - * Get DCB information on an Ethernet device. + * Read the time from the timesync clock on an Ethernet device. + * + * This is usually used in conjunction with other Ethdev timesync functions to + * synchronize the device time using the IEEE1588/802.1AS protocol. * * @param port_id * The port identifier of the Ethernet device. - * @param dcb_info - * dcb information. + * @param time + * Pointer to the timespec struct that holds the time. + * * @return - * - (0) if successful. - * - (-ENODEV) if port identifier is invalid. - * - (-ENOTSUP) if hardware doesn't support. + * - 0: Success. */ -int rte_eth_dev_get_dcb_info(uint16_t port_id, - struct rte_eth_dcb_info *dcb_info); +int rte_eth_timesync_read_time(uint16_t port_id, struct timespec *time); /** - * Add a callback to be called on packet RX on a given port and queue. - * - * This API configures a function to be called for each burst of - * packets received on a given NIC port queue. The return value is a pointer - * that can be used to later remove the callback using - * rte_eth_remove_rx_callback(). + * Set the time of the timesync clock on an Ethernet device. * - * Multiple functions are called in the order that they are added. + * This is usually used in conjunction with other Ethdev timesync functions to + * synchronize the device time using the IEEE1588/802.1AS protocol. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_id - * The queue on the Ethernet device on which the callback is to be added. - * @param fn - * The callback function - * @param user_param - * A generic pointer parameter which will be passed to each invocation of the - * callback function on this port and queue. + * @param time + * Pointer to the timespec struct that holds the time. * * @return - * NULL on error. - * On success, a pointer value which can later be used to remove the callback. + * - 0: Success. + * - -EINVAL: No timestamp is available. + * - -ENODEV: The port ID is invalid. + * - -ENOTSUP: The function is not supported by the Ethernet driver. */ -void *rte_eth_add_rx_callback(uint16_t port_id, uint16_t queue_id, - rte_rx_callback_fn fn, void *user_param); +int rte_eth_timesync_write_time(uint16_t port_id, const struct timespec *time); /** - * Add a callback that must be called first on packet RX on a given port - * and queue. - * - * This API configures a first function to be called for each burst of - * packets received on a given NIC port queue. The return value is a pointer - * that can be used to later remove the callback using - * rte_eth_remove_rx_callback(). - * - * Multiple functions are called in the order that they are added. + * Config l2 tunnel ether type of an Ethernet device for filtering specific + * tunnel packets by ether type. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_id - * The queue on the Ethernet device on which the callback is to be added. - * @param fn - * The callback function - * @param user_param - * A generic pointer parameter which will be passed to each invocation of the - * callback function on this port and queue. + * @param l2_tunnel + * l2 tunnel configuration. * * @return - * NULL on error. - * On success, a pointer value which can later be used to remove the callback. + * - (0) if successful. + * - (-ENODEV) if port identifier is invalid. + * - (-ENOTSUP) if hardware doesn't support tunnel type. */ -void *rte_eth_add_first_rx_callback(uint16_t port_id, uint16_t queue_id, - rte_rx_callback_fn fn, void *user_param); +int +rte_eth_dev_l2_tunnel_eth_type_conf(uint16_t port_id, + struct rte_eth_l2_tunnel_conf *l2_tunnel); /** - * Add a callback to be called on packet TX on a given port and queue. - * - * This API configures a function to be called for each burst of - * packets sent on a given NIC port queue. The return value is a pointer - * that can be used to later remove the callback using - * rte_eth_remove_tx_callback(). - * - * Multiple functions are called in the order that they are added. + * Enable/disable l2 tunnel offload functions. Include, + * 1, The ability of parsing a type of l2 tunnel of an Ethernet device. + * Filtering, forwarding and offloading this type of tunnel packets depend on + * this ability. + * 2, Stripping the l2 tunnel tag. + * 3, Insertion of the l2 tunnel tag. + * 4, Forwarding the packets based on the l2 tunnel tag. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_id - * The queue on the Ethernet device on which the callback is to be added. - * @param fn - * The callback function - * @param user_param - * A generic pointer parameter which will be passed to each invocation of the - * callback function on this port and queue. + * @param l2_tunnel + * l2 tunnel parameters. + * @param mask + * Indicate the offload function. + * @param en + * Enable or disable this function. * * @return - * NULL on error. - * On success, a pointer value which can later be used to remove the callback. + * - (0) if successful. + * - (-ENODEV) if port identifier is invalid. + * - (-ENOTSUP) if hardware doesn't support tunnel type. */ -void *rte_eth_add_tx_callback(uint16_t port_id, uint16_t queue_id, - rte_tx_callback_fn fn, void *user_param); +int +rte_eth_dev_l2_tunnel_offload_set(uint16_t port_id, + struct rte_eth_l2_tunnel_conf *l2_tunnel, + uint32_t mask, + uint8_t en); /** - * Remove an RX packet callback from a given port and queue. - * - * This function is used to removed callbacks that were added to a NIC port - * queue using rte_eth_add_rx_callback(). - * - * Note: the callback is removed from the callback list but it isn't freed - * since the it may still be in use. The memory for the callback can be - * subsequently freed back by the application by calling rte_free(): - * - * - Immediately - if the port is stopped, or the user knows that no - * callbacks are in flight e.g. if called from the thread doing RX/TX - * on that queue. - * - * - After a short delay - where the delay is sufficient to allow any - * in-flight callbacks to complete. +* Get the port id from pci address or device name +* Ex: 0000:2:00.0 or vdev name net_pcap0 +* +* @param name +* pci address or name of the device +* @param port_id +* pointer to port identifier of the device +* @return +* - (0) if successful and port_id is filled. +* - (-ENODEV or -EINVAL) on failure. +*/ +int +rte_eth_dev_get_port_by_name(const char *name, uint16_t *port_id); + +/** +* Get the device name from port id +* +* @param port_id +* pointer to port identifier of the device +* @param name +* pci address or name of the device +* @return +* - (0) if successful. +* - (-EINVAL) on failure. +*/ +int +rte_eth_dev_get_name_by_port(uint16_t port_id, char *name); + +/** + * Check that numbers of Rx and Tx descriptors satisfy descriptors limits from + * the ethernet device information, otherwise adjust them to boundaries. * * @param port_id * The port identifier of the Ethernet device. - * @param queue_id - * The queue on the Ethernet device from which the callback is to be removed. - * @param user_cb - * User supplied callback created via rte_eth_add_rx_callback(). + * @param nb_rx_desc + * A pointer to a uint16_t where the number of receive + * descriptors stored. + * @param nb_tx_desc + * A pointer to a uint16_t where the number of transmit + * descriptors stored. + * @return + * - (0) if successful. + * - (-ENOTSUP, -ENODEV or -EINVAL) on failure. + */ +int rte_eth_dev_adjust_nb_rx_tx_desc(uint16_t port_id, + uint16_t *nb_rx_desc, + uint16_t *nb_tx_desc); + + +/** + * Test if a port supports specific mempool ops. * + * @param port_id + * Port identifier of the Ethernet device. + * @param [in] pool + * The name of the pool operations to test. * @return - * - 0: Success. Callback was removed. - * - -ENOTSUP: Callback support is not available. - * - -EINVAL: The port_id or the queue_id is out of range, or the callback - * is NULL or not found for the port/queue. + * - 0: best mempool ops choice for this port. + * - 1: mempool ops are supported for this port. + * - -ENOTSUP: mempool ops not supported for this port. + * - -ENODEV: Invalid port Identifier. + * - -EINVAL: Pool param is null. */ -int rte_eth_remove_rx_callback(uint16_t port_id, uint16_t queue_id, - struct rte_eth_rxtx_callback *user_cb); +int +rte_eth_dev_pool_ops_supported(uint16_t port_id, const char *pool); + +#include /** - * Remove a TX packet callback from a given port and queue. * - * This function is used to removed callbacks that were added to a NIC port - * queue using rte_eth_add_tx_callback(). + * Retrieve a burst of input packets from a receive queue of an Ethernet + * device. The retrieved packets are stored in *rte_mbuf* structures whose + * pointers are supplied in the *rx_pkts* array. * - * Note: the callback is removed from the callback list but it isn't freed - * since the it may still be in use. The memory for the callback can be - * subsequently freed back by the application by calling rte_free(): + * The rte_eth_rx_burst() function loops, parsing the RX ring of the + * receive queue, up to *nb_pkts* packets, and for each completed RX + * descriptor in the ring, it performs the following operations: * - * - Immediately - if the port is stopped, or the user knows that no - * callbacks are in flight e.g. if called from the thread doing RX/TX - * on that queue. + * - Initialize the *rte_mbuf* data structure associated with the + * RX descriptor according to the information provided by the NIC into + * that RX descriptor. * - * - After a short delay - where the delay is sufficient to allow any - * in-flight callbacks to complete. + * - Store the *rte_mbuf* data structure into the next entry of the + * *rx_pkts* array. * - * @param port_id - * The port identifier of the Ethernet device. - * @param queue_id - * The queue on the Ethernet device from which the callback is to be removed. - * @param user_cb - * User supplied callback created via rte_eth_add_tx_callback(). + * - Replenish the RX descriptor with a new *rte_mbuf* buffer + * allocated from the memory pool associated with the receive queue at + * initialization time. * - * @return - * - 0: Success. Callback was removed. - * - -ENOTSUP: Callback support is not available. - * - -EINVAL: The port_id or the queue_id is out of range, or the callback - * is NULL or not found for the port/queue. - */ -int rte_eth_remove_tx_callback(uint16_t port_id, uint16_t queue_id, - struct rte_eth_rxtx_callback *user_cb); - -/** - * Retrieve information about given port's RX queue. + * When retrieving an input packet that was scattered by the controller + * into multiple receive descriptors, the rte_eth_rx_burst() function + * appends the associated *rte_mbuf* buffers to the first buffer of the + * packet. + * + * The rte_eth_rx_burst() function returns the number of packets + * actually retrieved, which is the number of *rte_mbuf* data structures + * effectively supplied into the *rx_pkts* array. + * A return value equal to *nb_pkts* indicates that the RX queue contained + * at least *rx_pkts* packets, and this is likely to signify that other + * received packets remain in the input queue. Applications implementing + * a "retrieve as much received packets as possible" policy can check this + * specific case and keep invoking the rte_eth_rx_burst() function until + * a value less than *nb_pkts* is returned. + * + * This receive method has the following advantages: + * + * - It allows a run-to-completion network stack engine to retrieve and + * to immediately process received packets in a fast burst-oriented + * approach, avoiding the overhead of unnecessary intermediate packet + * queue/dequeue operations. + * + * - Conversely, it also allows an asynchronous-oriented processing + * method to retrieve bursts of received packets and to immediately + * queue them for further parallel processing by another logical core, + * for instance. However, instead of having received packets being + * individually queued by the driver, this approach allows the caller + * of the rte_eth_rx_burst() function to queue a burst of retrieved + * packets at a time and therefore dramatically reduce the cost of + * enqueue/dequeue operations per packet. + * + * - It allows the rte_eth_rx_burst() function of the driver to take + * advantage of burst-oriented hardware features (CPU cache, + * prefetch instructions, and so on) to minimize the number of CPU + * cycles per packet. + * + * To summarize, the proposed receive API enables many + * burst-oriented optimizations in both synchronous and asynchronous + * packet processing environments with no overhead in both cases. + * + * The rte_eth_rx_burst() function does not provide any error + * notification to avoid the corresponding overhead. As a hint, the + * upper-level application might check the status of the device link once + * being systematically returned a 0 value for a given number of tries. * * @param port_id * The port identifier of the Ethernet device. * @param queue_id - * The RX queue on the Ethernet device for which information - * will be retrieved. - * @param qinfo - * A pointer to a structure of type *rte_eth_rxq_info_info* to be filled with - * the information of the Ethernet device. - * + * The index of the receive queue from which to retrieve input packets. + * The value must be in the range [0, nb_rx_queue - 1] previously supplied + * to rte_eth_dev_configure(). + * @param rx_pkts + * The address of an array of pointers to *rte_mbuf* structures that + * must be large enough to store *nb_pkts* pointers in it. + * @param nb_pkts + * The maximum number of packets to retrieve. * @return - * - 0: Success - * - -ENOTSUP: routine is not supported by the device PMD. - * - -EINVAL: The port_id or the queue_id is out of range. + * The number of packets actually retrieved, which is the number + * of pointers to *rte_mbuf* structures effectively supplied to the + * *rx_pkts* array. */ -int rte_eth_rx_queue_info_get(uint16_t port_id, uint16_t queue_id, - struct rte_eth_rxq_info *qinfo); +static inline uint16_t +rte_eth_rx_burst(uint16_t port_id, uint16_t queue_id, + struct rte_mbuf **rx_pkts, const uint16_t nb_pkts) +{ + struct rte_eth_dev *dev = &rte_eth_devices[port_id]; + +#ifdef RTE_LIBRTE_ETHDEV_DEBUG + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, 0); + RTE_FUNC_PTR_OR_ERR_RET(*dev->rx_pkt_burst, 0); + + if (queue_id >= dev->data->nb_rx_queues) { + RTE_PMD_DEBUG_TRACE("Invalid RX queue_id=%d\n", queue_id); + return 0; + } +#endif + int16_t nb_rx = (*dev->rx_pkt_burst)(dev->data->rx_queues[queue_id], + rx_pkts, nb_pkts); + +#ifdef RTE_ETHDEV_RXTX_CALLBACKS + struct rte_eth_rxtx_callback *cb = dev->post_rx_burst_cbs[queue_id]; + + if (unlikely(cb != NULL)) { + do { + nb_rx = cb->fn.rx(port_id, queue_id, rx_pkts, nb_rx, + nb_pkts, cb->param); + cb = cb->next; + } while (cb != NULL); + } +#endif + + return nb_rx; +} /** - * Retrieve information about given port's TX queue. + * Get the number of used descriptors of a rx queue * * @param port_id - * The port identifier of the Ethernet device. + * The port identifier of the Ethernet device. * @param queue_id - * The TX queue on the Ethernet device for which information - * will be retrieved. - * @param qinfo - * A pointer to a structure of type *rte_eth_txq_info_info* to be filled with - * the information of the Ethernet device. - * + * The queue id on the specific port. * @return - * - 0: Success - * - -ENOTSUP: routine is not supported by the device PMD. - * - -EINVAL: The port_id or the queue_id is out of range. + * The number of used descriptors in the specific queue, or: + * (-EINVAL) if *port_id* or *queue_id* is invalid + * (-ENOTSUP) if the device does not support this function */ -int rte_eth_tx_queue_info_get(uint16_t port_id, uint16_t queue_id, - struct rte_eth_txq_info *qinfo); +static inline int +rte_eth_rx_queue_count(uint16_t port_id, uint16_t queue_id) +{ + struct rte_eth_dev *dev; -/** - * Retrieve device registers and register attributes (number of registers and - * register size) - * - * @param port_id - * The port identifier of the Ethernet device. - * @param info - * Pointer to rte_dev_reg_info structure to fill in. If info->data is - * NULL the function fills in the width and length fields. If non-NULL - * the registers are put into the buffer pointed at by the data field. - * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port_id* invalid. - * - others depends on the specific operations implementation. - */ -int rte_eth_dev_get_reg_info(uint16_t port_id, struct rte_dev_reg_info *info); + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -EINVAL); + dev = &rte_eth_devices[port_id]; + RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_queue_count, -ENOTSUP); + if (queue_id >= dev->data->nb_rx_queues) + return -EINVAL; -/** - * Retrieve size of device EEPROM - * - * @param port_id - * The port identifier of the Ethernet device. - * @return - * - (>=0) EEPROM size if successful. - * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port_id* invalid. - * - others depends on the specific operations implementation. - */ -int rte_eth_dev_get_eeprom_length(uint16_t port_id); + return (*dev->dev_ops->rx_queue_count)(dev, queue_id); +} /** - * Retrieve EEPROM and EEPROM attribute + * Check if the DD bit of the specific RX descriptor in the queue has been set * * @param port_id - * The port identifier of the Ethernet device. - * @param info - * The template includes buffer for return EEPROM data and - * EEPROM attributes to be filled. + * The port identifier of the Ethernet device. + * @param queue_id + * The queue id on the specific port. + * @param offset + * The offset of the descriptor ID from tail. * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port_id* invalid. - * - others depends on the specific operations implementation. + * - (1) if the specific DD bit is set. + * - (0) if the specific DD bit is not set. + * - (-ENODEV) if *port_id* invalid. + * - (-ENOTSUP) if the device does not support this function */ -int rte_eth_dev_get_eeprom(uint16_t port_id, struct rte_dev_eeprom_info *info); +static inline int +rte_eth_rx_descriptor_done(uint16_t port_id, uint16_t queue_id, uint16_t offset) +{ + struct rte_eth_dev *dev = &rte_eth_devices[port_id]; + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); + RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_descriptor_done, -ENOTSUP); + return (*dev->dev_ops->rx_descriptor_done)( \ + dev->data->rx_queues[queue_id], offset); +} -/** - * Program EEPROM with provided data - * - * @param port_id - * The port identifier of the Ethernet device. - * @param info - * The template includes EEPROM data for programming and - * EEPROM attributes to be filled - * @return - * - (0) if successful. - * - (-ENOTSUP) if hardware doesn't support. - * - (-ENODEV) if *port_id* invalid. - * - others depends on the specific operations implementation. - */ -int rte_eth_dev_set_eeprom(uint16_t port_id, struct rte_dev_eeprom_info *info); +#define RTE_ETH_RX_DESC_AVAIL 0 /**< Desc available for hw. */ +#define RTE_ETH_RX_DESC_DONE 1 /**< Desc done, filled by hw. */ +#define RTE_ETH_RX_DESC_UNAVAIL 2 /**< Desc used by driver or hw. */ /** - * Set the list of multicast addresses to filter on an Ethernet device. + * Check the status of a Rx descriptor in the queue * - * @param port_id - * The port identifier of the Ethernet device. - * @param mc_addr_set - * The array of multicast addresses to set. Equal to NULL when the function - * is invoked to flush the set of filtered addresses. - * @param nb_mc_addr - * The number of multicast addresses in the *mc_addr_set* array. Equal to 0 - * when the function is invoked to flush the set of filtered addresses. - * @return - * - (0) if successful. - * - (-ENODEV) if *port_id* invalid. - * - (-ENOTSUP) if PMD of *port_id* doesn't support multicast filtering. - * - (-ENOSPC) if *port_id* has not enough multicast filtering resources. - */ -int rte_eth_dev_set_mc_addr_list(uint16_t port_id, - struct ether_addr *mc_addr_set, - uint32_t nb_mc_addr); - -/** - * Enable IEEE1588/802.1AS timestamping for an Ethernet device. + * It should be called in a similar context than the Rx function: + * - on a dataplane core + * - not concurrently on the same queue * - * @param port_id - * The port identifier of the Ethernet device. + * Since it's a dataplane function, no check is performed on port_id and + * queue_id. The caller must therefore ensure that the port is enabled + * and the queue is configured and running. * - * @return - * - 0: Success. - * - -ENODEV: The port ID is invalid. - * - -ENOTSUP: The function is not supported by the Ethernet driver. - */ -int rte_eth_timesync_enable(uint16_t port_id); - -/** - * Disable IEEE1588/802.1AS timestamping for an Ethernet device. + * Note: accessing to a random descriptor in the ring may trigger cache + * misses and have a performance impact. * * @param port_id - * The port identifier of the Ethernet device. + * A valid port identifier of the Ethernet device which. + * @param queue_id + * A valid Rx queue identifier on this port. + * @param offset + * The offset of the descriptor starting from tail (0 is the next + * packet to be received by the driver). * * @return - * - 0: Success. - * - -ENODEV: The port ID is invalid. - * - -ENOTSUP: The function is not supported by the Ethernet driver. + * - (RTE_ETH_RX_DESC_AVAIL): Descriptor is available for the hardware to + * receive a packet. + * - (RTE_ETH_RX_DESC_DONE): Descriptor is done, it is filled by hw, but + * not yet processed by the driver (i.e. in the receive queue). + * - (RTE_ETH_RX_DESC_UNAVAIL): Descriptor is unavailable, either hold by + * the driver and not yet returned to hw, or reserved by the hw. + * - (-EINVAL) bad descriptor offset. + * - (-ENOTSUP) if the device does not support this function. + * - (-ENODEV) bad port or queue (only if compiled with debug). */ -int rte_eth_timesync_disable(uint16_t port_id); +static inline int +rte_eth_rx_descriptor_status(uint16_t port_id, uint16_t queue_id, + uint16_t offset) +{ + struct rte_eth_dev *dev; + void *rxq; -/** - * Read an IEEE1588/802.1AS RX timestamp from an Ethernet device. - * - * @param port_id - * The port identifier of the Ethernet device. - * @param timestamp - * Pointer to the timestamp struct. - * @param flags - * Device specific flags. Used to pass the RX timesync register index to - * i40e. Unused in igb/ixgbe, pass 0 instead. - * - * @return - * - 0: Success. - * - -EINVAL: No timestamp is available. - * - -ENODEV: The port ID is invalid. - * - -ENOTSUP: The function is not supported by the Ethernet driver. - */ -int rte_eth_timesync_read_rx_timestamp(uint16_t port_id, - struct timespec *timestamp, uint32_t flags); +#ifdef RTE_LIBRTE_ETHDEV_DEBUG + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); +#endif + dev = &rte_eth_devices[port_id]; +#ifdef RTE_LIBRTE_ETHDEV_DEBUG + if (queue_id >= dev->data->nb_rx_queues) + return -ENODEV; +#endif + RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->rx_descriptor_status, -ENOTSUP); + rxq = dev->data->rx_queues[queue_id]; -/** - * Read an IEEE1588/802.1AS TX timestamp from an Ethernet device. - * - * @param port_id - * The port identifier of the Ethernet device. - * @param timestamp - * Pointer to the timestamp struct. - * - * @return - * - 0: Success. - * - -EINVAL: No timestamp is available. - * - -ENODEV: The port ID is invalid. - * - -ENOTSUP: The function is not supported by the Ethernet driver. - */ -int rte_eth_timesync_read_tx_timestamp(uint16_t port_id, - struct timespec *timestamp); + return (*dev->dev_ops->rx_descriptor_status)(rxq, offset); +} + +#define RTE_ETH_TX_DESC_FULL 0 /**< Desc filled for hw, waiting xmit. */ +#define RTE_ETH_TX_DESC_DONE 1 /**< Desc done, packet is transmitted. */ +#define RTE_ETH_TX_DESC_UNAVAIL 2 /**< Desc used by driver or hw. */ /** - * Adjust the timesync clock on an Ethernet device. - * - * This is usually used in conjunction with other Ethdev timesync functions to - * synchronize the device time using the IEEE1588/802.1AS protocol. + * Check the status of a Tx descriptor in the queue. * - * @param port_id - * The port identifier of the Ethernet device. - * @param delta - * The adjustment in nanoseconds. + * It should be called in a similar context than the Tx function: + * - on a dataplane core + * - not concurrently on the same queue * - * @return - * - 0: Success. - * - -ENODEV: The port ID is invalid. - * - -ENOTSUP: The function is not supported by the Ethernet driver. - */ -int rte_eth_timesync_adjust_time(uint16_t port_id, int64_t delta); - -/** - * Read the time from the timesync clock on an Ethernet device. + * Since it's a dataplane function, no check is performed on port_id and + * queue_id. The caller must therefore ensure that the port is enabled + * and the queue is configured and running. * - * This is usually used in conjunction with other Ethdev timesync functions to - * synchronize the device time using the IEEE1588/802.1AS protocol. + * Note: accessing to a random descriptor in the ring may trigger cache + * misses and have a performance impact. * * @param port_id - * The port identifier of the Ethernet device. - * @param time - * Pointer to the timespec struct that holds the time. + * A valid port identifier of the Ethernet device which. + * @param queue_id + * A valid Tx queue identifier on this port. + * @param offset + * The offset of the descriptor starting from tail (0 is the place where + * the next packet will be send). * * @return - * - 0: Success. + * - (RTE_ETH_TX_DESC_FULL) Descriptor is being processed by the hw, i.e. + * in the transmit queue. + * - (RTE_ETH_TX_DESC_DONE) Hardware is done with this descriptor, it can + * be reused by the driver. + * - (RTE_ETH_TX_DESC_UNAVAIL): Descriptor is unavailable, reserved by the + * driver or the hardware. + * - (-EINVAL) bad descriptor offset. + * - (-ENOTSUP) if the device does not support this function. + * - (-ENODEV) bad port or queue (only if compiled with debug). */ -int rte_eth_timesync_read_time(uint16_t port_id, struct timespec *time); +static inline int rte_eth_tx_descriptor_status(uint16_t port_id, + uint16_t queue_id, uint16_t offset) +{ + struct rte_eth_dev *dev; + void *txq; + +#ifdef RTE_LIBRTE_ETHDEV_DEBUG + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); +#endif + dev = &rte_eth_devices[port_id]; +#ifdef RTE_LIBRTE_ETHDEV_DEBUG + if (queue_id >= dev->data->nb_tx_queues) + return -ENODEV; +#endif + RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->tx_descriptor_status, -ENOTSUP); + txq = dev->data->tx_queues[queue_id]; + + return (*dev->dev_ops->tx_descriptor_status)(txq, offset); +} /** - * Set the time of the timesync clock on an Ethernet device. + * Send a burst of output packets on a transmit queue of an Ethernet device. * - * This is usually used in conjunction with other Ethdev timesync functions to - * synchronize the device time using the IEEE1588/802.1AS protocol. + * The rte_eth_tx_burst() function is invoked to transmit output packets + * on the output queue *queue_id* of the Ethernet device designated by its + * *port_id*. + * The *nb_pkts* parameter is the number of packets to send which are + * supplied in the *tx_pkts* array of *rte_mbuf* structures, each of them + * allocated from a pool created with rte_pktmbuf_pool_create(). + * The rte_eth_tx_burst() function loops, sending *nb_pkts* packets, + * up to the number of transmit descriptors available in the TX ring of the + * transmit queue. + * For each packet to send, the rte_eth_tx_burst() function performs + * the following operations: + * + * - Pick up the next available descriptor in the transmit ring. + * + * - Free the network buffer previously sent with that descriptor, if any. + * + * - Initialize the transmit descriptor with the information provided + * in the *rte_mbuf data structure. + * + * In the case of a segmented packet composed of a list of *rte_mbuf* buffers, + * the rte_eth_tx_burst() function uses several transmit descriptors + * of the ring. + * + * The rte_eth_tx_burst() function returns the number of packets it + * actually sent. A return value equal to *nb_pkts* means that all packets + * have been sent, and this is likely to signify that other output packets + * could be immediately transmitted again. Applications that implement a + * "send as many packets to transmit as possible" policy can check this + * specific case and keep invoking the rte_eth_tx_burst() function until + * a value less than *nb_pkts* is returned. + * + * It is the responsibility of the rte_eth_tx_burst() function to + * transparently free the memory buffers of packets previously sent. + * This feature is driven by the *tx_free_thresh* value supplied to the + * rte_eth_dev_configure() function at device configuration time. + * When the number of free TX descriptors drops below this threshold, the + * rte_eth_tx_burst() function must [attempt to] free the *rte_mbuf* buffers + * of those packets whose transmission was effectively completed. + * + * If the PMD is DEV_TX_OFFLOAD_MT_LOCKFREE capable, multiple threads can + * invoke this function concurrently on the same tx queue without SW lock. + * @see rte_eth_dev_info_get, struct rte_eth_txconf::txq_flags * * @param port_id * The port identifier of the Ethernet device. - * @param time - * Pointer to the timespec struct that holds the time. - * + * @param queue_id + * The index of the transmit queue through which output packets must be + * sent. + * The value must be in the range [0, nb_tx_queue - 1] previously supplied + * to rte_eth_dev_configure(). + * @param tx_pkts + * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures + * which contain the output packets. + * @param nb_pkts + * The maximum number of packets to transmit. * @return - * - 0: Success. - * - -EINVAL: No timestamp is available. - * - -ENODEV: The port ID is invalid. - * - -ENOTSUP: The function is not supported by the Ethernet driver. + * The number of output packets actually stored in transmit descriptors of + * the transmit ring. The return value can be less than the value of the + * *tx_pkts* parameter when the transmit ring is full or has been filled up. */ -int rte_eth_timesync_write_time(uint16_t port_id, const struct timespec *time); +static inline uint16_t +rte_eth_tx_burst(uint16_t port_id, uint16_t queue_id, + struct rte_mbuf **tx_pkts, uint16_t nb_pkts) +{ + struct rte_eth_dev *dev = &rte_eth_devices[port_id]; + +#ifdef RTE_LIBRTE_ETHDEV_DEBUG + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, 0); + RTE_FUNC_PTR_OR_ERR_RET(*dev->tx_pkt_burst, 0); + + if (queue_id >= dev->data->nb_tx_queues) { + RTE_PMD_DEBUG_TRACE("Invalid TX queue_id=%d\n", queue_id); + return 0; + } +#endif + +#ifdef RTE_ETHDEV_RXTX_CALLBACKS + struct rte_eth_rxtx_callback *cb = dev->pre_tx_burst_cbs[queue_id]; + + if (unlikely(cb != NULL)) { + do { + nb_pkts = cb->fn.tx(port_id, queue_id, tx_pkts, nb_pkts, + cb->param); + cb = cb->next; + } while (cb != NULL); + } +#endif + + return (*dev->tx_pkt_burst)(dev->data->tx_queues[queue_id], tx_pkts, nb_pkts); +} /** - * Config l2 tunnel ether type of an Ethernet device for filtering specific - * tunnel packets by ether type. + * @warning + * @b EXPERIMENTAL: this API may change without prior notice + * + * Process a burst of output packets on a transmit queue of an Ethernet device. + * + * The rte_eth_tx_prepare() function is invoked to prepare output packets to be + * transmitted on the output queue *queue_id* of the Ethernet device designated + * by its *port_id*. + * The *nb_pkts* parameter is the number of packets to be prepared which are + * supplied in the *tx_pkts* array of *rte_mbuf* structures, each of them + * allocated from a pool created with rte_pktmbuf_pool_create(). + * For each packet to send, the rte_eth_tx_prepare() function performs + * the following operations: + * + * - Check if packet meets devices requirements for tx offloads. + * + * - Check limitations about number of segments. + * + * - Check additional requirements when debug is enabled. + * + * - Update and/or reset required checksums when tx offload is set for packet. + * + * Since this function can modify packet data, provided mbufs must be safely + * writable (e.g. modified data cannot be in shared segment). + * + * The rte_eth_tx_prepare() function returns the number of packets ready to be + * sent. A return value equal to *nb_pkts* means that all packets are valid and + * ready to be sent, otherwise stops processing on the first invalid packet and + * leaves the rest packets untouched. + * + * When this functionality is not implemented in the driver, all packets are + * are returned untouched. * * @param port_id * The port identifier of the Ethernet device. - * @param l2_tunnel - * l2 tunnel configuration. - * + * The value must be a valid port id. + * @param queue_id + * The index of the transmit queue through which output packets must be + * sent. + * The value must be in the range [0, nb_tx_queue - 1] previously supplied + * to rte_eth_dev_configure(). + * @param tx_pkts + * The address of an array of *nb_pkts* pointers to *rte_mbuf* structures + * which contain the output packets. + * @param nb_pkts + * The maximum number of packets to process. * @return - * - (0) if successful. - * - (-ENODEV) if port identifier is invalid. - * - (-ENOTSUP) if hardware doesn't support tunnel type. + * The number of packets correct and ready to be sent. The return value can be + * less than the value of the *tx_pkts* parameter when some packet doesn't + * meet devices requirements with rte_errno set appropriately: + * - -EINVAL: offload flags are not correctly set + * - -ENOTSUP: the offload feature is not supported by the hardware + * */ -int -rte_eth_dev_l2_tunnel_eth_type_conf(uint16_t port_id, - struct rte_eth_l2_tunnel_conf *l2_tunnel); -/** - * Enable/disable l2 tunnel offload functions. Include, - * 1, The ability of parsing a type of l2 tunnel of an Ethernet device. - * Filtering, forwarding and offloading this type of tunnel packets depend on - * this ability. - * 2, Stripping the l2 tunnel tag. - * 3, Insertion of the l2 tunnel tag. - * 4, Forwarding the packets based on the l2 tunnel tag. - * - * @param port_id - * The port identifier of the Ethernet device. - * @param l2_tunnel - * l2 tunnel parameters. - * @param mask - * Indicate the offload function. - * @param en - * Enable or disable this function. +#ifndef RTE_ETHDEV_TX_PREPARE_NOOP + +static inline uint16_t +rte_eth_tx_prepare(uint16_t port_id, uint16_t queue_id, + struct rte_mbuf **tx_pkts, uint16_t nb_pkts) +{ + struct rte_eth_dev *dev; + +#ifdef RTE_LIBRTE_ETHDEV_DEBUG + if (!rte_eth_dev_is_valid_port(port_id)) { + RTE_PMD_DEBUG_TRACE("Invalid TX port_id=%d\n", port_id); + rte_errno = -EINVAL; + return 0; + } +#endif + + dev = &rte_eth_devices[port_id]; + +#ifdef RTE_LIBRTE_ETHDEV_DEBUG + if (queue_id >= dev->data->nb_tx_queues) { + RTE_PMD_DEBUG_TRACE("Invalid TX queue_id=%d\n", queue_id); + rte_errno = -EINVAL; + return 0; + } +#endif + + if (!dev->tx_pkt_prepare) + return nb_pkts; + + return (*dev->tx_pkt_prepare)(dev->data->tx_queues[queue_id], + tx_pkts, nb_pkts); +} + +#else + +/* + * Native NOOP operation for compilation targets which doesn't require any + * preparations steps, and functional NOOP may introduce unnecessary performance + * drop. * - * @return - * - (0) if successful. - * - (-ENODEV) if port identifier is invalid. - * - (-ENOTSUP) if hardware doesn't support tunnel type. + * Generally this is not a good idea to turn it on globally and didn't should + * be used if behavior of tx_preparation can change. */ -int -rte_eth_dev_l2_tunnel_offload_set(uint16_t port_id, - struct rte_eth_l2_tunnel_conf *l2_tunnel, - uint32_t mask, - uint8_t en); -/** -* Get the port id from pci address or device name -* Ex: 0000:2:00.0 or vdev name net_pcap0 -* -* @param name -* pci address or name of the device -* @param port_id -* pointer to port identifier of the device -* @return -* - (0) if successful and port_id is filled. -* - (-ENODEV or -EINVAL) on failure. -*/ -int -rte_eth_dev_get_port_by_name(const char *name, uint16_t *port_id); +static inline uint16_t +rte_eth_tx_prepare(__rte_unused uint16_t port_id, + __rte_unused uint16_t queue_id, + __rte_unused struct rte_mbuf **tx_pkts, uint16_t nb_pkts) +{ + return nb_pkts; +} -/** -* Get the device name from port id -* -* @param port_id -* pointer to port identifier of the device -* @param name -* pci address or name of the device -* @return -* - (0) if successful. -* - (-EINVAL) on failure. -*/ -int -rte_eth_dev_get_name_by_port(uint16_t port_id, char *name); +#endif /** - * Check that numbers of Rx and Tx descriptors satisfy descriptors limits from - * the ethernet device information, otherwise adjust them to boundaries. + * Send any packets queued up for transmission on a port and HW queue + * + * This causes an explicit flush of packets previously buffered via the + * rte_eth_tx_buffer() function. It returns the number of packets successfully + * sent to the NIC, and calls the error callback for any unsent packets. Unless + * explicitly set up otherwise, the default callback simply frees the unsent + * packets back to the owning mempool. * * @param port_id * The port identifier of the Ethernet device. - * @param nb_rx_desc - * A pointer to a uint16_t where the number of receive - * descriptors stored. - * @param nb_tx_desc - * A pointer to a uint16_t where the number of transmit - * descriptors stored. + * @param queue_id + * The index of the transmit queue through which output packets must be + * sent. + * The value must be in the range [0, nb_tx_queue - 1] previously supplied + * to rte_eth_dev_configure(). + * @param buffer + * Buffer of packets to be transmit. * @return - * - (0) if successful. - * - (-ENOTSUP, -ENODEV or -EINVAL) on failure. + * The number of packets successfully sent to the Ethernet device. The error + * callback is called for any packets which could not be sent. */ -int rte_eth_dev_adjust_nb_rx_tx_desc(uint16_t port_id, - uint16_t *nb_rx_desc, - uint16_t *nb_tx_desc); +static inline uint16_t +rte_eth_tx_buffer_flush(uint16_t port_id, uint16_t queue_id, + struct rte_eth_dev_tx_buffer *buffer) +{ + uint16_t sent; + uint16_t to_send = buffer->length; + + if (to_send == 0) + return 0; + + sent = rte_eth_tx_burst(port_id, queue_id, buffer->pkts, to_send); + + buffer->length = 0; + /* All packets sent, or to be dealt with by callback below */ + if (unlikely(sent != to_send)) + buffer->error_callback(&buffer->pkts[sent], to_send - sent, + buffer->error_userdata); + + return sent; +} /** - * Test if a port supports specific mempool ops. + * Buffer a single packet for future transmission on a port and queue + * + * This function takes a single mbuf/packet and buffers it for later + * transmission on the particular port and queue specified. Once the buffer is + * full of packets, an attempt will be made to transmit all the buffered + * packets. In case of error, where not all packets can be transmitted, a + * callback is called with the unsent packets as a parameter. If no callback + * is explicitly set up, the unsent packets are just freed back to the owning + * mempool. The function returns the number of packets actually sent i.e. + * 0 if no buffer flush occurred, otherwise the number of packets successfully + * flushed * * @param port_id - * Port identifier of the Ethernet device. - * @param [in] pool - * The name of the pool operations to test. + * The port identifier of the Ethernet device. + * @param queue_id + * The index of the transmit queue through which output packets must be + * sent. + * The value must be in the range [0, nb_tx_queue - 1] previously supplied + * to rte_eth_dev_configure(). + * @param buffer + * Buffer used to collect packets to be sent. + * @param tx_pkt + * Pointer to the packet mbuf to be sent. * @return - * - 0: best mempool ops choice for this port. - * - 1: mempool ops are supported for this port. - * - -ENOTSUP: mempool ops not supported for this port. - * - -ENODEV: Invalid port Identifier. - * - -EINVAL: Pool param is null. + * 0 = packet has been buffered for later transmission + * N > 0 = packet has been buffered, and the buffer was subsequently flushed, + * causing N packets to be sent, and the error callback to be called for + * the rest. */ -int -rte_eth_dev_pool_ops_supported(uint16_t port_id, const char *pool); +static __rte_always_inline uint16_t +rte_eth_tx_buffer(uint16_t port_id, uint16_t queue_id, + struct rte_eth_dev_tx_buffer *buffer, struct rte_mbuf *tx_pkt) +{ + buffer->pkts[buffer->length++] = tx_pkt; + if (buffer->length < buffer->size) + return 0; + + return rte_eth_tx_buffer_flush(port_id, queue_id, buffer); +} #ifdef __cplusplus } -- 2.14.3