@@ -156,10 +156,38 @@ void *odp_queue_context(odp_queue_t queue);
*
* @retval 0 on success
* @retval <0 on failure
+ *
+ * @note When operating in an ordered context a successful call to
+ * odp_queue_enq() resolves order. This means that further calls to ODP APIs
+ * that oeprate on ordered contexts will no longer provide ordered semantics.
*/
int odp_queue_enq(odp_queue_t queue, odp_event_t ev);
/**
+ * Queue enqueue without order resolution
+ *
+ * Enqueue the 'ev' on 'queue'. On failure the event is not consumed, the caller
+ * has to take care of it. On success, order is not resolved.
+ *
+ * @param queue Queue handle
+ * @param ev Event handle
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
+ *
+ * @note When operating in an ordered context this call differs from
+ * odp_queue_enq() in that it does not resolve order, meaning that the caller
+ * is still running in an ordered context. This means that the caller may
+ * continue to make calls to ODP APIs that operate on ordered contexts. A
+ * typical use for odp_queue_enq_sustain() is to insert an event into an
+ * ordered flow without resolving order. This permits, for example, an
+ * application to divide a packet into multiple segments for MTU or other
+ * purposes and have the segments preserve the relative order of the
+ * originating packet.
+ */
+int odp_queue_enq_sustain(odp_queue_t queue, odp_event_t ev);
+
+/**
* Enqueue multiple events to a queue
*
* Enqueue the events from 'events[]' on 'queue'. A successful call returns the
@@ -173,10 +201,46 @@ int odp_queue_enq(odp_queue_t queue, odp_event_t ev);
*
* @return Number of events actually enqueued (0 ... num)
* @retval <0 on failure
+ *
+ * @note When operating in an ordered context, all events passed to
+ * odp_queue_enq_multi() are added to the target queue as a block in context
+ * order. Upon successful enqueue, the ordered context is considered resolved,
+ * meaning that further ODP APIs that operate in an ordered context should not
+ * be made. If they are called, they will not provide ordered semantics. For
+ * example, following this call a call to odp_schedule_release_ordered() is a
+ * no-op since the caller is no longer running in an ordered
+ * context. Similarly, a call to odp_schedule_order_lock() will do nothing,
+ * and further enqueue calls will be unordered since the caller no longer
+ * holds and ordered context.
*/
int odp_queue_enq_multi(odp_queue_t queue, const odp_event_t events[], int num);
/**
+ * Enqueue multiple events to a queue without order resolution
+ *
+ * Enqueue the events from 'events[]' on 'queue'. A successful call returns the
+ * actual number of events enqueued. If return value is less than 'num', the
+ * remaining events at the end of events[] are not consumed, and the caller
+ * has to take care of them.
+ *
+ * @param queue Queue handle
+ * @param[in] events Array of event handles
+ * @param num Number of event handles to enqueue
+ *
+ * @return Number of events actually enqueued (0 ... num)
+ * @retval <0 on failure
+ *
+ * @note When operating in an ordered context, all events passed to
+ * odp_queue_enq_multi_sustain() are added to the target queue as a block in
+ * context order. Upon successful enqueue, the ordered context is not
+ * resolved, meaning that further ODP API calls that operate in an ordered
+ * context may be made and these will continue to be part of the current
+ * ordered context.
+ */
+int odp_queue_enq_multi_sustain(odp_queue_t queue,
+ const odp_event_t events[], int num);
+
+/**
* Queue dequeue
*
* Dequeues next event from head of the queue. Cannot be used for
Adds the following APIs for working with ordered queues: odp_queue_enq_sustain() odp_queue_enq_multi_sustain() Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- include/odp/api/queue.h | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+)