[PATCH v3 3/6] eventdev: add SW event preschedule hint

[<pbhagavatula@marvell.com>]

From: Pavan Nikhilesh <pbhagavatula@marvell.com>

Add a new eventdev API to provide a hint to the eventdev PMD to
pre-schedule the next event into the event port, without releasing
the current flow context.
Event device that support this feature advertises the capability
using the RTE_EVENT_DEV_CAP_SW_PRESCHEDULE capability flag.

Application can invoke `rte_event_port_preschedule` to hint the PMD.

Signed-off-by: Pavan Nikhilesh <pbhagavatula@marvell.com>
---
 doc/guides/prog_guide/eventdev/eventdev.rst |  8 ++++
 doc/guides/rel_notes/release_24_11.rst      |  3 +-
 lib/eventdev/eventdev_pmd.h                 |  2 +
 lib/eventdev/eventdev_private.c             | 21 ++++++++-
 lib/eventdev/eventdev_trace_points.c        |  3 ++
 lib/eventdev/rte_eventdev.h                 | 49 +++++++++++++++++++++
 lib/eventdev/rte_eventdev_core.h            |  5 +++
 lib/eventdev/rte_eventdev_trace_fp.h        |  8 ++++
 lib/eventdev/version.map                    |  2 +
 9 files changed, 98 insertions(+), 3 deletions(-)

diff --git a/doc/guides/prog_guide/eventdev/eventdev.rst b/doc/guides/prog_guide/eventdev/eventdev.rst
index 2deab0333e..1d8b86ab66 100644
--- a/doc/guides/prog_guide/eventdev/eventdev.rst
+++ b/doc/guides/prog_guide/eventdev/eventdev.rst
@@ -390,6 +390,14 @@ To enable or disable event pre-scheduling at a given event port, the application
    // Disable pre-scheduling if thread is about to be scheduled out and issue dequeue() to drain
    // pending events.
 
+Event Pre-schedule Hint can be used to provide a hint to the eventdev PMD to pre-schedule the next
+event without releasing the current flow context. Event device that support this feature advertises
+the capability using the ``RTE_EVENT_DEV_CAP_SW_PRESCHEDULE`` capability flag.
+If pre-scheduling is already enabled at a event device or event port level then the hint is ignored.
+
+.. code-block:: c
+
+   rte_event_port_preschedule(dev_id, port_id, RTE_EVENT_DEV_PRESCHEDULE);
 
 Starting the EventDev
 ~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/rel_notes/release_24_11.rst b/doc/guides/rel_notes/release_24_11.rst
index 6e36ac7b7e..3ada21c084 100644
--- a/doc/guides/rel_notes/release_24_11.rst
+++ b/doc/guides/rel_notes/release_24_11.rst
@@ -64,7 +64,8 @@ New Features
     level pre-scheduling type.
   * Added ``rte_event_port_preschedule_modify`` to modify pre-scheduling type
     on a given event port.
-
+  * Added ``rte_event_port_preschedule`` to allow applications to decide when
+    to pre-schedule events on an event port.
 
 Removed Items
 -------------
diff --git a/lib/eventdev/eventdev_pmd.h b/lib/eventdev/eventdev_pmd.h
index 9ea23aa6cd..0bee2347ef 100644
--- a/lib/eventdev/eventdev_pmd.h
+++ b/lib/eventdev/eventdev_pmd.h
@@ -186,6 +186,8 @@ struct __rte_cache_aligned rte_eventdev {
 	/**< Pointer to PMD Event switch profile function. */
 	event_preschedule_modify_t preschedule_modify;
 	/**< Pointer to PMD Event port pre-schedule type modify function.  */
+	event_preschedule_t preschedule;
+	/**< Pointer to PMD Event port pre-schedule function. */
 
 	uint64_t reserved_64s[3]; /**< Reserved for future fields */
 	void *reserved_ptrs[3];	  /**< Reserved for future fields */
diff --git a/lib/eventdev/eventdev_private.c b/lib/eventdev/eventdev_private.c
index dc37f736f8..6aed1cba9a 100644
--- a/lib/eventdev/eventdev_private.c
+++ b/lib/eventdev/eventdev_private.c
@@ -111,6 +111,19 @@ dummy_event_port_preschedule_modify_hint(__rte_unused void *port,
 	return -ENOTSUP;
 }
 
+static void
+dummy_event_port_preschedule(__rte_unused void *port,
+			     __rte_unused rte_event_dev_preschedule_type_t preschedule)
+{
+	RTE_EDEV_LOG_ERR("pre-schedule requested for unconfigured event device");
+}
+
+static void
+dummy_event_port_preschedule_hint(__rte_unused void *port,
+			     __rte_unused rte_event_dev_preschedule_type_t preschedule)
+{
+}
+
 void
 event_dev_fp_ops_reset(struct rte_event_fp_ops *fp_op)
 {
@@ -124,12 +137,12 @@ event_dev_fp_ops_reset(struct rte_event_fp_ops *fp_op)
 		.dequeue_burst = dummy_event_dequeue_burst,
 		.maintain = dummy_event_maintain,
 		.txa_enqueue = dummy_event_tx_adapter_enqueue,
-		.txa_enqueue_same_dest =
-			dummy_event_tx_adapter_enqueue_same_dest,
+		.txa_enqueue_same_dest = dummy_event_tx_adapter_enqueue_same_dest,
 		.ca_enqueue = dummy_event_crypto_adapter_enqueue,
 		.dma_enqueue = dummy_event_dma_adapter_enqueue,
 		.profile_switch = dummy_event_port_profile_switch,
 		.preschedule_modify = dummy_event_port_preschedule_modify,
+		.preschedule = dummy_event_port_preschedule,
 		.data = dummy_data,
 	};
 
@@ -153,8 +166,12 @@ event_dev_fp_ops_set(struct rte_event_fp_ops *fp_op,
 	fp_op->dma_enqueue = dev->dma_enqueue;
 	fp_op->profile_switch = dev->profile_switch;
 	fp_op->preschedule_modify = dev->preschedule_modify;
+	fp_op->preschedule = dev->preschedule;
 	fp_op->data = dev->data->ports;
 
 	if (fp_op->preschedule_modify == NULL)
 		fp_op->preschedule_modify = dummy_event_port_preschedule_modify_hint;
+
+	if (fp_op->preschedule == NULL)
+		fp_op->preschedule = dummy_event_port_preschedule_hint;
 }
diff --git a/lib/eventdev/eventdev_trace_points.c b/lib/eventdev/eventdev_trace_points.c
index e41674123c..e7af1591f7 100644
--- a/lib/eventdev/eventdev_trace_points.c
+++ b/lib/eventdev/eventdev_trace_points.c
@@ -52,6 +52,9 @@ RTE_TRACE_POINT_REGISTER(rte_eventdev_trace_port_profile_switch,
 RTE_TRACE_POINT_REGISTER(rte_eventdev_trace_port_preschedule_modify,
 	lib.eventdev.port.preschedule.modify)
 
+RTE_TRACE_POINT_REGISTER(rte_eventdev_trace_port_preschedule,
+	lib.eventdev.port.preschedule)
+
 /* Eventdev Rx adapter trace points */
 RTE_TRACE_POINT_REGISTER(rte_eventdev_trace_eth_rx_adapter_create,
 	lib.eventdev.rx.adapter.create)
diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
index 0add0093ac..8df6a8bee1 100644
--- a/lib/eventdev/rte_eventdev.h
+++ b/lib/eventdev/rte_eventdev.h
@@ -480,6 +480,15 @@ struct rte_event;
  * @see rte_event_port_preschedule_modify()
  */
 
+#define RTE_EVENT_DEV_CAP_SW_PRESCHEDULE (1ULL << 19)
+/**< Event device supports software prescheduling.
+ *
+ * When this flag is set, the application can issue preschedule request on
+ * a event port.
+ *
+ * @see rte_event_port_preschedule()
+ */
+
 /* Event device priority levels */
 #define RTE_EVENT_DEV_PRIORITY_HIGHEST   0
 /**< Highest priority level for events and queues.
@@ -2977,6 +2986,46 @@ rte_event_port_preschedule_modify(uint8_t dev_id, uint8_t port_id,
 	return fp_ops->preschedule_modify(port, type);
 }
 
+/**
+ * Provide a hint to the event device to pre-schedule events to event port .
+ *
+ * Hint the event device to pre-schedule events to the event port.
+ * The call doesn't not guarantee that the events will be pre-scheduleed.
+ * The call doesn't release the flow context currently held by the event port.
+ * The event device should support RTE_EVENT_DEV_CAP_SW_PRESCHEDULE capability.
+ *
+ * When pre-scheduling is enabled at an event device or event port level, the
+ * hint is ignored.
+ *
+ * Subsequent calls to rte_event_dequeue_burst() will dequeue the pre-schedule
+ * events but pre-schedule operation is not issued again.
+ *
+ * @param dev_id
+ *   The identifier of the device.
+ * @param port_id
+ *   The identifier of the event port.
+ * @param type
+ *   The pre-schedule type to use on the event port.
+ */
+static inline void
+rte_event_port_preschedule(uint8_t dev_id, uint8_t port_id, rte_event_dev_preschedule_type_t type)
+{
+	const struct rte_event_fp_ops *fp_ops;
+	void *port;
+
+	fp_ops = &rte_event_fp_ops[dev_id];
+	port = fp_ops->data[port_id];
+
+#ifdef RTE_LIBRTE_EVENTDEV_DEBUG
+	if (dev_id >= RTE_EVENT_MAX_DEVS || port_id >= RTE_EVENT_MAX_PORTS_PER_DEV)
+		return;
+	if (port == NULL)
+		return;
+#endif
+	rte_eventdev_trace_port_preschedule(dev_id, port_id, type);
+
+	fp_ops->preschedule(port, type);
+}
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/eventdev/rte_eventdev_core.h b/lib/eventdev/rte_eventdev_core.h
index 2275888a6b..21988abb4f 100644
--- a/lib/eventdev/rte_eventdev_core.h
+++ b/lib/eventdev/rte_eventdev_core.h
@@ -53,6 +53,9 @@ typedef int (*event_preschedule_modify_t)(void *port,
 					  rte_event_dev_preschedule_type_t preschedule_type);
 /**< @internal Modify pre-schedule type on the event port. */
 
+typedef void (*event_preschedule_t)(void *port, rte_event_dev_preschedule_type_t preschedule_type);
+/**< @internal Issue pre-schedule on an event port. */
+
 struct __rte_cache_aligned rte_event_fp_ops {
 	void **data;
 	/**< points to array of internal port data pointers */
@@ -82,6 +85,8 @@ struct __rte_cache_aligned rte_event_fp_ops {
 	/**< PMD Event switch profile function. */
 	event_preschedule_modify_t preschedule_modify;
 	/**< PMD Event port pre-schedule switch. */
+	event_preschedule_t preschedule;
+	/**< PMD Event port pre-schedule. */
 	uintptr_t reserved[4];
 };
 
diff --git a/lib/eventdev/rte_eventdev_trace_fp.h b/lib/eventdev/rte_eventdev_trace_fp.h
index 78baed94de..8290f8a248 100644
--- a/lib/eventdev/rte_eventdev_trace_fp.h
+++ b/lib/eventdev/rte_eventdev_trace_fp.h
@@ -63,6 +63,14 @@ RTE_TRACE_POINT_FP(
 	rte_trace_point_emit_int(type);
 )
 
+RTE_TRACE_POINT_FP(
+	rte_eventdev_trace_port_preschedule,
+	RTE_TRACE_POINT_ARGS(uint8_t dev_id, uint8_t port_id, int type),
+	rte_trace_point_emit_u8(dev_id);
+	rte_trace_point_emit_u8(port_id);
+	rte_trace_point_emit_int(type);
+)
+
 RTE_TRACE_POINT_FP(
 	rte_eventdev_trace_eth_tx_adapter_enqueue,
 	RTE_TRACE_POINT_ARGS(uint8_t dev_id, uint8_t port_id, void *ev_table,
diff --git a/lib/eventdev/version.map b/lib/eventdev/version.map
index b6d63ba576..42a5867aba 100644
--- a/lib/eventdev/version.map
+++ b/lib/eventdev/version.map
@@ -151,6 +151,8 @@ EXPERIMENTAL {
 	# added in 24.11
 	rte_event_port_preschedule_modify;
 	__rte_eventdev_trace_port_preschedule_modify;
+	rte_event_port_preschedule;
+	__rte_eventdev_trace_port_preschedule;
 };
 
 INTERNAL {
-- 
2.25.1