From patchwork Thu May 19 04:05:33 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 68066 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp2978947qge; Wed, 18 May 2016 21:06:09 -0700 (PDT) X-Received: by 10.55.54.85 with SMTP id d82mr11719113qka.57.1463630769818; Wed, 18 May 2016 21:06:09 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id q21si10300250qki.196.2016.05.18.21.06.09; Wed, 18 May 2016 21:06:09 -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 6748661677; Thu, 19 May 2016 04:06:09 +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 81F0F6166F; Thu, 19 May 2016 04:05:41 +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 9F5E361663; Thu, 19 May 2016 04:05:38 +0000 (UTC) Received: from mail-oi0-f53.google.com (mail-oi0-f53.google.com [209.85.218.53]) by lists.linaro.org (Postfix) with ESMTPS id 845DA61661 for ; Thu, 19 May 2016 04:05:37 +0000 (UTC) Received: by mail-oi0-f53.google.com with SMTP id x19so109830648oix.2 for ; Wed, 18 May 2016 21:05:37 -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:in-reply-to :references; bh=g4WzRW+K4FaPvhBkwqcErTcrhrdegUaqOUm1efIagXs=; b=U5P3iv9dqfU5xvvF5UQjvxOj2h5HmMl4njvXtovUiYRm6GnLpYmUyaG4LaDLQ/7tVC LYNBHkP96lq4nASQvihjtWu0807f158xmswYXuiVil8lcX4N0QeijVkDeL4Ol84OFcVP K2h1XeM5SMvvh7MRWtcI18znzbVPKUUeBUGqQpcmrLfpC6VIfdZrZmxNp4ER9aVLg+hx E4ptJv1ArbVjiGr5/GyMQlxP/6v/Fp+WTzYdxU6dfqHMeiJEXiiCsWHconz1wVDrX4JD xx/uCyTF9WpoUx42KgOcoJNLCGOYvYRFfqHd1vZ1pnNKJ6Rn9vHQVAd7kfWLGGPian/9 4jGQ== X-Gm-Message-State: AOPr4FUi2svaEn0YLGbrQ15QyYLz4cxid5B4u6ZL09W8Gqm4TIkf28Om6D5QpAodd3rj1XHMO38= X-Received: by 10.157.17.27 with SMTP id g27mr6785208ote.40.1463630737075; Wed, 18 May 2016 21:05:37 -0700 (PDT) Received: from localhost.localdomain (cpe-66-68-129-43.austin.res.rr.com. [66.68.129.43]) by smtp.gmail.com with ESMTPSA id u11sm3294565oie.29.2016.05.18.21.05.36 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 18 May 2016 21:05:36 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Wed, 18 May 2016 23:05:33 -0500 Message-Id: <1463630733-30902-2-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1463630733-30902-1-git-send-email-bill.fischofer@linaro.org> References: <1463630733-30902-1-git-send-email-bill.fischofer@linaro.org> X-Topics: patch Subject: [lng-odp] [PATCH 2/2] doc: userguide: add notes on threads and addressing scope 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" Expand thread section to explain rationale for threads not being ODP objects and how this relates to addressability considerations for shared resources. Signed-off-by: Bill Fischofer --- doc/users-guide/users-guide.adoc | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 745b85f..fbe745f 100755 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -288,6 +288,17 @@ _thread mask_ and _scheduler group_ that determine where they can run and the type of work that they can handle. These will be discussed in greater detail later. +It is important to note that threads are not ODP objects. This is intentional. +The ODP API is designed to abstract objects and functions that are relevant to +data plane programming, and that may find accelerated implementation across +diverse platforms and architectures. It is not, however, designed to abstract +operating system objects and concepts. As a result while ODP _refers_ to +threads, it does not _define_ threads in terms of their creation or management +from an operating system perspective. ODP does provide _helper_ functions that +permit Posix threads to be created and managed, however. Applications are free +to use these helpers or to manage threads in some other manner of their +choosing. + === Event Events are what threads process to perform their work. Events can represent new work, such as the arrival of a packet that needs to be processed, or they @@ -332,6 +343,9 @@ ODP applications if desired. Shared memory is represented by handles of abstract type `odp_shm_t`. +Note that addressability of shared memory is subject to operating system +considerations as described in <>. + === Buffer A buffer is a fixed sized block of shared storage that is used by ODP components and/or applications to realize their function. Buffers contain @@ -587,10 +601,28 @@ in response to an `odp_queue_deq()` call to get an event from a queue simply indicates that the queue is empty. === Addressing Scope -Unless specifically noted in the API, all ODP resources are global to the ODP -application, whether it runs as a single process or multiple processes. ODP -handles therefore have common meaning within an ODP application but have no -meaning outside the scope of the application. +ODP objects and their associated handles are intended to be global to an ODP +instance, _i.e.,_ to the thread that calls `odp_init_global()` and its +descendants. However, because ODP does not impose a threading model, +responsibility for achieving this is shared with both the ODP implementation as +well as the ODP application. In the odp-linux reference implementation, for +example, threads are assumed to be Posix-style threads that all share a single +address space. As a result, all ODP handles and any addresses derived from +them, are globally sharable throughout the ODP instance. Other implementations +may offer the same capabilities or may use a process-based threading model in +which individual threads execute in distinct address spaces. + +If a platform uses process that follow a Unix-style `fork()` model of process +creation, then for best portability ODP applications should be designed so +that any ODP resource creation (_e.g.,_ pools, shared memory objects, pktios) +are created during initialization by the thread that creates the ODP instance +by calling `odp_init_global()` _before_ any other threads are +created/launched. This will allow any common objects to be visible in forked +processes. + +If a platform uses some other process addressing model, then refer to that +platform for recommendations to achieve application-desired shared +addressability. === Resources and Names Many ODP resource objects, such as pools and queues, support an