From patchwork Thu May 19 12:48:49 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christophe Milard X-Patchwork-Id: 68121 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp3152471qge; Thu, 19 May 2016 04:50:18 -0700 (PDT) X-Received: by 10.140.181.70 with SMTP id c67mr13887136qha.20.1463658617665; Thu, 19 May 2016 04:50:17 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id h188si12132766qkc.19.2016.05.19.04.50.17; Thu, 19 May 2016 04:50:17 -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; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=pass (p=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 52633617D6; Thu, 19 May 2016 11:50:17 +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 8FAAB61645; Thu, 19 May 2016 11:50:11 +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 43DA46164C; Thu, 19 May 2016 11:50:09 +0000 (UTC) Received: from mail-lf0-f51.google.com (mail-lf0-f51.google.com [209.85.215.51]) by lists.linaro.org (Postfix) with ESMTPS id 77EE0610DE for ; Thu, 19 May 2016 11:50:03 +0000 (UTC) Received: by mail-lf0-f51.google.com with SMTP id m64so35184292lfd.1 for ; Thu, 19 May 2016 04:50:03 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=CQGCWZEf5n+szgTe5vf9uGhhIE8Aq8izRc3vkjoPnZY=; b=ZeKZlSTiMH3waGc2IwDTLHnqRZ1BrRCCDn5bJuU9aSDybFYeCPLJpuzsJXVh/asU4d Lyu9z+wDZRsAl6yxP3pQdkyIdfIBRn56HfBoqAbtkEE8hxruoXU5v0oFvqFrSrz6wkMP AlG9Dtsx5g63rXfbBFTKxtJveHNPxY7KKOYxZNdD+JC2t9nX0kcr3j3TZ4DneAqQPxh5 ckqgPi0k9h+wH8eaT8D0Pgzb/rABmz5L0ofEELx09ketjKgFSlaI3YpTfFgyJSIi6nVI EF1eK8XEcMg59HoXoXetsLaCxi1AJgH9TP0qCyjoeR+3xHE1lWpDH8/j+F9atSH34QvG yWgw== X-Gm-Message-State: AOPr4FUao/Bjlpl9L9MSXoUfZVi+KefcFDe9KODxVyiYGA9UY2XcX2Hr4u8q3EieOiRYrP2E44Q= X-Received: by 10.112.169.65 with SMTP id ac1mr4351810lbc.92.1463658601648; Thu, 19 May 2016 04:50:01 -0700 (PDT) Received: from erachmi-ericsson.ki.sw.ericsson.se (c-83-233-90-46.cust.bredband2.com. [83.233.90.46]) by smtp.gmail.com with ESMTPSA id jw6sm2285768lbc.13.2016.05.19.04.50.00 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 19 May 2016 04:50:00 -0700 (PDT) From: Christophe Milard To: bill.fischofer@linaro.org, mike.holmes@linaro.org, petri.savolainen@nokia.com, lng-odp@lists.linaro.org Date: Thu, 19 May 2016 14:48:49 +0200 Message-Id: <1463662129-21078-1-git-send-email-christophe.milard@linaro.org> X-Mailer: git-send-email 2.5.0 X-Topics: patch Subject: [lng-odp] [PATCHv2] doc: proper definition of ODP thread X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" 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" Making clear which ODP instance a thread is joining when calling odp_init_local(). Signed-off-by: Christophe Milard --- doc/glossary.adoc | 24 +++++++++++++++++------- include/odp/api/spec/init.h | 4 ++++ 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/doc/glossary.adoc b/doc/glossary.adoc index 2c0de24..209a292 100644 --- a/doc/glossary.adoc +++ b/doc/glossary.adoc @@ -10,7 +10,8 @@ control thread:: operating system house keeping tasks but will be scheduled by it and may receive interrupts. ODP instantiation process:: - The process calling `odp_init_global()`, which is probably the + The OS "flow of execution" (i.e. OS process or OS thread) + calling `odp_init_global()`, which is probably the first process which is started when an ODP application is started. There is one single such process per ODP instantiation. thread:: @@ -19,12 +20,21 @@ thread:: ODP thread:: An ODP thread is a flow of execution that belongs to ODP: Any "flow of execution" (i.e. OS process or OS thread) calling - `odp_init_global()`, or `odp_init_local()` becomes an ODP thread. - This definition currently limits the number of ODP instances on a given - machine to one. In the future `odp_init_global()` will return something - like an ODP instance reference and `odp_init_local()` will take such - a reference in parameter, allowing threads to join any running ODP instance. - Note that, in a Linux environment an ODP thread can be either a Linux + `odp_init_local()` becomes an ODP thread. + On OSes supporting process hierarchy (e.g. linux), any "flow of execution" + calling `odp_init_local()` becomes an ODP thread of the ODP instance whose + ODP instantiation process is an ancestor of (or same as) this + "flow of execution". + This means that on these OSes, all ODP threads are descendant of (or + same as) their ODP instantiation process. + This also means that on these OSes, the ODP instance passed as + `odp_init_local()` parameter is redundant, as the ODP instance the thread + belongs to is actually already defined by the process hierarchy. + This parameter is only meaningful on OSes which do not support process + hierarchy. The instance number should nevertheless be set to the correct + value (matching the ancestor ODP instance on OS supporting process + hierarchy). + Note that, e.g. in a Linux environment, an ODP thread can be either a Linux process or a linux thread (i.e. a linux process calling `odp_init_local()` will be referred as ODP thread, not ODP process). event:: diff --git a/include/odp/api/spec/init.h b/include/odp/api/spec/init.h index fec6774..7592669 100644 --- a/include/odp/api/spec/init.h +++ b/include/odp/api/spec/init.h @@ -234,6 +234,10 @@ int odp_term_global(odp_instance_t instance); * All threads must call this function before calling any other ODP API * functions. The instance parameter specifies which ODP instance the thread * joins. A thread may be simultaneously part of single ODP instance only. + * On OSes supporting process hierarchy (e.g linux), this parameter is actually + * redundant as all ODP threads have to be descendant of their ODP + * instantiation process: In these case, the instance parameter must match the + * ODP instance of the ancestor process which called ODP_init_global() * * @param instance Instance handle * @param thr_type Thread type