From patchwork Wed Feb 10 17:48:22 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Christophe Milard X-Patchwork-Id: 61683 Delivered-To: patch@linaro.org Received: by 10.112.43.199 with SMTP id y7csp2754986lbl; Wed, 10 Feb 2016 08:50:26 -0800 (PST) X-Received: by 10.55.75.203 with SMTP id y194mr50436659qka.2.1455123026475; Wed, 10 Feb 2016 08:50:26 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id a7si4480906qhd.24.2016.02.10.08.50.26; Wed, 10 Feb 2016 08:50:26 -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; dkim=neutral (body hash did not verify) header.i=@linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id E1C82617B0; Wed, 10 Feb 2016 16:50:25 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=PmmHqfOa; dkim-adsp=none (unprotected policy); dkim-atps=neutral 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.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, T_DKIM_INVALID, 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 6843861C82; Wed, 10 Feb 2016 16:50:17 +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 A1494617E0; Wed, 10 Feb 2016 16:49:42 +0000 (UTC) Received: from mail-lf0-f44.google.com (mail-lf0-f44.google.com [209.85.215.44]) by lists.linaro.org (Postfix) with ESMTPS id DDA3F617B0 for ; Wed, 10 Feb 2016 16:49:28 +0000 (UTC) Received: by mail-lf0-f44.google.com with SMTP id m1so15702578lfg.0 for ; Wed, 10 Feb 2016 08:49:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-type:content-transfer-encoding; bh=TJ+NCYZmlN/AP7v4D/kqUuR1a/+uvIYblHviVJxfQy4=; b=PmmHqfOaJnD+sNyeh9DvV3b0kGQxRt3IU+R3ZAkpin0J5bxTeJ5dyps35xU+p/Xdgu syH+/O8RaFa+R+TkTpOn2QvUrAvPLXyy2vzstlZ08RQ6vSiYd9XQ9FhOzQNcX8kMt3VB /oUo5aMUZvSl3zw0m2qlq0UeB3Pa86zxr6vTU= 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:mime-version:content-type:content-transfer-encoding; bh=TJ+NCYZmlN/AP7v4D/kqUuR1a/+uvIYblHviVJxfQy4=; b=Eo7qJc+IoxX4hxhV9iLHog6Xo2wSYY5pZnRBLSvG3ndJ5JSw5+g2n72WJnEZ4zU46B BeNEgNF6tGtdrUpmpqwCCJ23Gr7Qc7YNp6SpPrKCjJGWneEosAuQ92CqB3sbEuGeHP4r f2OQET+pgUvDap2L/bbQHhiJi8QbV+tkTd0fYxHOVoqdE8iq0Zg3lLg3jTuu/POob2RX ohUQTSXlwPVKU0tJpUGyNWdkUFVirFEkOaXoTAAOqdxJ9GYIFOnAexdgnTvzdAGzGtvA MAohTZBdBnVUPnHyVFQ2qfpizzYjrb3w6nzLJ0TCGm7ntXpN1+weGx4riD2RRX/yZKti 5z5Q== X-Gm-Message-State: AG10YOSkfvSzPLPtUzEk5CRwQviQjSLtdh/TQ1qxXg2ueH1KANvD1jCEddvbJFnADwlqOVmr61g= X-Received: by 10.25.33.198 with SMTP id h189mr17242920lfh.91.1455122967845; Wed, 10 Feb 2016 08:49:27 -0800 (PST) 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 mj4sm601197lbc.19.2016.02.10.08.49.26 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 10 Feb 2016 08:49:27 -0800 (PST) From: Christophe Milard To: anders.roxell@linaro.org, mike.holmes@linaro.org, bill.fischofer@linaro.org, petri.savolainen@linaro.org Date: Wed, 10 Feb 2016 18:48:22 +0100 Message-Id: <1455126503-52094-4-git-send-email-christophe.milard@linaro.org> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1455126503-52094-1-git-send-email-christophe.milard@linaro.org> References: <1455126503-52094-1-git-send-email-christophe.milard@linaro.org> MIME-Version: 1.0 X-Topics: patch Cc: lng-odp@lists.linaro.org Subject: [lng-odp] [API-NEXT PATCHv5 3/4] doc: descr of structure for new interfaces 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" updates of the documentation to reflect the new structure allowing new interface addition. Signed-off-by: Christophe Milard --- doc/implementers-guide/implementers-guide.adoc | 72 +++++++++++++++----------- doc/users-guide/users-guide.adoc | 13 +++-- 2 files changed, 51 insertions(+), 34 deletions(-) diff --git a/doc/implementers-guide/implementers-guide.adoc b/doc/implementers-guide/implementers-guide.adoc index d68354d..d855148 100644 --- a/doc/implementers-guide/implementers-guide.adoc +++ b/doc/implementers-guide/implementers-guide.adoc @@ -18,44 +18,58 @@ The implementers view of the include source tree allows the common API definitions and documentation to be reused by all the platforms defined in the tree, but leave the actual definitions to be defined by the specific platform. -.Implementers include structure +.Implementers include structure (in repository) ---- ./ ├── include/ │   ├── odp/ -│   │   └── api/ <1> -│   │   └── The Public API and the documentation. +│ │ └── api/ +│ │ └── spec/ +│ │ └── The Public API specification and its documentation. <1> │   │ -│   └── odp.h <4> This file should be the only file included by the application. +│ └── odp_api.h This file should be the only file included by the any ODP +│ application. <4> │ -├── platform/ -│   ├── / -│   │   ├── include/ -│   │   │   ├── odp/ <2> -│   │   │   │   ├── In-line function definitions of the public API for this -│   │   │   │ │ platform seen by the application. -│   │   │   │ │ -│   │   │   │   └── plat/ <3> -│   │   │   │     └── Platform specific types, enums etc as seen by the -│   │   │   │ application but require overriding by the -│   │   │   │ implementation. -│   │   │   │   -│   │   │   └── Internal header files seen only by the implementation. +└── platform/ + └── / + └── include/ + ├── Internal header files seen only by the implementation. + └── odp/ + └── api/ <2> + ├── In-line function definitions of the public API for this + │ platform seen by the application. + │ + └── plat/ <3> + └── Platform specific types, enums etc as seen by the + application but require overriding by the + implementation. ---- - -<1> The doxygen description of the API definition is held in the public api file -'include/odp/api'. -<2> The public file is included by a counterpart in -'platform//include/odp'. -The include of the public API is AFTER the platform specific definitions to -allow the platform to provide definitions that match the underlying hardware. -<3> The implementation code includes 'platform//include/plat' -and this then provides the source files with a complete definition the ODP API -to be implemented. -<4> Applications in turn include the include/odp.h file which includes the -'platform//include/plat' files to provide a complete +<1> The specification, defining the ODP application programming interface (API) +is held in 'include/odp/api/spec/'. The ODP API is defined by a set of '.h' +files including doxygen documentation. +<2> Each public specification file is included by a counterpart in +'platform//include/odp/api'. +The include of the specification API is AFTER the platform specific definitions +to allow the platform to provide definitions that match the underlying hardware. +<3> The implementation code may include files from +'platform//include/odp/api/plat' +<4> Applications in turn include the include/odp_api.h file which includes the +'platform//include/odp/api' files to provide a complete definition of the API. +After ODP installation (make install), the structure becomes as follows: + +.Installed ODP structure +---- +./ +└── include/ + ├── odp/ + │ └── api/ API In-line for this platform. + │ ├── plat/ API Platform specific types. + │ └── spec/ The public API specification. + └── odp_api.h +---- + == The validation Suite == ODP provides a comprehensive set of API validation tests that are intended to be diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 7bee6ed..ea5e6aa 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -462,8 +462,8 @@ _synchronization_ mechanisms. ODP provides APIs to assist in each of these areas. === The include structure -Applications only include the 'include/odp.h' file, which includes the -'platform//include/odp' files to provide a complete +Applications only include the 'include/odp_api.h' file, which includes the +'platform//include/odp/api' files to provide a complete definition of the API on that platform. The doxygen documentation defining the behavior of the ODP API is all contained in the public API files, and the actual definitions for an implementation will be found in the per platform @@ -477,9 +477,12 @@ visible to the application. ├── include/ │   ├── odp/ │   │   └── api/ -│   │   └── The Public API and the documentation. -│   │ -│   └── odp.h This file should be the only file included by the application. +│ │ └── spec/ +│ │ └── The Public API and the documentation. +│ │ +│ │ +│ ├── odp_api.h This file should be the only file included by the +│ │ application. ---- === Initialization