new file mode 100644
@@ -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.
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