From patchwork Wed Feb 18 15:19:28 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Petri Savolainen X-Patchwork-Id: 44783 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-lb0-f197.google.com (mail-lb0-f197.google.com [209.85.217.197]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 379AF21554 for ; Wed, 18 Feb 2015 15:20:33 +0000 (UTC) Received: by lbdu10 with SMTP id u10sf1252074lbd.3 for ; Wed, 18 Feb 2015 07:20:31 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:from:to:date:message-id: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=BM+pYcOgSoIwaOVWJJDDRZneEjetjfW6uxkw7wyl2Kk=; b=cGPa/JnPIkTfezJzoMN9U/5tjxyvl8CzVyxwF5y+uXwxpv3vs1QWyYaJB/oJA+fpM9 gN2CZTL2/PLCMa4W9H8HbKjdCCZ8rqwGI85Uz83UDtPJUZX0ImJfuoZfIBwyBM3cPvrZ JEbT3aI54Kki4o/JUw/MP8hF/yxm4XcztlHTdkMXr6AM2EPdEuliSCzxxGJIGVdwet6M De7jti1j/NQah5ebql+sWTjX70TzzZtAimHHoaYtfwTZx3yXlwC8e/ezmbJTK0togXsH 9jmBkj8YOxsJoWS9vDZxs5p7T1Wk90Zern9fWHlcBPNpUQKAt8JyyBPr2aMa74ywQB1m PACw== X-Gm-Message-State: ALoCoQko+d9ArsgqXVjhsUGFcPYRHmc8grdWtb8TTg3xQBKZ3QvdYL2j0fNurRoQv2QBeCZObt0y X-Received: by 10.180.94.134 with SMTP id dc6mr427753wib.2.1424272831803; Wed, 18 Feb 2015 07:20:31 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.204.12 with SMTP id ku12ls25175lac.105.gmail; Wed, 18 Feb 2015 07:20:31 -0800 (PST) X-Received: by 10.152.18.133 with SMTP id w5mr33835566lad.51.1424272831632; Wed, 18 Feb 2015 07:20:31 -0800 (PST) Received: from mail-lb0-f174.google.com (mail-lb0-f174.google.com. [209.85.217.174]) by mx.google.com with ESMTPS id wm7si13076826lbb.72.2015.02.18.07.20.31 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 18 Feb 2015 07:20:31 -0800 (PST) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.174 as permitted sender) client-ip=209.85.217.174; Received: by lbvp9 with SMTP id p9so1759997lbv.3 for ; Wed, 18 Feb 2015 07:20:31 -0800 (PST) X-Received: by 10.152.21.100 with SMTP id u4mr20312729lae.41.1424272831549; Wed, 18 Feb 2015 07:20:31 -0800 (PST) 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.35.133 with SMTP id h5csp2914911lbj; Wed, 18 Feb 2015 07:20:30 -0800 (PST) X-Received: by 10.229.125.133 with SMTP id y5mr1892706qcr.17.1424272829897; Wed, 18 Feb 2015 07:20:29 -0800 (PST) Received: from ip-10-35-177-41.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id l90si21534890qgd.26.2015.02.18.07.20.28 (version=TLSv1 cipher=RC4-SHA bits=128/128); Wed, 18 Feb 2015 07:20:29 -0800 (PST) Received-SPF: none (google.com: lng-odp-bounces@lists.linaro.org does not designate permitted sender hosts) client-ip=54.225.227.206; Received: from localhost ([127.0.0.1] helo=ip-10-35-177-41.ec2.internal) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1YO6QL-0008KH-Hu; Wed, 18 Feb 2015 15:20:25 +0000 Received: from mail-qa0-f48.google.com ([209.85.216.48]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1YO6QF-0008KC-W6 for lng-odp@lists.linaro.org; Wed, 18 Feb 2015 15:20:20 +0000 Received: by mail-qa0-f48.google.com with SMTP id dc16so1177000qab.7 for ; Wed, 18 Feb 2015 07:20:14 -0800 (PST) X-Received: by 10.140.195.195 with SMTP id q186mr928890qha.103.1424272814747; Wed, 18 Feb 2015 07:20:14 -0800 (PST) Received: from mcpro03.emea.nsn-net.net (ec2-23-23-178-99.compute-1.amazonaws.com. [23.23.178.99]) by mx.google.com with ESMTPSA id 7sm7875137qhv.8.2015.02.18.07.20.11 (version=TLSv1.1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 18 Feb 2015 07:20:13 -0800 (PST) From: Petri Savolainen To: lng-odp@lists.linaro.org Date: Wed, 18 Feb 2015 17:19:28 +0200 Message-Id: <1424272768-15154-1-git-send-email-petri.savolainen@linaro.org> X-Mailer: git-send-email 2.3.0 X-Topics: patch Subject: [lng-odp] [PATCH v3] api: scheduler: atomic and ordered definitions X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.14 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-bounces@lists.linaro.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: petri.savolainen@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.217.174 as permitted sender) smtp.mail=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 Improved documentation and definition of atomic and ordered queue synchronisation. Signed-off-by: Petri Savolainen Reviewed-by: Ola Liljedahl --- This is the ordered queue definition (in patch format) promised in the call yesterday. --- include/odp/api/queue.h | 25 +++++++++++++++++++++++-- include/odp/api/schedule.h | 15 ++++++++++++--- 2 files changed, 35 insertions(+), 5 deletions(-) diff --git a/include/odp/api/queue.h b/include/odp/api/queue.h index 9519edf..6a8b15f 100644 --- a/include/odp/api/queue.h +++ b/include/odp/api/queue.h @@ -104,16 +104,37 @@ extern "C" { /** * @def ODP_SCHED_SYNC_NONE * Queue not synchronised + * + * The scheduler does not provide event synchronisation or ordering, only load + * balancing. Events can be scheduled freely to multiple threads for concurrent + * processing. */ /** * @def ODP_SCHED_SYNC_ATOMIC - * Atomic queue + * Atomic queue synchronisation + * + * Events from an atomic queue can be scheduled only to a single thread at a + * time. The thread is guaranteed to have exclusive (atomic) access to the + * associated queue context and event ordering is maintained. This enables the + * user to avoid SW synchronisation for those two. + * + * The atomic queue is dedicated to the thread until it requests another event + * from the scheduler (which implicitly releases the queue) or calls + * odp_schedule_release_atomic(), which allows the scheduler to release the + * queue immediately. */ /** * @def ODP_SCHED_SYNC_ORDERED - * Ordered queue + * Ordered queue synchronisation + * + * Events from an ordered queue can be scheduled to multiple threads for + * concurrent processing. The source queue (dequeue) ordering is maintained when + * events are enqueued to their destination queue(s) before another schedule + * call. Events from the same (source) queue appear in their original order + * when dequeued from a destination queue. The destination queue can have any + * queue type and synchronisation method. */ /** diff --git a/include/odp/api/schedule.h b/include/odp/api/schedule.h index 5c08357..3bf0578 100644 --- a/include/odp/api/schedule.h +++ b/include/odp/api/schedule.h @@ -93,9 +93,9 @@ int odp_schedule_multi(odp_queue_t *from, uint64_t wait, odp_event_t events[], * Pause scheduling * * Pause global scheduling for this thread. After this call, all schedule calls - * will return only locally reserved buffers (if any). User can exit the + * will return only locally pre-scheduled events (if any). User can exit the * schedule loop only after the schedule function indicates that there's no more - * buffers (no more locally reserved buffers). + * (pre-scheduled) events. * * Must be used with odp_schedule() and odp_schedule_multi() before exiting (or * stalling) the schedule loop. @@ -111,7 +111,16 @@ void odp_schedule_pause(void); void odp_schedule_resume(void); /** - * Release currently hold atomic context + * Release the current atomic context + * + * This call is valid only for source queues with atomic synchronisation. It + * hints the scheduler that the user has completed processing of the critical + * section (which depends on the atomic synchronisation). The scheduler is now + * allowed to schedule events from the same queue to some other thread. + * + * Early atomic context release may increase parallelism and thus system + * performance, but user needs to design carefully the split into critical vs. + * non-critical sections. */ void odp_schedule_release_atomic(void);