From patchwork Mon Aug 24 04:06:32 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 52616 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-la0-f69.google.com (mail-la0-f69.google.com [209.85.215.69]) by patches.linaro.org (Postfix) with ESMTPS id 69AA220AF6 for ; Mon, 24 Aug 2015 04:09:13 +0000 (UTC) Received: by labpx14 with SMTP id px14sf37455090lab.1 for ; Sun, 23 Aug 2015 21:09:12 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:delivered-to:from:to:date :message-id:in-reply-to:references:subject:precedence:list-id :list-unsubscribe:list-archive:list-post:list-help:list-subscribe :mime-version:content-type:content-transfer-encoding:errors-to :sender:x-original-sender:x-original-authentication-results :mailing-list; bh=UIDBsFhO1k6vgzMDYCNjgExcEndwGAn2krWH1TMIrI8=; b=hGLJc+woZykzvJZIfHgl3k1Cpuj0rLTVzFbw7TGIKn994oFLxr56nXgoSSGkSWDGZZ RUU5C58d1DnbUaS6Zq1xbbpSlzihr1Chw4+m2x9R/A+Lh26MMtv10OtTtNKhl7nhpLHc st+BjHW/AmwCkHWb+6AuHT9/6jb+YzfFxL/QDQ26+9O66z9nBwXKy4XjaC4al3GNOnpL L7s8klVcZBtTnjQ9VW+zSmk+rmVdJSz5+5o3yISQjSIW2ziil0VuXiBGROtuA85+I8OD /DkpuVW/TUIXeNR35NFuVgZ566MMcgBu4XfakpB2izI1tGll/HuJJ3L+M9NZh7HwtVFO 9CKA== X-Gm-Message-State: ALoCoQk2aOh/9qKH/Br+dGRIm8U8pnW7xQp+lbIXB3wtJKLFjG03zGcoiXUxAMnItlrsnwue9ULM X-Received: by 10.112.149.39 with SMTP id tx7mr6174202lbb.11.1440389352402; Sun, 23 Aug 2015 21:09:12 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.5.1 with SMTP id o1ls537070lao.12.gmail; Sun, 23 Aug 2015 21:09:12 -0700 (PDT) X-Received: by 10.112.182.42 with SMTP id eb10mr2567508lbc.62.1440389352255; Sun, 23 Aug 2015 21:09:12 -0700 (PDT) Received: from mail-la0-f52.google.com (mail-la0-f52.google.com. [209.85.215.52]) by mx.google.com with ESMTPS id h9si12127571lam.85.2015.08.23.21.09.12 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 23 Aug 2015 21:09:12 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.52 as permitted sender) client-ip=209.85.215.52; Received: by lalv9 with SMTP id v9so69412215lal.0 for ; Sun, 23 Aug 2015 21:09:12 -0700 (PDT) X-Received: by 10.112.209.106 with SMTP id ml10mr18169917lbc.112.1440389352135; Sun, 23 Aug 2015 21:09:12 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.162.200 with SMTP id yc8csp2207142lbb; Sun, 23 Aug 2015 21:09:10 -0700 (PDT) X-Received: by 10.107.14.145 with SMTP id 139mr15781849ioo.37.1440389350206; Sun, 23 Aug 2015 21:09:10 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id y77si6694381ioi.134.2015.08.23.21.09.09; Sun, 23 Aug 2015 21:09:10 -0700 (PDT) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Received: by lists.linaro.org (Postfix, from userid 109) id 2C44F61C9C; Mon, 24 Aug 2015 04:09:09 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252.ec2.internal X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from ip-10-142-244-252.ec2.internal (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 456CE61CEA; Mon, 24 Aug 2015 04:07:00 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id AAF2761CBF; Mon, 24 Aug 2015 04:06:51 +0000 (UTC) Received: from mail-oi0-f50.google.com (mail-oi0-f50.google.com [209.85.218.50]) by lists.linaro.org (Postfix) with ESMTPS id 5220B61C89 for ; Mon, 24 Aug 2015 04:06:45 +0000 (UTC) Received: by oiev193 with SMTP id v193so72899784oie.3 for ; Sun, 23 Aug 2015 21:06:44 -0700 (PDT) X-Received: by 10.202.172.87 with SMTP id v84mr18118222oie.51.1440389204774; Sun, 23 Aug 2015 21:06:44 -0700 (PDT) Received: from Ubuntu15.localdomain (cpe-24-28-70-239.austin.res.rr.com. [24.28.70.239]) by smtp.gmail.com with ESMTPSA id ru8sm9436956oeb.8.2015.08.23.21.06.44 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sun, 23 Aug 2015 21:06:44 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Sun, 23 Aug 2015 23:06:32 -0500 Message-Id: <1440389196-28814-5-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1440389196-28814-1-git-send-email-bill.fischofer@linaro.org> References: <1440389196-28814-1-git-send-email-bill.fischofer@linaro.org> X-Topics: patch Subject: [lng-odp] [API-NEXT PATCH 4/8] api: queue: Ordered queue additional APIs X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: bill.fischofer@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.52 as permitted sender) smtp.mailfrom=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 Adds the following APIs for working with ordered queues: odp_queue_enq_sustain() odp_queue_enq_multi_sustain() Signed-off-by: Bill Fischofer --- include/odp/api/queue.h | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h index ce04eb4..554d9f1 100644 --- a/include/odp/api/queue.h +++ b/include/odp/api/queue.h @@ -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