@@ -174,6 +174,41 @@ void odp_schedule_release_atomic(void);
int odp_schedule_release_ordered(odp_event_t ev);
/**
+ * Ordered event lock
+ *
+ * Provide reusable in-order serialization for scheduled ordered events. Upon
+ * return the caller is in order with respect to other events originating from
+ * the current ordered context and will retain order until a subsequent
+ * odp_schedule_order_unlock() call is made, or until order is resolved for
+ * the event via a call to odp_queue_enq() or odp_schedule_release_ordered().
+ * If the caller holds multiple events, e.g., as received from
+ * odp_schedule_multi(), then the list of events may only be locked in their
+ * received order to avoid deadlock. That is, if the caller received events
+ * 1, 2, and 3 from odp_schedule_multi(), it is an error to attempt to lock
+ * event 2 before locking and unlocking event 1 or otherwise resolving event
+ * 1's order.
+ *
+ * @param ev The event whose order is to be locked. This event MUST have
+ * originated from an ordered queue.
+ */
+void odp_schedule_order_lock(odp_event_t ev);
+
+/**
+ * Ordered event unlock
+ *
+ * Release an ordered lock previously acquired by odp_schedule_order_lock().
+ * It is an error to attempt to release a lock that had not been previously
+ * acquired for the specified event. Following this call, the thread will
+ * exit the critical section protected by the ordered lock and will resume
+ * parallel execution until the next call to odp_schedule_order_lock() for
+ * that event, or until the event's order is resolved by a call to
+ * odp_queue_enq() or odp_schedule_release_ordered().
+ *
+ * @param ev The event whose order is to be unlocked.
+ */
+void odp_schedule_order_unlock(odp_event_t ev);
+
+/**
* Copy order from one event to another
*
* This call copies the order associated with an event originating from an
@@ -181,14 +216,19 @@ int odp_schedule_release_ordered(odp_event_t ev);
* associated ordering at input to the call. If the target is ordered, the
* prior ordering must first be released by an odp_schedule_release_ordered()
* call. Successfuly copying an order implicitly sets the order sustain
- * attribute for the src_event as if odp_schedule_order_sustain() were called
- * for it.
+ * attribute for the src_event as if odp_schedule_order_sustain_set() were
+ * called for it.
*
* @param src_event Event whose ordering is to be copied
* @param dst_event Event to receive the same ordering as src_event.
*
* @retval 0 Success
* @retval <0 Failure. Order not copied.
+ *
+ * @note If multiple events share the same order as a result of
+ * odp_schedule_order_copy(), only one of them should attempt to lock the
+ * order via calls to odp_schedule_order_lock(). Results are undefined if this
+ * restriction is not observed.
*/
int odp_schedule_order_copy(odp_event_t src_event, odp_event_t dst_event);
@@ -336,43 +376,6 @@ int odp_schedule_group_leave(odp_schedule_group_t group,
int odp_schedule_group_count(odp_schedule_group_t group);
/**
- * Initialize ordered context lock
- *
- * Initialize an ordered queue context lock. The lock can be associated only
- * with ordered queues and used only within an ordered synchronization context.
- *
- * @param queue Ordered queue
- * @param lock Ordered context lock
- *
- * @retval 0 on success
- * @retval <0 on failure
- */
-int odp_schedule_olock_init(odp_queue_t queue, odp_schedule_olock_t *lock);
-
-/**
- * Acquire ordered context lock
- *
- * This call is valid only when holding an ordered synchronization context. The
- * lock is used to protect a critical section that is executed within an
- * ordered context. Threads enter the critical section in the order determined
- * by the context (source queue). Lock ordering is automatically skipped for
- * threads that release the context instead of calling the lock.
- *
- * @param lock Ordered context lock
- */
-void odp_schedule_olock_lock(odp_schedule_olock_t *lock);
-
-/**
- * Release ordered context lock
- *
- * This call is valid only when holding an ordered synchronization context.
- * Release a previously locked ordered context lock.
- *
- * @param lock Ordered context lock
- */
-void odp_schedule_olock_unlock(odp_schedule_olock_t *lock);
-
-/**
* @}
*/
Additional scheduler APIs: odp_schedule_order_lock() odp_schedule_order_unlock() Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- include/odp/api/schedule.h | 81 ++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 39 deletions(-)