[dpdk-dev] [RFC] eventdev: event tx adapter APIs

[Nikhil Rao <nikhil.rao@intel.com>]

The patch below introduces the event tx adapter APIs that encapsulate common
code for the tx stage of a packet processing pipeline. These APIs allow
the application to configure a rte_service function that reads mbuf events
from an event queue and sends mbufs on the transmit queue and ethernet
port specified in the mbuf private area.

Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>
---
 lib/librte_eventdev/rte_event_eth_tx_adapter.h | 272 +++++++++++++++++++++++++
 1 file changed, 272 insertions(+)
 create mode 100644 lib/librte_eventdev/rte_event_eth_tx_adapter.h

diff --git a/lib/librte_eventdev/rte_event_eth_tx_adapter.h b/lib/librte_eventdev/rte_event_eth_tx_adapter.h
new file mode 100644
index 0000000..56218fe
--- /dev/null
+++ b/lib/librte_eventdev/rte_event_eth_tx_adapter.h
@@ -0,0 +1,272 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2018 Intel Corporation.
+ */
+
+#ifndef _RTE_EVENT_ETH_TX_ADAPTER_
+#define _RTE_EVENT_ETH_TX_ADAPTER_
+
+/**
+ * @file
+ *
+ * RTE Event Ethernet Tx Adapter
+ *
+ * The event ethernet Tx adapter provides the transmit stage of a
+ * event driven packet processing application. It dequeues mbuf events from
+ * an event queue and sends mbufs on a ethernet device.
+ *
+ * The ethernet Tx event adapter's functions are:
+ *  - rte_event_eth_tx_adapter_create()
+ *  - rte_event_eth_tx_adapter_free()
+ *  - rte_event_eth_tx_adapter_start()
+ *  - rte_event_eth_tx_adapter_stop()
+ *  - rte_event_eth_tx_adapter_queue_start()
+ *  - rte_event_eth_tx_adapter_queue_stop()
+ *  - rte_event_eth_tx_adapter_stats_get()
+ *  - rte_event_eth_tx_adapter_stats_reset()
+ *
+ * The application creates the adapter using
+ * rte_event_eth_tx_adapter_create(). The application is required to
+ * have linked a queue to the event port specified in this call.
+ *
+ * The application sends mbufs to the adapter via this event queue. The
+ * ethernet port and transmit queue index to send the mbuf on are specified
+ * in the mbuf private area and are accessed using
+ * struct rte_event_eth_tx_adapter_meta. The offset to this structure within
+ * the private area is provided when creating the adapter.
+ *
+ * The application can start and stop the adapter using the
+ * rte_event_eth_tx_adapter_start/stop() calls.
+ *
+ * To support dynamic reconfiguration of Tx queues, the application can
+ * call rte_event_eth_tx_adapter_queue_start()/stop() to synchronize
+ * access to the Tx queue with the adapter. For example, if the application
+ * wants to reconfigure a Tx queue that could be concurrently
+ * being accessed by the adapter, it calls rte_event_eth_tx_adapter_queue_stop()
+ * first, reconfigures the queue and then calls
+ * rte_event_eth_tx_adapter_queue_start() which signals to the adapter
+ * that it is safe to resume access to the Tx queue.
+ *
+ * The adapter uses an EAL service function and its execution is controlled
+ * using the rte_service APIs. The rte_event_eth_tx_adapter_service_id_get()
+ * function can be used to retrieve the adapter's service function ID.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+
+#include "rte_eventdev.h"
+
+#define RTE_EVENT_ETH_TX_ADAPTER_MAX_INSTANCE 32
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Adapter configuration structure
+ */
+struct rte_event_eth_tx_adapter_conf {
+	uint8_t event_port_id;
+	/**< Event port identifier, the adapter dequeues mbuf events from this
+	 * port.
+	 */
+	uint16_t tx_metadata_off;
+	/**<  Offset of struct rte_event_eth_tx_adapter_meta in the private
+	 * area of the mbuf
+	 */
+	uint32_t max_nb_tx;
+	/**< The adapter can return early if it has processed at least
+	 * max_nb_tx mbufs. This isn't treated as a requirement; batching may
+	 * cause the adapter to process more than max_nb_tx mbufs.
+	 */
+};
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * A structure used to retrieve statistics for an eth tx adapter instance.
+ */
+struct rte_event_eth_tx_adapter_stats {
+	uint64_t event_poll_count;
+	/*< Event port poll count */
+	uint64_t tx_packets;
+	/*< Number of packets transmitted */
+	uint64_t tx_dropped;
+	/*< Number of packets dropped */
+};
+
+/*
+ * Tx adapter metadata used to specifiy the ethernet port id and queue id to be
+ * used for transmitting the mbuf
+ */
+struct rte_event_eth_tx_adapter_meta {
+	uint16_t eth_dev_id;
+	/**< Port identifier of the ethernet device */
+	uint16_t eth_queue_id;
+	/**< Transmit queue index */
+};
+	
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Create a new event ethernet Tx adapter with the specified identifier.
+ *
+ * @param id
+ *  The identifier of the event ethernet Tx adapter.
+ * @param dev_id
+ *  The event device identifier.
+ * @param conf
+ * Tx adapter configuration.
+ * @return
+ *   - 0: Success
+ *   - <0: Error code on failure
+ */
+int rte_event_eth_tx_adapter_create(uint8_t id, uint8_t dev_id,
+				struct rte_event_eth_tx_adapter_conf *conf);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Free an event adapter
+ *
+ * @param id
+ *  Adapter identifier.
+ * @return
+ *   - 0: Success
+ *   - <0: Error code on failure, If the adapter still has Tx queues
+ *      added to it, the function returns -EBUSY.
+ */
+int rte_event_eth_tx_adapter_free(uint8_t id);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Start ethernet Tx event adapter
+ *
+ * @param id
+ *  Adapter identifier.
+ * @return
+ *  - 0: Success, Adapter started correctly.
+ *  - <0: Error code on failure.
+ */
+int rte_event_eth_tx_adapter_start(uint8_t id);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Stop ethernet Tx event adapter
+ *
+ * @param id
+ *  Adapter identifier.
+ * @return
+ *  - 0: Success, Adapter started correctly.
+ *  - <0: Error code on failure.
+ */
+int rte_event_eth_tx_adapter_stop(uint8_t id);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Signal the Tx adapter to start processing mbufs for a
+ * Tx queue. A queue value of -1 is used to indicate all
+ * queues within the device.
+ *
+ * @param id
+ *  Adapter identifier.
+ * @param eth_dev_id
+ *  Ethernet Port Identifier.
+ * @param queue
+ *  Tx queue index.
+ * @return
+ *  - 0: Success, Adapter started correctly.
+ *  - <0: Error code on failure.
+ */
+int rte_event_eth_tx_adapter_queue_start(uint8_t id, 
+					uint16_t eth_dev_id,
+					int32_t queue);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Signal the Tx adapter to stop processing mbufs for a
+ * Tx queue. A queue value of -1 is used to indicate all
+ * queues within the device.
+ *
+ * @param id
+ *  Adapter identifier.
+ * @param eth_dev_id
+ *  Ethernet Port Identifier.
+ * @param queue
+ *  Tx queue index.
+ * @return
+ *  - 0: Success, Adapter started correctly.
+ *  - <0: Error code on failure.
+ */
+int rte_event_eth_tx_adapter_queue_stop(uint8_t id, 
+					uint16_t eth_dev_id,
+					int32_t queue);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Retrieve statistics for an adapter
+ *
+ * @param id
+ *  Adapter identifier.
+ * @param [out] stats
+ *  A pointer to structure used to retrieve statistics for an adapter.
+ * @return
+ *  - 0: Success, retrieved successfully.
+ *  - <0: Error code on failure.
+ */
+int rte_event_eth_tx_adapter_stats_get(uint8_t id,
+				struct rte_event_eth_tx_adapter_stats *stats);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Reset statistics for an adapter.
+ *
+ * @param id
+ *  Adapter identifier.
+ * @return
+ *  - 0: Success, statistics reset successfully.
+ *  - <0: Error code on failure.
+ */
+int rte_event_eth_tx_adapter_stats_reset(uint8_t id);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Retrieve the service ID of an adapter. If the adapter doesn't use
+ * a rte_service function, this function returns -ESRCH.
+ *
+ * @param id
+ *  Adapter identifier.
+ * @param [out] service_id
+ *  A pointer to a uint32_t, to be filled in with the service id.
+ * @return
+ *  - 0: Success
+ *  - <0: Error code on failure, if the adapter doesn't use a rte_service
+ * function, this function returns -ESRCH.
+ */
+int rte_event_eth_tx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
+
+#ifdef __cplusplus
+}
+#endif
+#endif	/* _RTE_EVENT_ETH_TX_ADAPTER_ */
-- 
1.8.3.1