From patchwork Fri Oct 24 14:51:42 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 39481 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-ee0-f71.google.com (mail-ee0-f71.google.com [74.125.83.71]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 7860220341 for ; Fri, 24 Oct 2014 14:52:06 +0000 (UTC) Received: by mail-ee0-f71.google.com with SMTP id e51sf264309eek.6 for ; Fri, 24 Oct 2014 07:52:05 -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:from:to:date:message-id :mime-version:subject:precedence:list-id:list-unsubscribe :list-archive:list-post:list-help:list-subscribe:errors-to:sender :x-original-sender:x-original-authentication-results:mailing-list :content-type:content-transfer-encoding; bh=k1UPEsw7PFZNB7TN0RGxDAIMDf1w9CsqA8qXaQh1Y28=; b=GBiIZ6EfwKJ1Anwq3jF7VCWxP246DK6lE0dkAuMMgVWoVKyX4htMmYe/Z4GxpKlQ1G z/dSksKW9pFwPW7+FPaeuaY9a+PJ1xGeutyasouT4TBZZBtSOCHb/SMvED6GlDdoFsVX Yzfa2UPL3+lL/wMOUfxOLCIPCIknSdTRtWJooh4mW7ErRkmmjqSmIQGni6QB8Irk/CX4 Ik98+k50c8TuU/AK5u1KXb0LvmdbmPDSThi4qBvhBuEQww0+z0uVrj5Cx6WWSlAYTZK+ aY2rfURG3qKkymFbwmFoXvhFXd4HeT7L+cG/0w/tCOeowOilGaqx5O0ES+XnAAYcm8M5 S3Pw== X-Gm-Message-State: ALoCoQmQAFh1U+XwBahQvsAX0+4yT/Z2pLBc/wtYv6qaC2QuHsX2hQPxIKDqQwQxIgPwN8UFDLB9 X-Received: by 10.112.154.194 with SMTP id vq2mr733947lbb.10.1414162325251; Fri, 24 Oct 2014 07:52:05 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.36.169 with SMTP id r9ls371162laj.57.gmail; Fri, 24 Oct 2014 07:52:05 -0700 (PDT) X-Received: by 10.152.121.68 with SMTP id li4mr4898888lab.77.1414162325102; Fri, 24 Oct 2014 07:52:05 -0700 (PDT) Received: from mail-la0-f45.google.com (mail-la0-f45.google.com. [209.85.215.45]) by mx.google.com with ESMTPS id ku5si7404130lac.30.2014.10.24.07.52.05 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Fri, 24 Oct 2014 07:52:05 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.45 as permitted sender) client-ip=209.85.215.45; Received: by mail-la0-f45.google.com with SMTP id gm9so1329731lab.18 for ; Fri, 24 Oct 2014 07:52:05 -0700 (PDT) X-Received: by 10.112.221.197 with SMTP id qg5mr5076244lbc.32.1414162324964; Fri, 24 Oct 2014 07:52:04 -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.84.229 with SMTP id c5csp444855lbz; Fri, 24 Oct 2014 07:52:03 -0700 (PDT) X-Received: by 10.140.34.102 with SMTP id k93mr6139173qgk.21.1414162323268; Fri, 24 Oct 2014 07:52:03 -0700 (PDT) Received: from ip-10-35-177-41.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id g2si8256465qcz.19.2014.10.24.07.52.02 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Fri, 24 Oct 2014 07:52:03 -0700 (PDT) Received-SPF: none (google.com: lng-odp-bounces@lists.linaro.org does not designate permitted sender hosts) client-ip=54.225.227.206; Received: from localhost ([127.0.0.1] helo=ip-10-35-177-41.ec2.internal) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XhgDh-0000Mw-A8; Fri, 24 Oct 2014 14:52:01 +0000 Received: from mail-qg0-f49.google.com ([209.85.192.49]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XhgDa-0000Mp-Ls for lng-odp@lists.linaro.org; Fri, 24 Oct 2014 14:51:54 +0000 Received: by mail-qg0-f49.google.com with SMTP id e89so1075886qgf.8 for ; Fri, 24 Oct 2014 07:51:48 -0700 (PDT) X-Received: by 10.224.53.133 with SMTP id m5mr6801919qag.46.1414162308409; Fri, 24 Oct 2014 07:51:48 -0700 (PDT) Received: from fedora1.holmesfamily.ws ([98.221.136.245]) by mx.google.com with ESMTPSA id w8sm4333373qay.5.2014.10.24.07.51.47 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 24 Oct 2014 07:51:47 -0700 (PDT) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Fri, 24 Oct 2014 10:51:42 -0400 Message-Id: <1414162302-12288-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.1.0 MIME-Version: 1.0 X-Topics: Architecture patch Subject: [lng-odp] [PATCH ARCH] Add API guide lines X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.14 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-bounces@lists.linaro.org 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.215.45 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 Add guidelines for the ODP implimenter to follow. Signed-off-by: Mike Holmes --- api_guide_lines.dox | 144 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 api_guide_lines.dox diff --git a/api_guide_lines.dox b/api_guide_lines.dox new file mode 100644 index 0000000..4944947 --- /dev/null +++ b/api_guide_lines.dox @@ -0,0 +1,144 @@ +/* Copyright (c) 2043, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + +@page api_guide_lines API Guide Lines + +@tableofcontents + +@section introduction Introduction +ODP APIs are implemented as callable C functions that often return a typed value. +This document describes the approach to handling return values and error indications expected of conforming ODP implementations. +As such it should be regarded as providing guidelines for how to create new ODP APIs. + +@section functional Functional Definition +This section defines the use of data types, calling conventions, and return codes used by ODP APIs. +All ODP APIs MUST follow these conventions as part of their design. + +@subsection naming Naming Conventions +All ODP APIs begin with the prefix odp_ and those that describe an action to be performed on an object follow the naming convention of object followed by action. +The advantage of this approach is that an alphabetical list of APIs for an object all sort together since they all have names of the form odp_object_action(). + +So for example the API call to allocate a buffer is named odp_buffer_alloc() rather than odp_alloc_buffer(). + +@subsection data_types Data Types and Use of typedef +ODP is designed to allow broad variability in how APIs are implemented on various platforms. +To support this, most APIs operate on abstract data types that are defined via typedef on a per-implementation basis. +These abstract types follow the naming convention of odp_object_t. + +Typedefs that encapsulate C structs follow the convention: + +@code +typedef struct odp_ { +... +} odp__t; +@endcode + +The use of typedef allows implementations to choose underlying data representations that map efficiently to platform capabilities while providing accessor functions to provide structured access to implementation information in a portable manner +Similarly, the use of enum is RECOMMENDED to provide value abstraction for API parameters while enabling the implementation to choose code points that map well to platform native values + +Several native C types are used conventionally within ODP and SHOULD be employed in API design: + +type | Correct use + |---| :--------- +void | SHOULD be used for APIs that do not return a value +void*| SHOULD be used for APIs that return a pointer intended to be used by the caller as a pointer. For example, a routine that returns the address of an application context area SHOULD use a void * return type +int | SHOULD be used for APIs that return a boolean value. The values 1 = true, 0 = false are used for this purpose. Similarly, int SHOULD also be used for APIs that return a simple success/failure indication to the caller. In this case the return value 0 indicates success while non-zero (typically -1) indicates failure and errno is set to a reason code that indicates the nature of the failure. + +@subsection parameters Parameter Structure and Validation +ODP is a framework for use in the data plane. +Data plane applications typically have extreme performance requirements mandating very strict attention to path length considerations in the design of all ODP APIs, with the exception of those designed to be used infrequently such as only during initialization or termination processing. + +Minimizing pathlength in API design involves several considerations: + - The number of parameters passed to a call. In general, ODP APIs designed for frequent use SHOULD have few parameters. Limiting parameter count to one or two well-chosen parameters SHOULD be the goal for APIs designed for frequent use. If a call requires more complex parameter data then it is RECOMMENDED that instead of multiple parameters a single pointer to a struct that can be statically templated and modified by the caller be used. + - The use of macros and inlining. ODP APIs MAY be implemented as preprocessor macros and/or inline functions. This is especially true for accessor functions that are designed to provide getters/setters for object meta data. + - Limiting parameter validation and error-checking processing.  While useful for development and debugging, providing “bullet-proof” APIs that perform extensive parameter validation and error checking is often inappropriate.  While validations that can be performed statically at compile time or at little to no runtime cost SHOULD be considered, APIs MAY choose to leave behavior as undefined when presented with invalid parameters in the interest of runtime efficiency. + +One of the reasons for using abstract types is to avoid having implementation knowledge “bleed through” the API, leading to possible parameter errors. +When one API returns an opaque token to an application it is reasonable to expect that the application can pass that token to subsequent APIs without needing expensive runtime validation. + +ODP provides the helper APIs ODP_STATIC_ASSERT(cond,msg) and ODP_ASSERT(cond,msg) that SHOULD be used in implementations for performing appropriate validation. +The former is a compile-time assertion and hence adds no additional path length. +The latter is controlled by the ODP_NO_DEBUG compile-time switch and so is suitable for use in development/debug builds that can be compiled out for production use. +Other mechanisms available to the implementer are: + - ODP_ABORT() is provided for situations where further execution of the code must not occur and a level of tracing information should be left in the log. + - ODP_DEPRECATED() is used to signify that a call is planned for obsolescence. + - ODP_LOG() is used to direct implementation messages to the application. + + +@subsection function_calls Function Calls +ODP APIs typically have prototypes of the form: + +@code +odp_return_type_t odp_api(p1_type p1, p2_type p2, …); +@endcode +Where: + +type | Description + |--------- | :--------- +odp_return_type_t | Is the return value produced by the API call.  As noted above, the native types void, void *, and int are also used. Other APIs return abstract types defined via typedef +p1_type | Is the data type of the first parameter +p2_type | Is the data type of the second parameter, etc. + +For ODP APIs that return void, results are undefined if the input parameters are invalid. +For those that return void *, the value ODP_NULL or ODP_INVALID MAY be used to indicate call failure. +For non-boolean APIs returning int, a return value of 0 indicates success while non-zero indicates failure. + +@subsection errno Use of errno +ODP APIs SHOULD make use of the thread-local variable errno, defined in the standard library include file errno.h, to indicate a reason for an API call failure when appropriate. +This convention allows callers to easily determine success/failure of a call with a single test and then decode the failure as desired from the extended reason provided by errno. +So, for example, an attempt to allocate a buffer from a buffer pool might return ODP_BUFFER_INVALID if the call was unsuccessful and errno could then be set to an appropriate reason (no storage available (ENOMEM, ENOBUFS), pool not recognized (EINVAL), etc.). + +In general APIs are free to define their own errno usage conventions and values or reuse standard errno values when appropriate. +When “standard” codes exist, implementations SHOULD make use of them so that standard utility functions like perror() can decode them intelligently. +There are, however, a small set of standard codes that are commonly used. +One errno value that MUST be present for all APIs is ODP_FUNCTION_NOT_AVAILABLE. +This special reason code is used to indicate that the underlying implementation does not support the requested API, and SHOULD be equated to ENOSYS. +This may be because the requested API is specifically designated as OPTIONAL or that the caller is using a pre-release version of an API that does not have all functionality implemented yet. + +Another standard errno is ODP_IMPLEMENTATION_LIMIT. +This code SHOULD be used if a API call is made that exceeds a permitted limit of the underlying implementation, and SHOULD be equated to ERANGE. +For example, many APIs MAY mandate certain minimum functionality but provide latitude on maximums. +An example of this might be the number of queues that an application can create. +An attempt to allocate more queues than the underlying implementation supports would result in this failure code being returned via errno + +@subsection boolean Boolean +For odp booleans are integers (int) +The values 1 = true, 0 = false are used for this purpose. + +@subsection success Success and Failure +Pass indications are integers (int) and SHOULD also be used for APIs that return a simple success/failure indication to the caller. +In this case the return value 0 indicates success while non-zero (typically -1) indicates failure and errno is set to a reason code that indicates the nature of the failure. + + +@section implementation Implementation Considerations +To support application portability and preserve implementation flexibility, ODP APIs MUST be designed with several guiding principles in mind. + +@subsection application_view Application View vs. Implementation View +ODP APIs MUST present an application view of a problem in their externals. +That is, the API should allow the application to specify what it wants to do while the underlying implementation of that API controls how the requested function is realized. +As a result, ODP APIs SHOULD NOT be designed with a specific implementation in mind. +This is the reason, for example, that packet I/O in ODP follows a queued model. +It is an implementation responsibility to determine how packets are physically read and written, and whatever internal structures are needed to perform this most efficiently are an implementation rather than an application concern. +In some platforms this may involve the use of receive rings and buffer bursting, while in others this may be a simple memory-mapped register operation to interface with a hardware packet scheduler/distributor. +The ODP application does not care, how packets arrive for processing, only that a packet is available for it to work on. + +Similarly, ODP applications reference packets data fields in terms of the information that is needed, rather than focusing on how that information is obtained. +The assumption is that the underlying implementation has pre-parsed the packet to extract the most relevant data as packet meta data that is immediately available to the application without requiring the application to do this work itself. +Over time, as network speeds increase, more and higher level networking functions are expected to migrate directly into hardware and ODP APIs MUST be mindful of this evolution in their design. + +@subsection essential_functions Essential functions vs. Extensions +At the same time, APIs SHOULD reflect essential needs of data plane application programming and SHOULD NOT strive to offer comprehensive solutions to every possible contingency. +How to draw this line is a judgement call based on experience but API designers MUST take implementation practicalities into consideration when designing APIs to ensure that APIs and features can be implemented efficiently on a wide variety of underlying platforms. +This is one of the reasons why some features MAY be defined as OPTIONAL. +While allowed, the proliferation of OPTIONAL features SHOULD be avoided to enable broad application portability across many implementations. +At the same time, a “least common denominator” approach MUST NOT be taken as that defeats the purpose of providing higher-level abstractions in APIs + +@section defaults Default behaviours +When an API has a default behaviour it must be possible for the application to explicitly call for that behaviour, this guards against the default changing and breaking the application. + +*/