[1/2] eal: split compat header file
Checks
Commit Message
The compat.h header file provided macros for two purposes:
1. it provided the macros for marking functions as rte_experimental
2. it provided the macros for doing function versioning
Although these were in the same file, #1 is something that is for use by
public header files, which #2 is for internal use only. Therefore, we can
split these into two headers, keeping #1 in rte_compat.h and #2 in a new
file rte_function_versioning.h. For "make" builds, since internal objects
pick up the headers from the "include/" folder, we need to add the new
header to the installation list, but for "meson" builds it does not need to
be installed as it's not for public use.
The rework also serves to allow the use of the function versioning macros
to files that actually need them, so the use of experimental functions does
not need including of the versioning code.
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
doc/api/doxy-api-index.md | 3 ++-
doc/guides/contributing/versioning.rst | 4 ++--
lib/librte_distributor/rte_distributor.c | 2 +-
lib/librte_distributor/rte_distributor_v20.c | 2 +-
lib/librte_eal/common/Makefile | 1 +
...rte_compat.h => rte_function_versioning.h} | 19 +++----------------
lib/librte_lpm/rte_lpm.c | 1 +
lib/librte_lpm/rte_lpm.h | 1 -
lib/librte_lpm/rte_lpm6.c | 1 +
lib/librte_timer/rte_timer.c | 2 +-
10 files changed, 13 insertions(+), 23 deletions(-)
rename lib/librte_eal/common/include/{rte_compat.h => rte_function_versioning.h} (89%)
Comments
On Fri, Sep 27, 2019 at 08:49:31PM +0100, Bruce Richardson wrote:
> The compat.h header file provided macros for two purposes:
> 1. it provided the macros for marking functions as rte_experimental
> 2. it provided the macros for doing function versioning
>
> Although these were in the same file, #1 is something that is for use by
> public header files, which #2 is for internal use only. Therefore, we can
> split these into two headers, keeping #1 in rte_compat.h and #2 in a new
> file rte_function_versioning.h. For "make" builds, since internal objects
> pick up the headers from the "include/" folder, we need to add the new
> header to the installation list, but for "meson" builds it does not need to
> be installed as it's not for public use.
>
> The rework also serves to allow the use of the function versioning macros
> to files that actually need them, so the use of experimental functions does
> not need including of the versioning code.
>
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
> doc/api/doxy-api-index.md | 3 ++-
> doc/guides/contributing/versioning.rst | 4 ++--
> lib/librte_distributor/rte_distributor.c | 2 +-
> lib/librte_distributor/rte_distributor_v20.c | 2 +-
> lib/librte_eal/common/Makefile | 1 +
> ...rte_compat.h => rte_function_versioning.h} | 19 +++----------------
> lib/librte_lpm/rte_lpm.c | 1 +
> lib/librte_lpm/rte_lpm.h | 1 -
> lib/librte_lpm/rte_lpm6.c | 1 +
> lib/librte_timer/rte_timer.c | 2 +-
> 10 files changed, 13 insertions(+), 23 deletions(-)
> rename lib/librte_eal/common/include/{rte_compat.h => rte_function_versioning.h} (89%)
>
Apologies, but one of the parts of the split file somehow missed making the
patch. I'll do a v2 soon.
@@ -171,5 +171,6 @@ The public API headers are grouped by topics:
- **misc**:
[EAL config] (@ref rte_eal.h),
[common] (@ref rte_common.h),
- [ABI compat] (@ref rte_compat.h),
+ [experimental APIs] (@ref rte_compat.h),
+ [ABI versioning] (@ref rte_function_versioning.h),
[version] (@ref rte_version.h)
@@ -206,7 +206,7 @@ functionality or behavior. When that occurs, it is desirable to allow for
backward compatibility for a time with older binaries that are dynamically
linked to the DPDK.
-To support backward compatibility the ``rte_compat.h``
+To support backward compatibility the ``rte_function_versioning.h``
header file provides macros to use when updating exported functions. These
macros are used in conjunction with the ``rte_<library>_version.map`` file for
a given library to allow multiple versions of a symbol to exist in a shared
@@ -362,7 +362,7 @@ the function, we add this line of code
VERSION_SYMBOL(rte_acl_create, _v20, 2.0);
-Remembering to also add the rte_compat.h header to the requisite c file where
+Remembering to also add the rte_function_versioning.h header to the requisite c file where
these changes are being made. The above macro instructs the linker to create a
new symbol ``rte_acl_create@DPDK_2.0``, which matches the symbol created in older
builds, but now points to the above newly named function. We have now mapped
@@ -8,7 +8,7 @@
#include <rte_mbuf.h>
#include <rte_memory.h>
#include <rte_cycles.h>
-#include <rte_compat.h>
+#include <rte_function_versioning.h>
#include <rte_memzone.h>
#include <rte_errno.h>
#include <rte_string_fns.h>
@@ -9,7 +9,7 @@
#include <rte_memory.h>
#include <rte_memzone.h>
#include <rte_errno.h>
-#include <rte_compat.h>
+#include <rte_function_versioning.h>
#include <rte_string_fns.h>
#include <rte_eal_memconfig.h>
#include <rte_pause.h>
@@ -4,6 +4,7 @@
include $(RTE_SDK)/mk/rte.vars.mk
INC := rte_branch_prediction.h rte_common.h rte_compat.h
+INC += rte_function_versioning.h
INC += rte_debug.h rte_eal.h rte_eal_interrupts.h
INC += rte_errno.h rte_launch.h rte_lcore.h
INC += rte_log.h rte_memory.h rte_memzone.h
similarity index 89%
rename from lib/librte_eal/common/include/rte_compat.h
rename to lib/librte_eal/common/include/rte_function_versioning.h
@@ -3,8 +3,8 @@
* All rights reserved.
*/
-#ifndef _RTE_COMPAT_H_
-#define _RTE_COMPAT_H_
+#ifndef _RTE_FUNCTION_VERSIONING_H_
+#define _RTE_FUNCTION_VERSIONING_H_
#include <rte_common.h>
#ifdef RTE_BUILD_SHARED_LIB
@@ -76,17 +76,4 @@
*/
#endif
-#ifndef ALLOW_EXPERIMENTAL_API
-
-#define __rte_experimental \
-__attribute__((deprecated("Symbol is not yet part of stable ABI"), \
-section(".text.experimental")))
-
-#else
-
-#define __rte_experimental \
-__attribute__((section(".text.experimental")))
-
-#endif
-
-#endif /* _RTE_COMPAT_H_ */
+#endif /* _RTE_FUNCTION_VERSIONING_H_ */
@@ -22,6 +22,7 @@
#include <rte_rwlock.h>
#include <rte_spinlock.h>
#include <rte_tailq.h>
+#include <rte_function_versioning.h>
#include "rte_lpm.h"
@@ -20,7 +20,6 @@
#include <rte_memory.h>
#include <rte_common.h>
#include <rte_vect.h>
-#include <rte_compat.h>
#ifdef __cplusplus
extern "C" {
@@ -25,6 +25,7 @@
#include <assert.h>
#include <rte_jhash.h>
#include <rte_tailq.h>
+#include <rte_function_versioning.h>
#include "rte_lpm6.h"
@@ -25,8 +25,8 @@
#include <rte_pause.h>
#include <rte_memzone.h>
#include <rte_malloc.h>
-#include <rte_compat.h>
#include <rte_errno.h>
+#include <rte_function_versioning.h>
#include "rte_timer.h"