[v10,30/30] include: provide formal description of ODP specification

Message ID 20171027125014.27313-31-dmitry.ereminsolenikov@linaro.org
State New
Headers show
Series
  • restructure headers for ABI-compat/platform-optimized modes
Related show

Commit Message

Dmitry Eremin-Solenikov Oct. 27, 2017, 12:50 p.m.
Provide formal description of files being part of ODP specification,
platform-specific headers, substituting parts of ODP specification and
additional headers supplementing ODP specification.

Signed-off-by: Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org>

---
 include/README | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 include/README

-- 
2.14.2

Patch

diff --git a/include/README b/include/README
new file mode 100644
index 000000000000..8f13dbad68e5
--- /dev/null
+++ b/include/README
@@ -0,0 +1,77 @@ 
+ODP specification
+=================
+
+ODP specification consists of several types of files, which together provide
+full list of types, values and functions that ODP implemention MUST provide.
+
+ODP API specification
+---------------------
+
+These are the files from `include/odp/api/spec` directory. They specify a set
+of function prototypes, types, type names, enumerations etc that MUST be
+provided by ODP implementation. Doxygen comments inside these files document
+requirements for ABI interface provided by an implementation. An implementation
+MUST use these headers AS IS, without any modifications to be compatible with
+ODP specification.
+
+ODP ABI compatibility specification
+-----------------------------------
+
+These are the files from `include/odp/arch/@ARCH_ABI@/odp/api/abi/` directory.
+They specify a set of types and values that MUST be used AS IS without any
+modifications by an implementation if it supports and is compiled for
+ABI-compatibility mode.
+
+ODP default ABI headers
+-----------------------
+
+These are the files from `include/odp/api/abi-default` directory. They provide
+default specification for ODP types and values for ABI compatibility. CPU
+architecture specific ABI compatibility files heavily depend on these headers.
+These files MUST NOT be changed by an implementation.
+
+odp_api.h header
+----------------
+
+This header found at `include/odp_api.h` is an entry point for an application.
+Application MUST include only odp_api.h, nothing else. This file includes all
+files from ODP specification.
+
+Additional ODP headers
+======================
+
+These are the headers provided by an ODP to supplement ODP specification.
+
+ODP API headers
+---------------
+
+These are the files from `include/odp/api` directory. They glue together API
+and ABI specification headers. Although they are not part of ODP specification
+itself, they provide an easy way for an implementation to use ODP API/ABI
+header files.  An implementation SHOULD use these headers AS IS unless it has
+strong reason not to do so.
+
+Platform-specific headers
+=========================
+
+Platform ABI headers
+--------------------
+
+These are the headers found at
+`platform/@with_platform@/include-abi/odp/api/abi` directory. They are used by
+the reset of ODP code if implementation is compiled with ABI compatibility
+disabled. They should implement at least a set of types and values documented
+in ODP API specification headers. They are permitted to provide any platform
+specific optimizations (i.e. they might provide types and/or values that map
+directly onto the hardware details, they might provide inline functions to
+speed up execution of the application, etc). These headers MAY use ODP default
+ABI headers if they do fit.
+
+Rest of platform-specific headers
+---------------------------------
+
+Platform MAY provide additional headers at `platform/@with_platform/include`.
+However these headers SHOULD NOT be used directly by an application, because
+this will tie it to the exact implementation details. Application MUST include
+only <odp_api.h> header.  Platform ABI headers MAY use these headers to
+implement platform-specific optimizations.