@@ -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);
+
/**
* @}
*/
@@ -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
*
@@ -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.
*/
/**