compat: add macro to map symbol in static build

[dpdk.git] / lib / librte_compat / rte_compat.h

diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
index 45ab88f..929a918 100644 (file)
--- a/lib/librte_compat/rte_compat.h
+++ b/lib/librte_compat/rte_compat.h
@@ -45,26 +45,10 @@
  * VERSION_SYMBOL macros are created.  They, in conjunction with the
  * <library>_version.map file for a given library allow for multiple versions of
  * a symbol to exist in a shared library so that older binaries need not be
- * immediately recompiled. Their use is outlined in the following example:
- * Assumptions: DPDK 2.(X) contains a function int foo(char *string)
- *              DPDK 2.(X+1) needs to change foo to be int foo(int index)
- *
- * To accomplish this:
- * 1) Edit lib/<library>/library_version.map to add a DPDK_2.(X+1) node, in which
- * foo is exported as a global symbol.
- *
- * 2) rename the existing function int foo(char *string) to
- *     int foo_v20(char *string)
- *
- * 3) Add this macro immediately below the function
- *     VERSION_SYMBOL(foo, _v20, 2.0);
- *
- * 4) Implement a new version of foo.
- *     char foo(int value, int otherval) { ...}
- *
- * 5) Mark the newest version as the default version
- *     BIND_DEFAULT_SYMBOL(foo, _v21, 2.1);
+ * immediately recompiled.
  *
+ * Refer to the guidelines document in the docs subdirectory for details on the
+ * use of these macros
  */
 
 /*
@@ -72,6 +56,8 @@
  * b - function base name
  * e - function version extension, to be concatenated with base name
  * n - function symbol version string to be applied
+ * f - function prototype
+ * p - full function symbol name
  */
 
 /*
@@ -96,6 +82,19 @@
 #define BIND_DEFAULT_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@@DPDK_" RTE_STR(n))
 #define __vsym __attribute__((used))
 
+/*
+ * MAP_STATIC_SYMBOL
+ * If a function has been bifurcated into multiple versions, none of which
+ * are defined as the exported symbol name in the map file, this macro can be
+ * used to alias a specific version of the symbol to its exported name.  For
+ * example, if you have 2 versions of a function foo_v1 and foo_v2, where the
+ * former is mapped to foo@DPDK_1 and the latter is mapped to foo@DPDK_2 when
+ * building a shared library, this macro can be used to map either foo_v1 or
+ * foo_v2 to the symbol foo when building a static library, e.g.:
+ * MAP_STATIC_SYMBOL(void foo(), foo_v2);
+ */
+#define MAP_STATIC_SYMBOL(f, p)
+
 #else
 /*
  * No symbol versioning in use
@@ -104,7 +103,7 @@
 #define __vsym
 #define BASE_SYMBOL(b, e)
 #define BIND_DEFAULT_SYMBOL(b, e, n)
-
+#define MAP_STATIC_SYMBOL(f, p) f __attribute__((alias(RTE_STR(p))))
 /*
  * RTE_BUILD_SHARED_LIB=n
  */