api: deprecated: add configure option and macros

Added configuration option --enable-deprecated to control if
deprecated APIs are enabled or disabled.

Added ODP_DEPRECATED_API macro into the API. Its value can be
used to check if deprecated API definitions are enabled or
disabled. Deprecated APIs are disabled by default. Deprecated
APIs are meant to be removed completely in a later API version.

Added ODP_DEPRECATE() macro to enforce deprecation of API
definitions. When deprecated APIs are disabled, the macro renames
API definitions so that application cannot use those any more,
but a single implementation library can serve applications built
with both options.

Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org>
Reviewed-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>

3 files changed, 7 insertions, 6 deletions

diff --git a/doc/application-api-guide/api_guide_lines.dox b/doc/application-api-guide/api_guide_lines.dox
index 394e95829..a6488c322 100644
--- a/doc/application-api-guide/api_guide_lines.dox
+++ b/doc/application-api-guide/api_guide_lines.dox
@@ -75,7 +75,7 @@ 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_DEPRECATE() is used to signify that a call is planned for obsolescence.
  - ODP_LOG() is used to direct implementation messages to the application.
 
 
@@ -197,8 +197,8 @@ 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.
 
-@subsection odp_deprecated ODP DEPRECATED
-A deprecated API will remain marked as such in the public API using #ODP_DEPRECATED for two release cycles for the #ODP_VERSION_API_MAJOR number.
+@subsection odp_deprecate ODP DEPRECATE
+A deprecated API will remain marked as such in the public API using #ODP_DEPRECATE() for two release cycles for the #ODP_VERSION_API_MAJOR number.
 For example an API marked as deprecated in 1.1.0 will still be present in 1.2.0 and removed in 1.3.0.
 A deprecated API will contain the doxygen tag \@deprecated with a description of the reason for the change.
 
diff --git a/doc/platform-api-guide/Doxyfile b/doc/platform-api-guide/Doxyfile
index 93f6edfe3..12d356e3a 100644
--- a/doc/platform-api-guide/Doxyfile
+++ b/doc/platform-api-guide/Doxyfile
@@ -17,4 +17,5 @@ PREDEFINED = __GNUC__ \
 	     __LITTLE_ENDIAN_BITFIELD \
 	     __x86_64__ \
 	     ODP_PACKED \
+	     ODP_DEPRECATE(x)=x \
 	     "ODP_HANDLE_T(type)=odp_handle_t type"
diff --git a/doc/process-guide/release-guide.adoc b/doc/process-guide/release-guide.adoc
index 8ea147af8..595af91a4 100644
--- a/doc/process-guide/release-guide.adoc
+++ b/doc/process-guide/release-guide.adoc
@@ -251,7 +251,7 @@ Deleting or changing the published API follows the normal <<anchor-1,process>>,
 * A deprecated indication is applied to the old API using the @deprecated
 doxygen syntax.
 * For a function change the old API it is additionally marked using the
-ODP_DEPRECATED preprocessor macro.
+ODP_DEPRECATE() preprocessor macro.
 * The CHANGELOG will have an entry in the API change section.
 * The Release Manager will resolve the duration for which the deprecated API.
 will be supported, and determine which future release it will be applied to. +
@@ -275,7 +275,7 @@ The new API must have comparable coverage to the old API.
  *
  * @param name ...
  */
-odp_foo_t odp_foo_create(const char *name) ODP_DEPRECATED;
+odp_foo_t ODP_DEPRECATE(odp_foo_create)(const char *name);
 
 /**
  * Create a bar
@@ -298,7 +298,7 @@ compiler warning.
  *
  * @param name ...
  */
-odp_foo_t odp_foo_create(const char *name) ODP_DEPRECATED;
+odp_foo_t ODP_DEPRECATE(odp_foo_create)(const char *name);
 ----
 
 === Changing a struct member