From patchwork Tue Jan 26 18:04:58 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Christophe Milard X-Patchwork-Id: 60487 Delivered-To: patch@linaro.org Received: by 10.112.130.2 with SMTP id oa2csp2089086lbb; Tue, 26 Jan 2016 09:12:06 -0800 (PST) X-Received: by 10.50.61.209 with SMTP id s17mr24173378igr.40.1453828322669; Tue, 26 Jan 2016 09:12:02 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id d4si3349361iod.35.2016.01.26.09.12.02; Tue, 26 Jan 2016 09:12:02 -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 E007E61611; Tue, 26 Jan 2016 17:12:01 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=ci9jVfUi; 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_H2,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 F0B5561780; Tue, 26 Jan 2016 17:07:06 +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 40EEA6177A; Tue, 26 Jan 2016 17:06:55 +0000 (UTC) Received: from mail-lb0-f171.google.com (mail-lb0-f171.google.com [209.85.217.171]) by lists.linaro.org (Postfix) with ESMTPS id 175F861764 for ; Tue, 26 Jan 2016 17:06:46 +0000 (UTC) Received: by mail-lb0-f171.google.com with SMTP id x4so96520301lbm.0 for ; Tue, 26 Jan 2016 09:06:46 -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=SFZp2I+5fC+hErTH8p1KsHwEDbmm9iRxJZ7TGqtEbqg=; b=ci9jVfUiZ1vQdH1VTbCcKQJwToxxYq5i9GotQCI61ueA7l7UVASzvJEKyjwxd77M3X IAm4D/BubzLUBjMNn0nhxCiWE2EAVFe20FdDaggbgztoAhDoANaHgGZpwb34GFvjrs+Z rf8MU5nP0HzdDgpGLlGnhHsvo+KDBWDE6M8Rk= 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=SFZp2I+5fC+hErTH8p1KsHwEDbmm9iRxJZ7TGqtEbqg=; b=TspP7ZRLw7tq6DaScrtOzaj/8SzQieeqNuYTgaLXOsnadIJu58EZw8Ge10urudqN5k h9wxrYbvxkRyd8UFr9RhcKfHCtqV5fFLdBdTJqWfh9aC+utXMBVjCBVmMw5LaRJKN9jE a3kdTpq4R9qeSn8/FzlJi4C0/thBRLwpE36oh3a4q6rYnrE+zAP7gyAcqz+fUWuYnW8N eUjmU74FadYckR1eQO3sZy/MNIrepeE0eO6FHcrk60QX862LNlt0Rk/QqKG7v3w04XG3 7A6/edf3Y7DVrO/Km0ekJTocML6nqRpDFajBEislsQcKccDWGUomBiQ0u77pFxOs9/hf Sabg== X-Gm-Message-State: AG10YORfl3wbFq5lmt7hYQotbdG1+yK6p72VBJFOI3eQczvtpoWp1EEQMzT2xA6I05qgXnLS6RE= X-Received: by 10.112.125.198 with SMTP id ms6mr9275289lbb.106.1453828005040; Tue, 26 Jan 2016 09:06:45 -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 r63sm299514lfe.38.2016.01.26.09.06.43 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 26 Jan 2016 09:06:44 -0800 (PST) From: Christophe Milard To: anders.roxell@linaro.org, mike.holmes@linaro.org, bill.fischofer@linaro.org, petri.savolainen@linaro.org Date: Tue, 26 Jan 2016 19:04:58 +0100 Message-Id: <1453831498-46414-4-git-send-email-christophe.milard@linaro.org> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1453831498-46414-1-git-send-email-christophe.milard@linaro.org> References: <1453831498-46414-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 RFC PATCH 3/3] doc: updates following new structure 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" Signed-off-by: Christophe Milard --- doc/implementers-guide/implementers-guide.adoc | 74 +++++++++++++++----------- doc/users-guide/users-guide.adoc | 15 +++--- 2 files changed, 53 insertions(+), 36 deletions(-) diff --git a/doc/implementers-guide/implementers-guide.adoc b/doc/implementers-guide/implementers-guide.adoc index 574317a..2e0944a 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. -│   │ -│   └── odp.h <4> This file should be the only file included by the application. +│   └── odp/ +│   ├── api/ +│   │   └── ref/ +│   │   └── The Public API reference and its documentation. <1> +│   │ +│   └── 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 +<1> The reference, defining the ODP application programming interface (API) +is held in 'include/odp/api/ref/'. The ODP API is defined by a set of '.h' files +including doxygen documentation. +<2> Each public reference file is included by a counterpart in +'platform//include/odp/api'. +The include of the reference 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 +<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: + +.Installation structure +---- +./ +└── include/ + └── odp/ + ├── api/ In-line for this platform. + │   ├── plat/ Platform specific types. + │   └── ref/ The public API reference. + └── 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 b3c08a1..0592984 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 @@ -476,10 +476,13 @@ 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. +│   │   ├── api/ +│   │   │ └── ref/ +│   │   │ └── The Public API and the documentation. +│   │ │ +│   │ │ +│   │ └── api.h This file should be the only file included by the +│   │ application. ---- === Initialization