From patchwork Fri Sep 4 18:39:11 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 53137 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-la0-f72.google.com (mail-la0-f72.google.com [209.85.215.72]) by patches.linaro.org (Postfix) with ESMTPS id 0A30F22E23 for ; Fri, 4 Sep 2015 18:39:34 +0000 (UTC) Received: by laeb10 with SMTP id b10sf10486899lae.1 for ; Fri, 04 Sep 2015 11:39:33 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:delivered-to:from:to:date :message-id:mime-version:subject:precedence:list-id:list-unsubscribe :list-archive:list-post:list-help:list-subscribe:content-type :content-transfer-encoding:errors-to:sender:x-original-sender :x-original-authentication-results:mailing-list; bh=sD1TNq0juziMgKJAD/Bfta4g2rooJwHRvssYbhNlL0s=; b=KtEBkTBn+bTBeo1qm3OO4fHLaHiWZbZqPxQw94JbUkqlYBs+knoVhhpaUysmQGYOi8 GUgkw9upNRNq5B9vTiT59HEoTNQpjCfFx63ZzeF48Yq4PzGg/zF5zEcUXki0of5EYZXm FbXgdRZpQc5SU7A80F88UfFs7VOV87KZLjCj5hSdNPAZ9qxCN3RJY8C/C60QtRw2VsZS wYV5H7meHAdfracD1bHL7JIeKU1jDuBnt8yNlLzbh/ob8aBop6UY7JV1mxADyZfW7Z1O j6jskDllzpC1I+SJgmwvGtmSxnYrrB27yzv1K1I64Xx1+r1WJa0ZJe2yN1lkVFkB5S1y 8phg== X-Gm-Message-State: ALoCoQnM5R74ZFtwozj6NK2cCJMsw0iXu1gwk6ZEu1FugTIGu9astZ68WxwChcqgX8fBjDHewpxi X-Received: by 10.180.9.104 with SMTP id y8mr1488470wia.7.1441391972960; Fri, 04 Sep 2015 11:39:32 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.5.39 with SMTP id p7ls355858lap.104.gmail; Fri, 04 Sep 2015 11:39:32 -0700 (PDT) X-Received: by 10.112.161.137 with SMTP id xs9mr4977176lbb.4.1441391972791; Fri, 04 Sep 2015 11:39:32 -0700 (PDT) Received: from mail-lb0-f174.google.com (mail-lb0-f174.google.com. [209.85.217.174]) by mx.google.com with ESMTPS id tn10si2984103lbb.38.2015.09.04.11.39.32 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 04 Sep 2015 11:39:32 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.174 as permitted sender) client-ip=209.85.217.174; Received: by lbbmp1 with SMTP id mp1so16054900lbb.1 for ; Fri, 04 Sep 2015 11:39:32 -0700 (PDT) X-Received: by 10.112.219.70 with SMTP id pm6mr4754076lbc.41.1441391972665; Fri, 04 Sep 2015 11:39:32 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.164.42 with SMTP id yn10csp92540lbb; Fri, 4 Sep 2015 11:39:31 -0700 (PDT) X-Received: by 10.50.32.34 with SMTP id f2mr9590442igi.44.1441391971432; Fri, 04 Sep 2015 11:39:31 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id x3si3287106igl.65.2015.09.04.11.39.30; Fri, 04 Sep 2015 11:39:31 -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; Received: by lists.linaro.org (Postfix, from userid 109) id CC58161D16; Fri, 4 Sep 2015 18:39:30 +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 8D64B61960; Fri, 4 Sep 2015 18:39:25 +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 F3A3061960; Fri, 4 Sep 2015 18:39:17 +0000 (UTC) Received: from mail-qk0-f179.google.com (mail-qk0-f179.google.com [209.85.220.179]) by lists.linaro.org (Postfix) with ESMTPS id C5CDD619AB for ; Fri, 4 Sep 2015 18:39:13 +0000 (UTC) Received: by qkcf65 with SMTP id f65so12203321qkc.3 for ; Fri, 04 Sep 2015 11:39:13 -0700 (PDT) X-Received: by 10.55.217.218 with SMTP id q87mr7366188qkl.56.1441391953552; Fri, 04 Sep 2015 11:39:13 -0700 (PDT) Received: from localhost.localdomain (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by smtp.gmail.com with ESMTPSA id c188sm1814555qka.37.2015.09.04.11.39.13 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 04 Sep 2015 11:39:13 -0700 (PDT) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Fri, 4 Sep 2015 14:39:11 -0400 Message-Id: <1441391951-1929-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.1.4 MIME-Version: 1.0 X-Topics: patch Subject: [lng-odp] [PATCH] doc: implementers add include structure X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: mike.holmes@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.174 as permitted sender) smtp.mailfrom=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 Signed-off-by: Mike Holmes Reviewed-by: Bill Fischofer --- doc/implementers-guide/implementers-guide.adoc | 34 ++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/doc/implementers-guide/implementers-guide.adoc b/doc/implementers-guide/implementers-guide.adoc index 56d6e05..32dbfea 100644 --- a/doc/implementers-guide/implementers-guide.adoc +++ b/doc/implementers-guide/implementers-guide.adoc @@ -11,6 +11,40 @@ Further details about ODP may be found at http://opendataplane.org[ODP homepage] :numbered: +The include structure +--------------------- +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 +---- +./ +├── include/ +│   ├── odp/ +│   │   └── api/ +│   │   └── The Public API and the documentation. +│   │ +│   └── odp.h This file should be the only file included by the application. +│ +├── platform/ +│   ├── / +│   │   ├── include/ +│   │   │   ├── odp/ +│   │   │   │   ├── In-line function definitions of the public API for this platform +│   │   │   │ │ seen by the applicationx. +│   │   │   │ │ +│   │   │   │   └── plat/ +│   │   │   │     └── Platform specific types, enums etc as seen by the application +│   │   │   │ but require overriding by the implementation. +│   │   │   │   +│   │   │   └── Internal header files seen only by the implementation. +---- + +The doxygen description of the API definition is held in the public api file 'include/odp/api'. +This 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. +The implementation code includes 'platform//include/plat' and this then provides the source files with a complete definition the ODP API to be implemented. +Applications in turn include the include/odp.h file which includes the 'platform//include/plat' files to provide a complete definition of the API. + The validation Suite -------------------- ODP provides a comprehensive set of API validation tests that are intended to be used by implementers during development and by application developers to verify that a particular implementation meets their requirements.