[API-NEXT,v3,1/2] api: schedule: add scheduler flow aware mode

Message ID 1534939206-19985-2-git-send-email-odpbot@yandex.ru
State New
Headers show
Series
  • api: schedule: add scheduler flow aware mode
Related show

Commit Message

Github ODP bot Aug. 22, 2018, noon
From: Balasubramanian Manoharan <bala.manoharan@linaro.org>


ODP scheduler configuration to support flow aware mode

Signed-off-by: Balasubramanian Manoharan <bala.manoharan@linaro.org>

---
/** Email created from pull request 665 (bala-manoharan:sched_flow_aware)
 ** https://github.com/Linaro/odp/pull/665
 ** Patch: https://github.com/Linaro/odp/pull/665.patch
 ** Base sha: d42ef2c5a01d29a9877e0b487694f66e40c43624
 ** Merge commit sha: dcc55a30faf9b8487dc21576e88b55c0720fa78c
 **/
 include/odp/api/spec/event.h          |  39 ++++++++
 include/odp/api/spec/schedule.h       | 129 ++++++++++++++++++++++++++
 include/odp/api/spec/schedule_types.h |   6 ++
 3 files changed, 174 insertions(+)

Patch

diff --git a/include/odp/api/spec/event.h b/include/odp/api/spec/event.h
index d9f7ab73d..d953fa7b2 100644
--- a/include/odp/api/spec/event.h
+++ b/include/odp/api/spec/event.h
@@ -209,6 +209,45 @@  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 hash value
+ *
+ * Returns the hash value set in the event.
+ * Flow hash value set in the event is used by scheduler to distribute the
+ * event across different flows.
+ *
+ * @param	event	Event handle
+ *
+ * @return		Hash value
+ *
+ * @note The hash algorithm and the header fields defining the flow (therefore
+ * used for hashing) is platform dependent. The initial event flow hash
+ * generated by the HW will be same for flow hash generated for packets.
+
+ * @note The returned hash is either the platform generated (if any), or if
+ * odp_event_flow_hash_set() were called then the value set there.
+ */
+uint32_t odp_event_flow_hash(odp_event_t event);
+
+/**
+ * Set event flow hash value
+ *
+ * Store the event flow hash for the event and sets the flow hash flag.
+ * When scheduler is configured as flow aware, schedule queue synchronization
+ * will be based on flow within each queue.
+ * When scheduler is configured as flow unaware, event flow hash is ignored by
+ * the implementation.
+ * The value of flow hash should not be greater than the max flow count
+ * supported by the implementation.
+ *
+ * @param      event		Event handle
+ * @param      flow_hash        Hash value to set
+ *
+ * @note When scheduler is configured as flow unaware, overwriting the platform
+ * provided value doesn't change how the platform handles this packet after it.
+ */
+void odp_event_flow_hash_set(odp_event_t event, uint32_t flow_hash);
+
 /**
  * @}
  */
diff --git a/include/odp/api/spec/schedule.h b/include/odp/api/spec/schedule.h
index bbc749836..53e5c2690 100644
--- a/include/odp/api/spec/schedule.h
+++ b/include/odp/api/spec/schedule.h
@@ -24,6 +24,7 @@  extern "C" {
 #include <odp/api/queue.h>
 #include <odp/api/schedule_types.h>
 #include <odp/api/thrmask.h>
+#include <odp/api/support.h>
 
 /** @defgroup odp_scheduler ODP SCHEDULER
  *  Operations on the scheduler.
@@ -45,6 +46,98 @@  extern "C" {
  * Maximum schedule group name length in chars including null char
  */
 
+/**
+ * Schedule configuration
+ * When schedule configuration is not called by the application, the scheduler
+ * behaves in flow-unaware mode and event flow hash values are ignored
+ */
+typedef struct odp_schedule_config_t {
+
+	/* Number of flows per queue to be supported
+	 * Scheduler enables flow aware mode when flow count is configured
+	 * greater than 1.
+	 * Flows are lightweight entities and packets can be assigned to specific
+	 * flows by the application using odp_event_flow_hash_set() before
+	 * enqueuing the packet into the scheduler. This value is ignored unless
+	 * scheduler supports flow aware mode
+	 * Depening on the implementation this number might be rounded-off to
+	 * nearest supported value (e.g power of 2)
+	 * This number should be less than maximum flow supported by the
+	 * implementation.
+	 * @see odp_schedule_capability_t
+	 */
+	uint32_t flow_count;
+
+	/* Maximum number of schedule queues to be supported
+	 * Application configures the maximum number of schedule queues to be
+	 * supported by the implementation.
+	 * @see odp_queue_capability_t
+	 */
+	uint32_t queue_count;
+
+	/* Maximum number of events required to be stored simultaneously in
+	 * schedule queue. This number should be less than 'max_queue_size'
+	 * supported by the implementation.
+	 * A value of 0 configures default queue size supported by the
+	 * implementation.
+	 */
+	uint32_t queue_size;
+} odp_schedule_config_t;
+
+typedef struct odp_schedule_capability_t {
+
+	/* 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_flow_count;
+
+	/* Maximum supported queues
+	 * Specifies the maximum number of queues supported by the
+	 * implementation.
+	 */
+	uint32_t max_queue_count;
+
+	/* Maximum number of events a schedule queue can store simultaneoulsy.
+	 * A value of 0 indicates the implementation does not restrict the
+	 * queue size
+	 */
+	uint32_t max_queue_size;
+} odp_schedule_capability_t;
+
+/**
+ * Start scheduler operation
+ *
+ * Activate scheduler module to schedule packets across different schedule
+ * queues. The scheduler module should be started before creating any odp
+ * queues. The scheduler module can be stopped usinig odp_schedule_stop().
+ *
+ * The initialization sequeunce should be,
+ * odp_schedule_capability()
+ * odp_schedule_config_init()
+ * odp_schedule_config()
+ * odp_schedule_start()
+ * odp_schedule()
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ *
+ * @odp_schedule_stop()
+ */
+int odp_schedule_start(void);
+
+/**
+ * Stop scheduler operations
+ *
+ * Stop scheduler module. The application should make sure there are no further
+ * events in the scheduler before calling odp_schedule_stop.
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_schedule_stop(void);
+
 /**
  * Schedule wait time
  *
@@ -187,6 +280,42 @@  void odp_schedule_prefetch(int num);
  */
 int odp_schedule_num_prio(void);
 
+/**
+ * Initialize schedule configuration options
+ *
+ * Initialize an odp_schedule_config_t to its default values.
+ *
+ * @param[out] config  Pointer to schedule configuration structure
+ */
+void odp_schedule_config_init(odp_schedule_config_t *config);
+
+
+/**
+ * Global schedule configuration
+ *
+ * Initialize and configure scheduler with global configuration options.
+ *
+ * @param config   Pointer to scheduler configuration structure
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ *
+ * @see odp_schedule_capability(), odp_schedule_config_init()
+ */
+int odp_schedule_config(const odp_schedule_config_t *config);
+
+/**
+ * Query scheduler capabilities
+ *
+ * Outputs schedule capabilities on success.
+ *
+ * @param[out] capa   Pointer to capability structure for output
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ */
+int odp_schedule_capability(odp_schedule_capability_t *capa);
+
 /**
  * Schedule group create
  *
diff --git a/include/odp/api/spec/schedule_types.h b/include/odp/api/spec/schedule_types.h
index 44eb663a2..7f2179e9e 100644
--- a/include/odp/api/spec/schedule_types.h
+++ b/include/odp/api/spec/schedule_types.h
@@ -79,6 +79,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 hash value affects
+ * scheduling of the event and synchronization is maintained per flow within
+ * each queue.
  */
 
 /**
@@ -105,6 +108,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 hash value affects
+ * scheduling of the event and synchronization is maintained per flow within
+ * each queue.
  */
 
 /**