[PATCH v2 10/11] eventdev: RFC clarify comments on scheduling types

[Bruce Richardson]

The description of ordered and atomic scheduling given in the eventdev
doxygen documentation was not always clear. Try and simplify this so
that it is clearer for the end-user of the application

Signed-off-by: Bruce Richardson <bruce.richardson at intel.com>
---

NOTE TO REVIEWERS:
I've updated this based on my understanding of what these scheduling
types are meant to do. It matches my understanding of the support
offered by our Intel DLB2 driver, as well as the SW eventdev, and I
believe the DSW eventdev too. If it does not match the behaviour of
other eventdevs, let's have a discussion to see if we can reach a good
definition of the behaviour that is common.
---
 lib/eventdev/rte_eventdev.h | 47 ++++++++++++++++++++-----------------
 1 file changed, 25 insertions(+), 22 deletions(-)

diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
index 2c6576e921..cb13602ffb 100644
--- a/lib/eventdev/rte_eventdev.h
+++ b/lib/eventdev/rte_eventdev.h
@@ -1313,26 +1313,24 @@ struct rte_event_vector {
 #define RTE_SCHED_TYPE_ORDERED          0
 /**< Ordered scheduling
  *
- * Events from an ordered flow of an event queue can be scheduled to multiple
+ * Events from an ordered event queue can be scheduled to multiple
  * ports for concurrent processing while maintaining the original event order.
  * This scheme enables the user to achieve high single flow throughput by
- * avoiding SW synchronization for ordering between ports which bound to cores.
- *
- * The source flow ordering from an event queue is maintained when events are
- * enqueued to their destination queue within the same ordered flow context.
- * An event port holds the context until application call
- * rte_event_dequeue_burst() from the same port, which implicitly releases
- * the context.
- * User may allow the scheduler to release the context earlier than that
- * by invoking rte_event_enqueue_burst() with RTE_EVENT_OP_RELEASE operation.
- *
- * Events from the source queue appear in their original order when dequeued
- * from a destination queue.
- * Event ordering is based on the received event(s), but also other
- * (newly allocated or stored) events are ordered when enqueued within the same
- * ordered context. Events not enqueued (e.g. released or stored) within the
- * context are  considered missing from reordering and are skipped at this time
- * (but can be ordered again within another context).
+ * avoiding SW synchronization for ordering between ports which are polled by
+ * different cores.
+ *
+ * As events are scheduled to ports/cores, the original event order from the
+ * source event queue is recorded internally in the scheduler. As events are
+ * returned (via FORWARD type enqueue) to the scheduler, the original event
+ * order is restored before the events are enqueued into their new destination
+ * queue.
+ *
+ * Any events not forwarded, ie. dropped explicitly via RELEASE or implicitly
+ * released by the next dequeue from a port, are skipped by the reordering
+ * stage and do not affect the reordering of returned events.
+ *
+ * The ordering behaviour of NEW events with respect to FORWARD events is
+ * undefined and implementation dependent.
  *
  * @see rte_event_queue_setup(), rte_event_dequeue_burst(), RTE_EVENT_OP_RELEASE
  */
@@ -1340,18 +1338,23 @@ struct rte_event_vector {
 #define RTE_SCHED_TYPE_ATOMIC           1
 /**< Atomic scheduling
  *
- * Events from an atomic flow of an event queue can be scheduled only to a
+ * Events from an atomic flow, identified by @ref rte_event.flow_id,
+ * of an event queue can be scheduled only to a
  * single port at a time. The port is guaranteed to have exclusive (atomic)
  * access to the associated flow context, which enables the user to avoid SW
  * synchronization. Atomic flows also help to maintain event ordering
- * since only one port at a time can process events from a flow of an
+ * since only one port at a time can process events from each flow of an
  * event queue.
  *
- * The atomic queue synchronization context is dedicated to the port until
+ * The atomic queue synchronization context for a flow is dedicated to the port until
  * application call rte_event_dequeue_burst() from the same port,
  * which implicitly releases the context. User may allow the scheduler to
  * release the context earlier than that by invoking rte_event_enqueue_burst()
- * with RTE_EVENT_OP_RELEASE operation.
+ * with RTE_EVENT_OP_RELEASE operation for each event from that flow. The context
+ * is only released once the last event from the flow, outstanding on the port,
+ * is released. So long as there is one event from an atomic flow scheduled to
+ * a port/core (including any events in the port's dequeue queue, not yet read
+ * by the application), that port will hold the synchronization context.
  *
  * @see rte_event_queue_setup(), rte_event_dequeue_burst(), RTE_EVENT_OP_RELEASE
  */
-- 
2.40.1