From patchwork Fri Feb 12 15:10:02 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Christophe Milard X-Patchwork-Id: 61856 Delivered-To: patch@linaro.org Received: by 10.112.43.199 with SMTP id y7csp848226lbl; Fri, 12 Feb 2016 06:13:34 -0800 (PST) X-Received: by 10.140.107.182 with SMTP id h51mr2062734qgf.53.1455286414783; Fri, 12 Feb 2016 06:13:34 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id 19si15947250qgf.103.2016.02.12.06.13.34; Fri, 12 Feb 2016 06:13:34 -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 43B676683B; Fri, 12 Feb 2016 14:13:34 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=juRwjqfP; 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 968706683C; Fri, 12 Feb 2016 14:11: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 7A30466872; Fri, 12 Feb 2016 14:11:34 +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 8D64D6683B for ; Fri, 12 Feb 2016 14:11:13 +0000 (UTC) Received: by mail-lb0-f171.google.com with SMTP id uq3so9965882lbc.1 for ; Fri, 12 Feb 2016 06:11:13 -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=YNRKyTGZuBiWDvWgrqI3UFtKIYL31iRbl8KmbMci33k=; b=juRwjqfPqPbxO//1cT0ZYrDD7PwgZPqeI6hnRR9zHsEk2/EOzqx0Giw+J5XwHhvH1A OO9QmmPOq54BKO6dC3oHE81Q9gzpgiGTATrcNkpIF0LeLzhMSFyxi7B6rjulluNTTc+l CkUI9q8ab9gr22tA+Jdmo/Y0WHWkZgTY1Asdg= 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=YNRKyTGZuBiWDvWgrqI3UFtKIYL31iRbl8KmbMci33k=; b=DGriM+86ii4cfAdSqwBYgcVLXKigQVF6220Mn+HDuHlu8nbtvhDKdkf7tHxZYuKcQh nxk2VUY+jk93Jumxn/vo8EciWWkKA+1R1KkGp2W4YLGovNvcqlyNqJGb83LyuTOEG8NE 4ly98fNscAaMwnsGnLyIaWYn0RmqwaHAkApogIst2gNNt9t9w6BM4BOKJbJTkimLqJ4V vaZ5i5LNbWJef7G6mW++kUbBuhlyoUt9w2DUW+Iu6wwVPAh+75CcxNh9nhr3W76c/Ls1 q+plPJG7sKkUul1n2U5EIsgtf+tr04cTENbjcftOrKa/x0cNySxAQN4v144w+TdcWtuT 9GlQ== X-Gm-Message-State: AG10YOS41Jws+Tfd3SAylocyi/w75HWcIsWksHno6UPfg9+W+lFAS0+6lYKWIzIV5fvRhtALOv0= X-Received: by 10.112.131.37 with SMTP id oj5mr621360lbb.94.1455286272302; Fri, 12 Feb 2016 06:11:12 -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 rx3sm1876740lbb.35.2016.02.12.06.11.11 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 12 Feb 2016 06:11:11 -0800 (PST) From: Christophe Milard To: anders.roxell@linaro.org, mike.holmes@linaro.org, bill.fischofer@linaro.org, petri.savolainen@linaro.org Date: Fri, 12 Feb 2016 16:10:02 +0100 Message-Id: <1455289804-1821-4-git-send-email-christophe.milard@linaro.org> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1455289804-1821-1-git-send-email-christophe.milard@linaro.org> References: <1455289804-1821-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 PATCH 3/5] doc: implementers-guide: adding drv interface 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" The driver interface structure (similar to the api) is described. Signed-off-by: Christophe Milard --- doc/implementers-guide/implementers-guide.adoc | 77 ++++++++++++++++++++------ 1 file changed, 60 insertions(+), 17 deletions(-) diff --git a/doc/implementers-guide/implementers-guide.adoc b/doc/implementers-guide/implementers-guide.adoc index d855148..4294a5b 100644 --- a/doc/implementers-guide/implementers-guide.adoc +++ b/doc/implementers-guide/implementers-guide.adoc @@ -14,35 +14,58 @@ 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 +The implementers view of the include source tree allows the common interface 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. +The different ODP interfaces (api and drv) are defined and implemented using +similar structures: .Implementers include structure (in repository) ---- ./ ├── include/ │   ├── odp/ -│ │ └── api/ +│ │ ├── api/ +│ │ │ └── spec/ +│ │ │ └── The Public API specification and its documentation. <1> +│ │ │ +│ │ └── drv/ │ │ └── spec/ -│ │ └── The Public API specification and its documentation. <1> +│ │ └── The Public Nic driver interface and its documentation. <5> │   │ -│ └── odp_api.h This file should be the only file included by the any ODP -│ application. <4> +│ │ +│ ├── odp_api.h This file should be the only file included by the any ODP +│ │ application. <4> +│ │ +│ └── odp_drv.h This file should be the only file included by the any ODP +│ nic driver. <8> │ └── 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. + ├── 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. + │ + ├── drv/ <6> + │ ├── In-line function definitions of the nic driver interface + │ │ for this platform seen by the application. + │ │ + │ └── plat/ <7> + │ └── Platform specific types, enums etc as seen by the + │ nic driver but require overriding by the + │ implementation. + │ + └── com/ + └── Things common to both interfaces are placed here. + ---- <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' @@ -56,6 +79,20 @@ to allow the platform to provide definitions that match the underlying hardware. <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. +<5> The specification, defining the driver programming interface (drv) +is held in 'include/odp/drv/spec/'. The interface is defined by a set of '.h' +files including doxygen documentation. +<6> Each public specification file is included by a counterpart in +'platform//include/odp/drv'. +The include of the specification is AFTER the platform specific definitions +to allow the platform to provide definitions that match the underlying hardware. +<7> The implementation code may include files from +'platform//include/odp/drv/plat' +<8> Nic drivers in turn include the include/odp_drv.h file which includes the +'platform//include/odp/drv' files to provide a complete +definition of the ODP driver interface. + + After ODP installation (make install), the structure becomes as follows: @@ -64,10 +101,16 @@ After ODP installation (make install), the structure becomes as follows: ./ └── include/ ├── odp/ - │ └── api/ API In-line for this platform. - │ ├── plat/ API Platform specific types. - │ └── spec/ The public API specification. - └── odp_api.h + │ ├── api/ API In-line for this platform. + │ │ ├── plat/ API Platform specific types. + │ │ └── spec/ The public API specification. + │ │ + │ └── drv/ Driver interface In-line for this platform. + │ ├── plat/ Driver interface Platform specific types. + │ └── spec/ The public Driver interface specification. + │ + ├── odp_api.h + └── odp_drv.h ---- == The validation Suite ==