@@ -16,7 +16,8 @@ ODP_VERSION_API_MAJOR=odpapi_major_version
AC_SUBST(ODP_VERSION_API_MAJOR)
ODP_VERSION_API_MINOR=odpapi_minor_version
AC_SUBST(ODP_VERSION_API_MINOR)
-AC_CONFIG_FILES([include/odp/api/spec/version.h])
+AC_CONFIG_FILES([include/odp/api/spec/version.h
+ include/odp/api/spec/deprecated.h])
AM_INIT_AUTOMAKE([1.9 tar-pax subdir-objects])
AC_CONFIG_SRCDIR([helper/config.h.in])
@@ -284,7 +285,7 @@ ODP_CFLAGS="$ODP_CFLAGS -DODP_DEBUG=$ODP_DEBUG"
ODP_ABI_COMPAT=1
abi_compat=yes
AC_ARG_ENABLE([abi-compat],
- [ --disable-abi-compat disables ABI compatible mode, enables inline code in header files],
+ [ --disable-abi-compat disables ABI compatible mode, enables inline code in header files],
[if test "x$enableval" = "xno"; then
ODP_ABI_COMPAT=0
abi_compat=no
@@ -294,6 +295,19 @@ AC_ARG_ENABLE([abi-compat],
AC_SUBST(ODP_ABI_COMPAT)
##########################################################################
+# Enable/disable deprecated API definitions
+##########################################################################
+ODP_DEPRECATED_API=0
+deprecated=no
+AC_ARG_ENABLE([deprecated],
+ [ --enable-deprecated enable deprecated API definitions],
+ [if test "x$enableval" = "xyes"; then
+ ODP_DEPRECATED_API=1
+ deprecated=yes
+ fi])
+AC_SUBST(ODP_DEPRECATED_API)
+
+##########################################################################
# Default warning setup
##########################################################################
ODP_CFLAGS="$ODP_CFLAGS -W -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes"
@@ -379,6 +393,7 @@ AC_MSG_RESULT([
static libraries: ${enable_static}
shared libraries: ${enable_shared}
ABI compatible: ${abi_compat}
+ Deprecated APIs: ${deprecated}
cunit: ${cunit_support}
test_vald: ${test_vald}
test_perf: ${test_perf}
@@ -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.
@@ -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"
@@ -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
@@ -1 +1,2 @@
+deprecated.h
version.h
new file mode 100644
@@ -0,0 +1,50 @@
+/* Copyright (c) 2017, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/**
+ * @file
+ *
+ * Macro for deprecated API definitions
+ */
+
+#ifndef ODP_API_DEPRECATED_H_
+#define ODP_API_DEPRECATED_H_
+#include <odp/visibility_begin.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Deprecated API definitions
+ *
+ * Some API definitions may be deprecated by this or a previous API version.
+ * This macro controls if those are enabled (and visible to the application)
+ * or disabled.
+ *
+ * * 0: Deprecated API definitions are disabled (default)
+ * * 1: Deprecated API definitions are enabled
+ */
+#define ODP_DEPRECATED_API @ODP_DEPRECATED_API@
+
+/**
+ * @def ODP_DEPRECATE
+ *
+ * Macro to deprecate API definitions
+ */
+
+#if ODP_DEPRECATED_API
+#define ODP_DEPRECATE(x) x
+#else
+#define ODP_DEPRECATE(x) _deprecated_ ## x
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#include <odp/visibility_end.h>
+#endif
@@ -18,6 +18,7 @@
extern "C" {
#endif
+#include <odp/api/deprecated.h>
#include <odp/api/version.h>
#include <odp/api/std_types.h>
#include <odp/api/compiler.h>
@@ -29,6 +29,7 @@ odpapispecinclude_HEADERS = \
$(top_srcdir)/include/odp/api/spec/cpumask.h \
$(top_srcdir)/include/odp/api/spec/crypto.h \
$(top_srcdir)/include/odp/api/spec/debug.h \
+ $(top_srcdir)/include/odp/api/spec/deprecated.h \
$(top_srcdir)/include/odp/api/spec/errno.h \
$(top_srcdir)/include/odp/api/spec/event.h \
$(top_srcdir)/include/odp/api/spec/hash.h \
@@ -34,6 +34,7 @@ odpapiinclude_HEADERS = \
$(srcdir)/include/odp/api/cpumask.h \
$(srcdir)/include/odp/api/crypto.h \
$(srcdir)/include/odp/api/debug.h \
+ $(srcdir)/include/odp/api/deprecated.h \
$(srcdir)/include/odp/api/errno.h \
$(srcdir)/include/odp/api/event.h \
$(srcdir)/include/odp/api/hash.h \
new file mode 100644
@@ -0,0 +1,26 @@
+/* Copyright (c) 2017, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/**
+ * @file
+ *
+ * Control deprecated API definitions
+ */
+
+#ifndef ODP_PLAT_DEPRECATED_H_
+#define ODP_PLAT_DEPRECATED_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <odp/api/spec/deprecated.h>
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
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> --- configure.ac | 19 +++++++- doc/application-api-guide/api_guide_lines.dox | 6 +-- doc/platform-api-guide/Doxyfile | 1 + doc/process-guide/release-guide.adoc | 6 +-- include/odp/api/spec/.gitignore | 1 + include/odp/api/spec/deprecated.h.in | 50 ++++++++++++++++++++++ include/odp_api.h | 1 + platform/Makefile.inc | 1 + platform/linux-generic/Makefile.am | 1 + .../linux-generic/include/odp/api/deprecated.h | 26 +++++++++++ 10 files changed, 104 insertions(+), 8 deletions(-) create mode 100644 include/odp/api/spec/deprecated.h.in create mode 100644 platform/linux-generic/include/odp/api/deprecated.h -- 2.8.1