On Wed, Mar 11, 2015 at 1:30 PM, Mike Holmes <[email protected]> wrote:
> This docuemtnation has been moved to the API document > > Signed-off-by: Mike Holmes <[email protected]> > Reviewed-by: Bill Fischofer <[email protected]> > --- > api_guide_lines.dox | 178 > ---------------------------------------------------- > 1 file changed, 178 deletions(-) > delete mode 100644 api_guide_lines.dox > > diff --git a/api_guide_lines.dox b/api_guide_lines.dox > deleted file mode 100644 > index 4cfe088..0000000 > --- a/api_guide_lines.dox > +++ /dev/null > @@ -1,178 +0,0 @@ > -/* Copyright (c) 2014, 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_<descriptive_name>_s { > -... > -} odp_<descriptive_name>_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. For example, a routine that returns the address of an > application context area SHOULD use a void * return type > -odp_bool_t | SHOULD be used for APIs that return a @ref boolean value. > -int | SHOULD be used for success and failure indications, with 0 > indicating a success. Errno may be set > - > -@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_name Function Names > -Functions must attempt to be so clear in their intent that referencing > the documentation is not necessary, the guidelines below should be followed > unless a strong case is made for an exception. > - > -@subsection getters Getting information > - > -@subsubsection is_has Is / Has > -An api with "is" or "has" are both considered @ref boolean questions. > They can only return true or false and it reflects the current state of > something. > - > -An example might be a packet interface, you might want to know if it is > in promiscuous mode. > -@code odp_bool_t state = odp_pktio_is_promiscuous(pktio handle) @endcode > - > -In addtion you might want to know if it has the ability to be in > promiscuous mode. > -@code odp_bool_t state = odp_pktio_has_promiscuous(pktio handle) @endcode > - > -Another case might be if a packet has a vlan flag set > -@code odp_bool_t state = odp_packet_has_vlan(packet handle) @endcode > - > -@subsubsection get Get > -Where possible returned information should be an enum if it reflects a > finite list of information. > -In general get apis drop the actual tag "get" in the function name. > - > -@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 see @ref success. > - > -@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 all booleans are integers. To aid application readability they > are defined as the type odp_bool_t. > -The values !0 = 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. > - > -@subsection odp_internal Internal APIs > -When an interface is defined in a header file and is intended to to be > reused internally it will follow these rules:- > -- Be prefixed with an underscore "_". > -- All the required definitions for the API are to use an underscore, this > includes MACROS, typedefs, enums and function names. > - > -@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. > - > -*/ > -- > 2.1.0 > > > _______________________________________________ > lng-odp mailing list > [email protected] > http://lists.linaro.org/mailman/listinfo/lng-odp >
_______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
