@@ -173,6 +173,29 @@ 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 odp_queue_enq_multi() serves two purposes. First, it allows
+ * multiple events to be enqueued via a single call. In addition, it
+ * permits multiple events to partitipate in ordering. When an event
+ * originating from an ordered queue is followed by one or more events
+ * that did not originate from an ordered queue, then these subsequent
+ * events are "chained" to the ordered event such that they participate
+ * in its ordering. This provides a convenient means for an application
+ * to split a packet into multiple packets and have them retain the
+ * relative order of the original packet.
+ *
+ * @note If multiple events originating from ordered queues are passed
+ * to odp_queue_enq_multi() then they (and their associated chains, if
+ * any) are handled independently. To see this, consider the following
+ * array of events: uo1, uo2, o1, uo3, uo4, o2, o3, uo5. When this
+ * array is passed to odp_queue_enq_multi() then unordered events uo1 and
+ * uo2 will be added to queue, then ordered event o1 and the chained
+ * events uo3, and uo4, will be added, then ordered event o2, then ordered
+ * event o3 and the chained event uo5 will be added. In all cases,
+ * unordered events that are chained to ordered events inherit the relative
+ * order of their ordered lead event. Note also that there is no
+ * requirement that the ordered events passed to this routine all originate
+ * from the same ordered queue sine each is treated independently.
*/
int odp_queue_enq_multi(odp_queue_t queue, const odp_event_t events[], int num);
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- include/odp/api/queue.h | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)