From patchwork Fri Jul 24 12:26:25 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 51436 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-wi0-f198.google.com (mail-wi0-f198.google.com [209.85.212.198]) by patches.linaro.org (Postfix) with ESMTPS id 4395E22D94 for ; Fri, 24 Jul 2015 12:26:49 +0000 (UTC) Received: by wixh2 with SMTP id h2sf6385445wix.0 for ; Fri, 24 Jul 2015 05:26:48 -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 :errors-to:sender:x-original-sender :x-original-authentication-results:mailing-list; bh=90RpI9W57a3EDRURLrLVjuizvnEm9qLBK6X2fMH6KbQ=; b=k7W5pgETWT/p5IReortPGkNfNn5i4V3LBYfHVkapOpOEFyfikZYr6bBNjepm/vIAFP TfgSVnKwLOv6EGCwZnyAIwXIwBDm8CC+yFtGrTHU53a0XfHNaIw/UZVrM5pKtldTXxgG Dz9xcY7yshtbHfegzinDjivcJyd/S42DHhNbgqjnLCgviTvezIDID3i1AofItXuEwvXA Pb6RTEkfY8Q+aV926sqdXFPyw5pl7jqpQBAK6Quh2yawZz8wDmYEcAPcjNp1gS00pDDm LDZuMS40+6OG+qvQToi2NBFk5y/5DlW/Puy9Jnhjr3buWccNz+dJkbFdRHEsIR6QqcGo gnpg== X-Gm-Message-State: ALoCoQmS1W9sYZDBPTFOtfKxDVV3YQ0ainPrcEOuXJWHtPwz0TVR44rhJrYGgAUsBMcfS6RpVoSa X-Received: by 10.152.88.111 with SMTP id bf15mr6072714lab.9.1437740808546; Fri, 24 Jul 2015 05:26:48 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.7.105 with SMTP id i9ls354506laa.96.gmail; Fri, 24 Jul 2015 05:26:48 -0700 (PDT) X-Received: by 10.152.25.228 with SMTP id f4mr13224434lag.112.1437740808390; Fri, 24 Jul 2015 05:26:48 -0700 (PDT) Received: from mail-lb0-f175.google.com (mail-lb0-f175.google.com. [209.85.217.175]) by mx.google.com with ESMTPS id m2si7384309laj.125.2015.07.24.05.26.48 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 24 Jul 2015 05:26:48 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.175 as permitted sender) client-ip=209.85.217.175; Received: by lblf12 with SMTP id f12so14136511lbl.2 for ; Fri, 24 Jul 2015 05:26:48 -0700 (PDT) X-Received: by 10.152.4.163 with SMTP id l3mr13634916lal.35.1437740808247; Fri, 24 Jul 2015 05:26:48 -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.7.198 with SMTP id l6csp1146494lba; Fri, 24 Jul 2015 05:26:47 -0700 (PDT) X-Received: by 10.140.32.181 with SMTP id h50mr20157361qgh.31.1437740806612; Fri, 24 Jul 2015 05:26:46 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id i17si9805927qkh.89.2015.07.24.05.26.45; Fri, 24 Jul 2015 05:26:46 -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 19CC461839; Fri, 24 Jul 2015 12:26:45 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252.ec2.internal 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 ip-10-142-244-252.ec2.internal (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 9E78C61832; Fri, 24 Jul 2015 12:26:40 +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 51F4261832; Fri, 24 Jul 2015 12:26:38 +0000 (UTC) Received: from mail-qk0-f180.google.com (mail-qk0-f180.google.com [209.85.220.180]) by lists.linaro.org (Postfix) with ESMTPS id 1712861832 for ; Fri, 24 Jul 2015 12:26:36 +0000 (UTC) Received: by qkdv3 with SMTP id v3so12894639qkd.3 for ; Fri, 24 Jul 2015 05:26:35 -0700 (PDT) X-Received: by 10.140.148.204 with SMTP id 195mr5714464qhu.24.1437740795869; Fri, 24 Jul 2015 05:26:35 -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 b133sm3925842qhc.40.2015.07.24.05.26.34 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 24 Jul 2015 05:26:35 -0700 (PDT) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Fri, 24 Jul 2015 08:26:25 -0400 Message-Id: <1437740785-15255-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: users: add include directory 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.175 as permitted sender) smtp.mail=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 The directory structure is a little unorthodox, explain the structure Signed-off-by: Mike Holmes Reviewed-by: Bill Fischofer --- doc/users-guide/dir_structure.dox | 63 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 doc/users-guide/dir_structure.dox diff --git a/doc/users-guide/dir_structure.dox b/doc/users-guide/dir_structure.dox new file mode 100644 index 0000000..aa89dec --- /dev/null +++ b/doc/users-guide/dir_structure.dox @@ -0,0 +1,63 @@ +/* Copyright (c) 2015, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page dir_structure Directory Structure + +The ODP API requires that the function definitions, structures and enums be implementation specific so that they are as efficient as possible, however this results in a more complex include hierarchy. + +@section application_view Application View +The single header file odp.h (see diagram below) is the only file an application may include directly if portability is to be maintained for the application. +The structure is then not a familiar hierarchical tree of includes because platform specific files are included before the traditional top level API definition files. + +The single odp.h includes the platform specific files from include/odp giving the implementer an opportunity to define the public API functions as inline and static for performance as necessary on a per platform basis. +The files in include/odp in turn include files from include/odp/plat that contain structure and enum definitions specific to the platform to ensure that the structures used by the implementation are also optimal. +Finally files in include/odp include the traditional pubic api from include/odp/api to complete the API by adding truly generic definitions and the documentation. + +@verbatim +./ +├── include/ +│ ├── odp/ +│ │ ├── In-line function definitions of the public API for this platform +│ │ │ seen by the application. +│ │ │ +│ │ ├── plat/ +│ │ │ └── Platform specific types, enums etc as seen by the application +│ │ │ but require overriding by the implementation +│ │ │ +│ │ └── api/ +│ │ └── The Public API and the documentation. +│ │ +│ └── odp.h This file should be the only file included by the application. +@endverbatim + + +@section implementers_view Implementation View +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 still leave the actual definitions to be defined by the platform. + +@verbatim +./ +├── 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 application. +│ │ │ │ │ +│ │ │ │ └── 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 +@endverbatim +*/