eventdev: quiesce an event port

Add function to quiesce any core specific resources consumed by
the event port.

When the application decides to migrate the event port to another lcore
or teardown the current lcore it may to call `rte_event_port_quiesce`
to make sure that all the data associated with the event port are released
from the lcore, this might also include any prefetched events.

While releasing the event port from the lcore, this function calls the
user-provided flush callback once per event.

Signed-off-by: Pavan Nikhilesh <pbhagavatula@marvell.com>
Acked-by: Jerin Jacob <jerinj@marvell.com>

diff --git a/doc/guides/prog_guide/eventdev.rst b/doc/guides/prog_guide/eventdev.rst
index a49e486a303fefac5892f9ebe4381f3cc1cdf483..8c13c5832cf999ed7b151c87d024b2615da60228 100644 (file)
--- a/doc/guides/prog_guide/eventdev.rst
+++ b/doc/guides/prog_guide/eventdev.rst
@@ -412,6 +412,41 @@ An event driven worker thread has following typical workflow on fastpath:
                rte_event_enqueue_burst(...);
        }
 
+Quiescing Event Ports
+~~~~~~~~~~~~~~~~~~~~~
+
+To migrate the event port to another lcore
+or while tearing down a worker core using an event port,
+``rte_event_port_quiesce()`` can be invoked to make sure that all the data
+associated with the event port are released from the worker core,
+this might also include any prefetched events.
+
+A flush callback can be passed to the function to handle any outstanding events.
+
+.. code-block:: c
+
+        rte_event_port_quiesce(dev_id, port_id, release_cb, NULL);
+
+.. Note::
+
+        Invocation of this API does not affect the existing port configuration.
+
+Stopping the EventDev
+~~~~~~~~~~~~~~~~~~~~~
+
+A single function call tells the eventdev instance to stop processing events.
+A flush callback can be registered to free any inflight events
+using ``rte_event_dev_stop_flush_callback_register()`` function.
+
+.. code-block:: c
+
+        int err = rte_event_dev_stop(dev_id);
+
+.. Note::
+
+        The event producers such as ``event_eth_rx_adapter``,
+        ``event_timer_adapter`` and ``event_crypto_adapter``
+        need to be stopped before stopping the event device.
 
 Summary
 -------

diff --git a/doc/guides/rel_notes/release_22_07.rst b/doc/guides/rel_notes/release_22_07.rst
index a60a0d5f16e0c32a11b1054386118bd2873a4b8d..3d867322aed7d0b4066422f550ee60f2ba016f22 100644 (file)
--- a/doc/guides/rel_notes/release_22_07.rst
+++ b/doc/guides/rel_notes/release_22_07.rst
@@ -86,6 +86,12 @@ New Features
   * Added AH mode support in lookaside protocol (IPsec) for CN9K & CN10K.
   * Added AES-GMAC support in lookaside protocol (IPsec) for CN9K & CN10K.
 
+* **Added eventdev API to quiesce an event port.**
+
+  Added the function ``rte_event_port_quiesce()``
+  to quiesce any lcore-specific resources consumed by the event port,
+  when the lcore is no more associated with an event port.
+
 
 Removed Items
 -------------

diff --git a/lib/eventdev/eventdev_pmd.h b/lib/eventdev/eventdev_pmd.h
index ce469d47a6b01fc6ff7e097b060eb58deef76cf4..6173f22b9b77a17bc7e458baa115f656fcb1a25e 100644 (file)
--- a/lib/eventdev/eventdev_pmd.h
+++ b/lib/eventdev/eventdev_pmd.h
@@ -381,6 +381,23 @@ typedef int (*eventdev_port_setup_t)(struct rte_eventdev *dev,
  */
 typedef void (*eventdev_port_release_t)(void *port);
 
+/**
+ * Quiesce any core specific resources consumed by the event port
+ *
+ * @param dev
+ *   Event device pointer.
+ * @param port
+ *   Event port pointer.
+ * @param flush_cb
+ *   User-provided event flush function.
+ * @param args
+ *   Arguments to be passed to the user-provided event flush function.
+ *
+ */
+typedef void (*eventdev_port_quiesce_t)(struct rte_eventdev *dev, void *port,
+                                       rte_eventdev_port_flush_t flush_cb,
+                                       void *args);
+
 /**
  * Link multiple source event queues to destination event port.
  *
@@ -1218,6 +1235,8 @@ struct eventdev_ops {
        /**< Set up an event port. */
        eventdev_port_release_t port_release;
        /**< Release an event port. */
+       eventdev_port_quiesce_t port_quiesce;
+       /**< Quiesce an event port. */
 
        eventdev_port_link_t port_link;
        /**< Link event queues to an event port. */

diff --git a/lib/eventdev/rte_eventdev.c b/lib/eventdev/rte_eventdev.c
index 532a253553a4f6c0b677543950cb293aef788460..0250e57f24bcc111d655bf31eff7b4ed3e7657cf 100644 (file)
--- a/lib/eventdev/rte_eventdev.c
+++ b/lib/eventdev/rte_eventdev.c
@@ -730,6 +730,25 @@ rte_event_port_setup(uint8_t dev_id, uint8_t port_id,
        return 0;
 }
 
+void
+rte_event_port_quiesce(uint8_t dev_id, uint8_t port_id,
+                      rte_eventdev_port_flush_t release_cb, void *args)
+{
+       struct rte_eventdev *dev;
+
+       RTE_EVENTDEV_VALID_DEVID_OR_RET(dev_id);
+       dev = &rte_eventdevs[dev_id];
+
+       if (!is_valid_port(dev, port_id)) {
+               RTE_EDEV_LOG_ERR("Invalid port_id=%" PRIu8, port_id);
+               return;
+       }
+
+       if (dev->dev_ops->port_quiesce)
+               (*dev->dev_ops->port_quiesce)(dev, dev->data->ports[port_id],
+                                             release_cb, args);
+}
+
 int
 rte_event_dev_attr_get(uint8_t dev_id, uint32_t attr_id,
                       uint32_t *attr_value)

diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
index 42a566016994d0924c4347d76f75acb88cc2b964..4454eaea12300572d03d5adb6b37e475abce51e5 100644 (file)
--- a/lib/eventdev/rte_eventdev.h
+++ b/lib/eventdev/rte_eventdev.h
@@ -830,6 +830,42 @@ int
 rte_event_port_setup(uint8_t dev_id, uint8_t port_id,
                     const struct rte_event_port_conf *port_conf);
 
+typedef void (*rte_eventdev_port_flush_t)(uint8_t dev_id,
+                                         struct rte_event event, void *arg);
+/**< Callback function prototype that can be passed during
+ * rte_event_port_release(), invoked once per a released event.
+ */
+
+/**
+ * Quiesce any core specific resources consumed by the event port.
+ *
+ * Event ports are generally coupled with lcores, and a given Hardware
+ * implementation might require the PMD to store port specific data in the
+ * lcore.
+ * When the application decides to migrate the event port to another lcore
+ * or teardown the current lcore it may to call `rte_event_port_quiesce`
+ * to make sure that all the data associated with the event port are released
+ * from the lcore, this might also include any prefetched events.
+ * While releasing the event port from the lcore, this function calls the
+ * user-provided flush callback once per event.
+ *
+ * @note Invocation of this API does not affect the existing port configuration.
+ *
+ * @param dev_id
+ *   The identifier of the device.
+ * @param port_id
+ *   The index of the event port to setup. The value must be in the range
+ *   [0, nb_event_ports - 1] previously supplied to rte_event_dev_configure().
+ * @param release_cb
+ *   Callback function invoked once per flushed event.
+ * @param args
+ *   Argument supplied to callback.
+ */
+__rte_experimental
+void
+rte_event_port_quiesce(uint8_t dev_id, uint8_t port_id,
+                      rte_eventdev_port_flush_t release_cb, void *args);
+
 /**
  * The queue depth of the port on the enqueue side
  */

diff --git a/lib/eventdev/version.map b/lib/eventdev/version.map
index cd5dada07f5296d8602b303fd5086918f81e146b..19070935396987ae963f8cf86aa975ae64da1c23 100644 (file)
--- a/lib/eventdev/version.map
+++ b/lib/eventdev/version.map
@@ -108,6 +108,9 @@ EXPERIMENTAL {
 
        # added in 22.03
        rte_event_eth_rx_adapter_event_port_get;
+
+       # added in 22.07
+       rte_event_port_quiesce;
 };
 
 INTERNAL {