From patchwork Tue Aug 25 00:14:24 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 52658 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-lb0-f199.google.com (mail-lb0-f199.google.com [209.85.217.199]) by patches.linaro.org (Postfix) with ESMTPS id A6FE222DD4 for ; Tue, 25 Aug 2015 00:18:34 +0000 (UTC) Received: by lbcue2 with SMTP id ue2sf45548248lbc.1 for ; Mon, 24 Aug 2015 17:18:33 -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=b/w9pEsSP1CdfncXSos7CiS6mc3bsrFXgVVuo2sjxlk=; b=WYV2TLB1pGH7iOIJtc7gVTgy/SO9UMg+lAyWM5YNBqq2vclZLuUItsDKQoQAmbWOOK ocnKgZuoeC14FAFAU/gtc2BGm2pIHwF2yca7dKIH8KXfYwXyf9eTKqCIIB4vM7uhqm/k 1IUA8OuWdDYwQsk66MKydcr2h4vqoN5ClTxQO42CSgiGodS08TUWGaV1ZUGU/3c+6FA6 2lLvZizib6LstPywlejLyTvMwXBQ/uGOYsmsIuI0SOE5bQCf+l3anBaiDXwH7p3tL9Ps FxnXhYpjJRQ9TlHgEOpU37pCHTojx/Pd6/6G4uxwh3mbBcc2EjeTAG4YmLqpOZLJzUvX 357w== X-Gm-Message-State: ALoCoQkbGP7QrX6dMfcA8mtBYePJjoz+DV/2qlv2omN5djCST33xrIJEKcfwsXjCF8iM0pG0xUDH X-Received: by 10.152.6.103 with SMTP id z7mr7567756laz.8.1440461913723; Mon, 24 Aug 2015 17:18:33 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.21.100 with SMTP id u4ls107422lae.51.gmail; Mon, 24 Aug 2015 17:18:33 -0700 (PDT) X-Received: by 10.152.37.137 with SMTP id y9mr19305797laj.105.1440461913325; Mon, 24 Aug 2015 17:18:33 -0700 (PDT) Received: from mail-la0-f48.google.com (mail-la0-f48.google.com. [209.85.215.48]) by mx.google.com with ESMTPS id jt9si1810419lab.77.2015.08.24.17.18.33 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 24 Aug 2015 17:18:33 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.48 as permitted sender) client-ip=209.85.215.48; Received: by labia3 with SMTP id ia3so23528267lab.3 for ; Mon, 24 Aug 2015 17:18:33 -0700 (PDT) X-Received: by 10.112.166.106 with SMTP id zf10mr22986757lbb.36.1440461912988; Mon, 24 Aug 2015 17:18:32 -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 yc8csp2812337lbb; Mon, 24 Aug 2015 17:18:31 -0700 (PDT) X-Received: by 10.107.137.217 with SMTP id t86mr26934907ioi.103.1440461911350; Mon, 24 Aug 2015 17:18:31 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id nt6si8637299igb.79.2015.08.24.17.18.28; Mon, 24 Aug 2015 17:18:31 -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 F042361EEC; Tue, 25 Aug 2015 00:18:27 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 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 [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id D5A6461F21; Tue, 25 Aug 2015 00:14:58 +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 6D43961F1D; Tue, 25 Aug 2015 00:14:45 +0000 (UTC) Received: from mail-ob0-f178.google.com (mail-ob0-f178.google.com [209.85.214.178]) by lists.linaro.org (Postfix) with ESMTPS id 55F5661F06 for ; Tue, 25 Aug 2015 00:14:41 +0000 (UTC) Received: by obbhe7 with SMTP id he7so128531671obb.0 for ; Mon, 24 Aug 2015 17:14:41 -0700 (PDT) X-Received: by 10.60.16.228 with SMTP id j4mr24917251oed.59.1440461680871; Mon, 24 Aug 2015 17:14:40 -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 p10sm11084442oev.0.2015.08.24.17.14.40 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 24 Aug 2015 17:14:40 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Mon, 24 Aug 2015 19:14:24 -0500 Message-Id: <1440461669-18578-7-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1440461669-18578-1-git-send-email-bill.fischofer@linaro.org> References: <1440461669-18578-1-git-send-email-bill.fischofer@linaro.org> X-Topics: patch Subject: [lng-odp] [API-NEXT PATCHv2 06/11] 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.48 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 Add the following APIs for ordered queues: odp_queue_enq_sustain() odp_queue_enq_multi_sustain() These are used to enqueue events without resolving order when operating in an ordered context. 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