api: schedule: add scheduler flow aware mode

ODP scheduler configuration to support flow aware mode

Signed-off-by: Balasubramanian Manoharan <bala.manoharan@linaro.org>
Signed-off-by: Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org>
Signed-off-by: Balasubramanian Manoharan <bala.manoharan@linaro.org>
Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org>
Reviewed-by: Petri Savolainen <petri.savolainen@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

include/odp/api/spec/event.h

@@ -209,6 +209,44 @@ void odp_event_free_multi(const odp_event_t event[], int num);
  */
 void odp_event_free_sp(const odp_event_t event[], int num);
 
+/**
+ * Event flow id value
+ *
+ * Returns the flow id value set in the event.
+ * Usage of flow id enables scheduler to maintain multiple synchronization
+ * contexts per single queue. For example, when multiple flows are assigned to
+ * an atomic queue, events of a single flow (events from the same queue with
+ * the same flow id value) are guaranteed to be processed by only single thread
+ * at a time.  For packets received through packet input initial
+ * event flow id will be same as flow hash generated for packets. The hash
+ * algorithm and therefore the resulting flow id value is implementation
+ * specific. Use pktio API configuration options to select the fields used for
+ * initial flow id calculation. For all other events initial flow id is zero
+ * An application can change event flow id using odp_event_flow_id_set().
+ *
+ * @param	event	Event handle
+ *
+ * @return		Flow id of the event
+ *
+ */
+uint32_t odp_event_flow_id(odp_event_t event);
+
+/**
+ * Set event flow id value
+ *
+ * Store the event flow id for the event and sets the flow id flag.
+ * When scheduler is configured as flow aware, scheduled queue synchronization
+ * will be based on this id within each queue.
+ * When scheduler is configured as flow unaware, event flow id is ignored by
+ * the implementation.
+ * The value of flow id must be less than the number of flows configured in the
+ * scheduler.
+ *
+ * @param      event		Event handle
+ * @param      flow_id          Flow event id to be set.
+ */
+void odp_event_flow_id_set(odp_event_t event, uint32_t flow_id);
+
 /**
  * @}
  */

include/odp/api/spec/schedule_types.h

@@ -78,6 +78,9 @@ extern "C" {
  * requests another event from the scheduler, which implicitly releases the
  * context. User may allow the scheduler to release the context earlier than
  * that by calling odp_schedule_release_atomic().
+ * When scheduler is enabled as flow-aware, the event flow id value affects
+ * scheduling of the event and synchronization is maintained per flow within
+ * each queue.
  */
 
 /**
@@ -104,6 +107,9 @@ extern "C" {
  * (e.g. freed or stored) within the context are considered missing from
  * reordering and are skipped at this time (but can be ordered again within
  * another context).
+ * When scheduler is enabled as flow-aware, the event flow id value affects
+ * scheduling of the event and synchronization is maintained per flow within
+ * each queue.
  */
 
 /**
@@ -190,6 +196,13 @@ typedef struct odp_schedule_capability_t {
 	 * events. */
 	uint32_t max_queue_size;
 
+	/** Maximum supported flows per queue.
+	 * Specifies the maximum number of flows per queue supported by the
+	 * implementation.  A value of 0 indicates flow aware mode is not
+	 * supported.
+	 */
+	uint32_t max_flows;
+
 	/** Lock-free (ODP_NONBLOCKING_LF) queues support.
 	 * The specification is the same as for the blocking implementation. */
 	odp_support_t lockfree_queues;
@@ -217,6 +230,22 @@ typedef struct odp_schedule_config_t {
 	 */
 	uint32_t queue_size;
 
+	/** Number of flows per queue to be supported.  Scheduler enables flow
+	 * aware mode when flow count is configured greater than 1 (up to
+	 * 'max_flows' capability).
+	 *
+	 * Flows are lightweight entities and events can be assigned to
+	 * specific flows by the application using odp_event_flow_id_set()
+	 * before enqueuing the event into the scheduler. This value is ignored
+	 * unless scheduler supports flow aware mode.
+	 *
+	 * This number should be less than maximum flow supported by the
+	 * implementation. The default value is zero.
+	 *
+	 * @see odp_schedule_capability_t
+	 */
+	uint32_t num_flows;
+
 } odp_schedule_config_t;
 
 /**