From patchwork Mon Jan 30 20:38:14 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 92917 Delivered-To: patch@linaro.org Received: by 10.140.20.99 with SMTP id 90csp1622822qgi; Mon, 30 Jan 2017 12:38:30 -0800 (PST) X-Received: by 10.36.123.136 with SMTP id q130mr17357650itc.25.1485808710800; Mon, 30 Jan 2017 12:38:30 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id m204si11549658ioe.134.2017.01.30.12.38.29; Mon, 30 Jan 2017 12:38:30 -0800 (PST) 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 sp=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id BDD4662CF8; Mon, 30 Jan 2017 20:38:29 +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=-1.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, 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 3F61D60EA5; Mon, 30 Jan 2017 20:38:23 +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 A278960F31; Mon, 30 Jan 2017 20:38:20 +0000 (UTC) Received: from mail-oi0-f47.google.com (mail-oi0-f47.google.com [209.85.218.47]) by lists.linaro.org (Postfix) with ESMTPS id 95B3060CDE for ; Mon, 30 Jan 2017 20:38:19 +0000 (UTC) Received: by mail-oi0-f47.google.com with SMTP id j15so202358886oih.2 for ; Mon, 30 Jan 2017 12:38:19 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=cZ8cKAJVVt3w89bIsm1cAQpAkbSJFdolp+kKOh+uHKo=; b=nQEd2s5CInh3FZ1uDmat6a4c9CyrMQBFgfQKJbhqs+rlkM9dHJ1Tzv5rVLhtyuoXXk gc57U3z4/jvuIM6bSnNr+00qcp75cJpY+kWUmsH/KldyfG00kE9rcn8kbwWu/wnWeJEt 0nrtT7Y0hHEBoVGUCxQ10F6s1FPJ6Z1if3d9z0gKnseu/wp6N2VVQwdp2wmcaxz8WQlI WSz341ynpLi+EQ9hNP2x30Ts0SBsOl93IuI8X0Xqo0CJDNVZBFtLBA+4xs6pHOd7y2OZ sipkKdp6cJ/FzJOw3fcRF6H/AvERTHeAk9uDGQ83Het/MCuGzxnWpDbI9sbFQHQgeTfb HXzQ== X-Gm-Message-State: AIkVDXIJRavJhXiPcDWczG8XqUxRhe03N8Qg0EIPyc7PYX1PyADG6idBOzjr1/cvDQGCMfDYMHM= X-Received: by 10.202.71.137 with SMTP id u131mr13711873oia.111.1485808698957; Mon, 30 Jan 2017 12:38:18 -0800 (PST) Received: from localhost.localdomain (cpe-70-121-83-241.austin.res.rr.com. [70.121.83.241]) by smtp.gmail.com with ESMTPSA id z34sm7493997ota.35.2017.01.30.12.38.18 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 30 Jan 2017 12:38:18 -0800 (PST) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Mon, 30 Jan 2017 14:38:14 -0600 Message-Id: <20170130203814.24598-1-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.9.3 Subject: [lng-odp] [API-NEXT PATCH] doc: userguide: add section on application portability 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: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Add a section to the ODP User Guide discussing application portability considerations and the use of source and binary portability options provided by ODP. Signed-off-by: Bill Fischofer --- doc/users-guide/users-guide.adoc | 120 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) -- 2.9.3 Reviewed-by: Mike Holmes diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 41c57d1..ead8da5 100755 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -589,6 +589,126 @@ lookup. The lookup function is particularly useful to allow an ODP application that is divided into multiple processes to obtain the handle for the common resource. +== Application Portability Considerations +ODP is designed to support the creation of portable data plane applications +that can easily be run on multiple target platforms while at the same time +fully exploit hardware acceleration capabilities native to whatever platform +it is running on. This section discusses tradeoffs that application writers +should consider when using ODP. + +First, it should be noted that portability is not an absolute good nor is it a +single-valued attribute (application is portable or is not portable). While +any application can be ported from one platform to another the real question +is: _at what cost?_ Costs can be measured in two dimensions: The level of +effort needed to port, and the resulting performance differences seen due to +the port. Ideally an application should be portable between platforms with +minimal effort and equally minimal performance impact. While ODP is designed +to support this ideal, each application must assess what its goals are in this +area and how best to use ODP to achieve these goals. + +=== Portability and Coexistence +Because ODP offers a programming _framework_ rather than a programming +_environment_, it is designed to be able to work alongside APIs offered by +other frameworks with minimual interference. Therefore when we speak of +portability in an ODP context, we of necessity speak of portability of those +portions of the application that make use of ODP APIs. If an application uses +non-ODP APIs then those must be taken into consideration as well when +assessing the portability of the entire application. For many applications, it +suffices to isolate certain non-portable code to a few areas of the application +with the result that the application is significantly more portable than it +would be without using ODP. Especially when dealing with existing applications +that run in production environments, ODP may well be introduced in an +incremental manner with the result being that the application becomes more +portable only over time. + +=== Source vs. Binary Portability +ODP has been designed to support both source and binary portability. Source +portability is intrinsic to the ODP API specification itself. Any application +written to the ODP API specification will be source portable between any +conforming ODP implementation with at most a recompile. This is because ODP +APIs do not expose implementation details or internal structures that may vary +from platform to platform. + +For platforms that share a common Instruction Set Architecture (ISA), ODP can +also offer binary portability via the specification of an Application Binary +Interface (ABI). This is especially useful in a Network Function +Virtualization (NFV) environment where a data plane application may be +developed and compiled on one platform for distribution and then deployed on +many different platforms by an NFV Orchestrator function. + +=== ODP Application Profiles +To assist in meeting these needs, ODP offers two distinct _application +profiles_ that are designed to characterize the needs of different types of +data plane applications: the _Embedded Profile_ and the _Cloud Profile_. + +==== Embedded Profile +The ODP Embedded Profile is designed to support applications that wish to +target a specific platform and achieve optimal performance on that platform +and where source code portability is sufficient. If such applications need to +support more than one platform then they simply need to be recompiled against +the ODP implementation for that platform. + +Embedded applications will typically work with a copy of ODP downloaded from +a git repository so that it can be configured for the application's precise +needs. To specify that the application wishes to use the embedded profile: + +`./configure --enable-abi-compat=no ...` + +should be used as part of the ODP configuration options. This allows +applications to use inline forms of ODP APIs to give optimal performance +on this platform, and may include additional optimizations that preclude +binary portability to other platforms. The result is a binary that will achieve +maximum performance on a given target platform and that can be ported to +other platforms with a recompile. + +==== Cloud Profile +By contrast, the ODP Cloud Profile is designed to support applications that +wish to be platform-agnostic and be binary compatible across all platforms +sharing this ABI. Any ODP implementation included in a Linux distribution will +be configured for the cloud profile, so no additional action is required on +the part of applications when compiling against a distributed copy of ODP (one +that is installed via `sudo apt-get install` or equivalent command). + +When using a copy of ODP downloaded from a repository, the cloud profile is +selected at configure time: + +`./configure --enable-abi-compat=yes ...` + +Note that `--enable-abi-compat=yes` is the default, so this need not be +specified. Unless `no` is specified for this option, the result will be +applications designed to run in the cloud profile. + +=== ABI Characteristics +An ABI consists of several conventions that ensure that a program compiled +against one ODP implementation can run unchanged on another platform that +has a possibly very different ODP implementation without requiring +recompilation. These include: + +* A set of function calling conventions that define how functions call other +functions, pass parameters, and receive returned results. These are typically +specified by the Operating System (_e.g.,_ Linux) and are independent of ODP. + +* Avoiding the use of inline expansions for any ODP API. This ensures that +differing ODP implementations can maintain their different internals without +these differences being visible to the application. + +* Agreement as to the size and alignment of ODP abstract datatypes used by all +ODP implementations sharing this ABI definition. This means that, for example, +the size of an `odp_packet_t` handle is the same across all members of the +ABI. Since these handles are opaque, it doesn't matter if their structure +differs between ODP implementations since applications never reference these +possibly different internals. + +Note that an ABI definition exists within a specific Instruction Set +Architecture (ISA), such as x86-64 or AArch64. Binaries cannot directly port +between ISAs--that requires a recompilation. + +Each ODP implementation will identify which ABI definition it supports, if any. +When compiling against an ODP implementation in ABI compabitilty mode, the +resulting binary is automatically binary compatible with all other ODP +implementations that share this ABI. For example, for the x86-64 ISA, both +the `odp-linux` and `odp-dpdk` implemtations are a common ABI. + == Shared memory === Allocating shared memory Blocks of shared memory can be created using the `odp_shm_reserve()` API