api: scheduler: atomic and ordered definitions

Improved documentation and definition of atomic and ordered
queue synchronisation.

Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org>
Reviewed-by: Ola Liljedahl <ola.liljedahl@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

2 files changed, 35 insertions, 5 deletions

diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h
index 9519edf80..6a8b15f6e 100644
--- a/include/odp/api/queue.h
+++ b/include/odp/api/queue.h
@@ -104,16 +104,37 @@ extern "C" {
 /**
  * @def ODP_SCHED_SYNC_NONE
  * Queue not synchronised
+ *
+ * The scheduler does not provide event synchronisation or ordering, only load
+ * balancing. Events can be scheduled freely to multiple threads for concurrent
+ * processing.
  */
 
 /**
  * @def ODP_SCHED_SYNC_ATOMIC
- * Atomic queue
+ * Atomic queue synchronisation
+ *
+ * Events from an atomic queue can be scheduled only to a single thread at a
+ * time. The thread is guaranteed to have exclusive (atomic) access to the
+ * associated queue context and event ordering is maintained. This enables the
+ * user to avoid SW synchronisation for those two.
+ *
+ * The atomic queue is dedicated to the thread until it requests another event
+ * from the scheduler (which implicitly releases the queue) or calls
+ * odp_schedule_release_atomic(), which allows the scheduler to release the
+ * queue immediately.
  */
 
 /**
  * @def ODP_SCHED_SYNC_ORDERED
- * Ordered queue
+ * Ordered queue synchronisation
+ *
+ * Events from an ordered queue can be scheduled to multiple threads for
+ * concurrent processing. The source queue (dequeue) ordering is maintained when
+ * events are enqueued to their destination queue(s) before another schedule
+ * call. Events from the same (source) queue appear in their original order
+ * when dequeued from a destination queue. The destination queue can have any
+ * queue type and synchronisation method.
  */
 
 /**
diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h
index 5c083572c..3bf05786e 100644
--- a/include/odp/api/schedule.h
+++ b/include/odp/api/schedule.h
@@ -93,9 +93,9 @@ int odp_schedule_multi(odp_queue_t *from, uint64_t wait, odp_event_t events[],
  * Pause scheduling
  *
  * Pause global scheduling for this thread. After this call, all schedule calls
- * will return only locally reserved buffers (if any). User can exit the
+ * will return only locally pre-scheduled events (if any). User can exit the
  * schedule loop only after the schedule function indicates that there's no more
- * buffers (no more locally reserved buffers).
+ * (pre-scheduled) events.
  *
  * Must be used with odp_schedule() and odp_schedule_multi() before exiting (or
  * stalling) the schedule loop.
@@ -111,7 +111,16 @@ void odp_schedule_pause(void);
 void odp_schedule_resume(void);
 
 /**
- * Release currently hold atomic context
+ * Release the current atomic context
+ *
+ * This call is valid only for source queues with atomic synchronisation. It
+ * hints the scheduler that the user has completed processing of the critical
+ * section (which depends on the atomic synchronisation). The scheduler is now
+ * allowed to schedule events from the same queue to some other thread.
+ *
+ * Early atomic context release may increase parallelism and thus system
+ * performance, but user needs to design carefully the split into critical vs.
+ * non-critical sections.
  */
 void odp_schedule_release_atomic(void);