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.ereminsoleni...@linaro.org> --- include/README | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 include/README 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. -- 2.14.2
