include: provide formal description of ODP specification

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>
Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

1 files changed, 79 insertions, 0 deletions

diff --git a/include/README b/include/README
new file mode 100644
index 000000000..c8abb6893
--- /dev/null
+++ b/include/README
@@ -0,0 +1,79 @@
+ODP specification
+=================
+
+ODP specification consists of several types of files, which together provide
+full list of types, values and functions that ODP implementation 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. Content of some
+types and value of some enumerations are left undefined in API spec. These are
+defined either in ABI spec or implementation specific (non-ABI compatible)
+headers .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 rest 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.