doc: move api guidelines to API doc

This documentation was moved from the architecture doc to this API doc.

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

1 files changed, 178 insertions, 0 deletions

diff --git a/doc/api_guide_lines.dox b/doc/api_guide_lines.dox
new file mode 100644
index 00000000..4cfe0889
--- /dev/null
+++ b/doc/api_guide_lines.dox
@@ -0,0 +1,178 @@
+/* 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.
+
+*/