[dpdk-dev,1/4] compat: Add infrastructure to support symbol versioning
Commit Message
Add initial pass header files to support symbol versioning.
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas.monjalon@6wind.com>
CC: "Richardson, Bruce" <bruce.richardson@intel.com>
CC: "Gonzalez Monroy, Sergio" <sergio.gonzalez.monroy@intel.com>
---
lib/Makefile | 1 +
lib/librte_compat/Makefile | 38 +++++++++++++++++
lib/librte_compat/rte_compat.h | 96 ++++++++++++++++++++++++++++++++++++++++++
mk/rte.lib.mk | 6 +++
4 files changed, 141 insertions(+)
create mode 100644 lib/librte_compat/Makefile
create mode 100644 lib/librte_compat/rte_compat.h
Comments
Hi Neil,
Just a couple of minor comments.
> From: Neil Horman [mailto:nhorman@tuxdriver.com]
> Sent: Saturday, December 20, 2014 9:02 PM
> Subject: [PATCH 1/4] compat: Add infrastructure to support symbol
> versioning
>
> Add initial pass header files to support symbol versioning.
>
[...]
>
> diff --git a/mk/rte.lib.mk b/mk/rte.lib.mk index 81bf8e1..2299cbe 100644
> --- a/mk/rte.lib.mk
> +++ b/mk/rte.lib.mk
> @@ -40,8 +40,12 @@ VPATH += $(SRCDIR)
>
> ifeq ($(RTE_BUILD_SHARED_LIB),y)
> LIB := $(patsubst %.a,%.so,$(LIB))
> +
> +CPU_LDFLAGS += --version-script=$(EXPORT_MAP)
What about setting --version-script=$(SRCDIR)/$(EXPORT_MAP) so we can do:
Ie. 'EXPORT_MAP = rte_eal_version.map' instead of 'EXPORT_MAP = $(RTE_SDK)/lib/librte_eal/linuxapp/eal/rte_eal_version.map'
> +
> endif
>
> +
> _BUILD = $(LIB)
> _INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
> $(RTE_OUTPUT)/lib/$(LIB) _CLEAN = doclean @@ -161,7 +165,9 @@ endif
> $(RTE_OUTPUT)/lib/$(LIB): $(LIB)
> @echo " INSTALL-LIB $(LIB)"
> @[ -d $(RTE_OUTPUT)/lib ] || mkdir -p $(RTE_OUTPUT)/lib
> +ifneq ($(LIB),)
> $(Q)cp -f $(LIB) $(RTE_OUTPUT)/lib
> +endif
>
We could move the ifneq($(LIB),) to the _INSTALL variable (top of the same file).
Something like this:
-_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) $(RTE_OUTPUT)/lib/$(LIB)
+_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
+ifneq ($(LIB),)
+_INSTALL += $(RTE_OUTPUT)/lib/$(LIB)
+endif
Thanks,
Sergio
> #
> # Clean all generated files
> --
> 1.9.3
On Mon, Dec 22, 2014 at 02:01:10PM +0000, Gonzalez Monroy, Sergio wrote:
> Hi Neil,
>
> Just a couple of minor comments.
>
> > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > Sent: Saturday, December 20, 2014 9:02 PM
> > Subject: [PATCH 1/4] compat: Add infrastructure to support symbol
> > versioning
> >
> > Add initial pass header files to support symbol versioning.
> >
> [...]
> >
> > diff --git a/mk/rte.lib.mk b/mk/rte.lib.mk index 81bf8e1..2299cbe 100644
> > --- a/mk/rte.lib.mk
> > +++ b/mk/rte.lib.mk
> > @@ -40,8 +40,12 @@ VPATH += $(SRCDIR)
> >
> > ifeq ($(RTE_BUILD_SHARED_LIB),y)
> > LIB := $(patsubst %.a,%.so,$(LIB))
> > +
> > +CPU_LDFLAGS += --version-script=$(EXPORT_MAP)
>
> What about setting --version-script=$(SRCDIR)/$(EXPORT_MAP) so we can do:
> Ie. 'EXPORT_MAP = rte_eal_version.map' instead of 'EXPORT_MAP = $(RTE_SDK)/lib/librte_eal/linuxapp/eal/rte_eal_version.map'
>
> > +
> > endif
> >
> > +
> > _BUILD = $(LIB)
> > _INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
> > $(RTE_OUTPUT)/lib/$(LIB) _CLEAN = doclean @@ -161,7 +165,9 @@ endif
> > $(RTE_OUTPUT)/lib/$(LIB): $(LIB)
> > @echo " INSTALL-LIB $(LIB)"
> > @[ -d $(RTE_OUTPUT)/lib ] || mkdir -p $(RTE_OUTPUT)/lib
> > +ifneq ($(LIB),)
> > $(Q)cp -f $(LIB) $(RTE_OUTPUT)/lib
> > +endif
> >
> We could move the ifneq($(LIB),) to the _INSTALL variable (top of the same file).
> Something like this:
>
> -_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) $(RTE_OUTPUT)/lib/$(LIB)
> +_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
> +ifneq ($(LIB),)
> +_INSTALL += $(RTE_OUTPUT)/lib/$(LIB)
> +endif
>
Yeah, this all seems reasonable, I'll repost shortly
Thanks
Neil
> Thanks,
> Sergio
>
> > #
> > # Clean all generated files
> > --
> > 1.9.3
>
>
On Mon, Dec 22, 2014 at 02:01:10PM +0000, Gonzalez Monroy, Sergio wrote:
> Hi Neil,
>
> Just a couple of minor comments.
>
> > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > Sent: Saturday, December 20, 2014 9:02 PM
> > Subject: [PATCH 1/4] compat: Add infrastructure to support symbol
> > versioning
> >
> > Add initial pass header files to support symbol versioning.
> >
> [...]
> >
> > diff --git a/mk/rte.lib.mk b/mk/rte.lib.mk index 81bf8e1..2299cbe 100644
> > --- a/mk/rte.lib.mk
> > +++ b/mk/rte.lib.mk
> > @@ -40,8 +40,12 @@ VPATH += $(SRCDIR)
> >
> > ifeq ($(RTE_BUILD_SHARED_LIB),y)
> > LIB := $(patsubst %.a,%.so,$(LIB))
> > +
> > +CPU_LDFLAGS += --version-script=$(EXPORT_MAP)
>
> What about setting --version-script=$(SRCDIR)/$(EXPORT_MAP) so we can do:
> Ie. 'EXPORT_MAP = rte_eal_version.map' instead of 'EXPORT_MAP = $(RTE_SDK)/lib/librte_eal/linuxapp/eal/rte_eal_version.map'
>
> > +
> > endif
> >
> > +
> > _BUILD = $(LIB)
> > _INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
> > $(RTE_OUTPUT)/lib/$(LIB) _CLEAN = doclean @@ -161,7 +165,9 @@ endif
> > $(RTE_OUTPUT)/lib/$(LIB): $(LIB)
> > @echo " INSTALL-LIB $(LIB)"
> > @[ -d $(RTE_OUTPUT)/lib ] || mkdir -p $(RTE_OUTPUT)/lib
> > +ifneq ($(LIB),)
> > $(Q)cp -f $(LIB) $(RTE_OUTPUT)/lib
> > +endif
> >
> We could move the ifneq($(LIB),) to the _INSTALL variable (top of the same file).
> Something like this:
>
> -_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) $(RTE_OUTPUT)/lib/$(LIB)
> +_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
> +ifneq ($(LIB),)
> +_INSTALL += $(RTE_OUTPUT)/lib/$(LIB)
> +endif
>
Actually, as I look at it, this second one doesn't seem to make any sense to me.
_INSTALL as a variable doesn't seem to get used anywhere that I can see,
certainly not in the capacity of copying shared libraries into the build/lib
area so that the example apps can get linked with them. So I'm not sure this
makes sense.
Neil
> Thanks,
> Sergio
>
> > #
> > # Clean all generated files
> > --
> > 1.9.3
>
>
> From: Neil Horman [mailto:nhorman@tuxdriver.com]
> Sent: Monday, December 22, 2014 4:35 PM
>
> On Mon, Dec 22, 2014 at 02:01:10PM +0000, Gonzalez Monroy, Sergio wrote:
> >
> > > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > > Sent: Saturday, December 20, 2014 9:02 PM
> > We could move the ifneq($(LIB),) to the _INSTALL variable (top of the same
> file).
> > Something like this:
> >
> > -_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
> > $(RTE_OUTPUT)/lib/$(LIB)
> > +_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) ifneq ($(LIB),)
> > +_INSTALL += $(RTE_OUTPUT)/lib/$(LIB) endif
> >
> Actually, as I look at it, this second one doesn't seem to make any sense to
> me.
> _INSTALL as a variable doesn't seem to get used anywhere that I can see,
> certainly not in the capacity of copying shared libraries into the build/lib area
> so that the example apps can get linked with them. So I'm not sure this
> makes sense.
>
The _INSTALL var gets expanded for the rule '_install' in mk/internal/rte.install-post.mk if I am not mistaken.
That would trigger the rule $(RTE_OUTPUT)/lib/$(LIB) which in turn builds and copy the shared/static library to build/lib.
If we do not add $(RTE_OUTPUT)/lib/$(LIB) to _INSTALL, then the rule will not trigger.
Regards,
Sergio
> Neil
>
On Mon, Dec 22, 2014 at 05:09:55PM +0000, Gonzalez Monroy, Sergio wrote:
> > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > Sent: Monday, December 22, 2014 4:35 PM
> >
> > On Mon, Dec 22, 2014 at 02:01:10PM +0000, Gonzalez Monroy, Sergio wrote:
> > >
> > > > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > > > Sent: Saturday, December 20, 2014 9:02 PM
> > > We could move the ifneq($(LIB),) to the _INSTALL variable (top of the same
> > file).
> > > Something like this:
> > >
> > > -_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
> > > $(RTE_OUTPUT)/lib/$(LIB)
> > > +_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) ifneq ($(LIB),)
> > > +_INSTALL += $(RTE_OUTPUT)/lib/$(LIB) endif
> > >
> > Actually, as I look at it, this second one doesn't seem to make any sense to
> > me.
> > _INSTALL as a variable doesn't seem to get used anywhere that I can see,
> > certainly not in the capacity of copying shared libraries into the build/lib area
> > so that the example apps can get linked with them. So I'm not sure this
> > makes sense.
> >
> The _INSTALL var gets expanded for the rule '_install' in mk/internal/rte.install-post.mk if I am not mistaken.
> That would trigger the rule $(RTE_OUTPUT)/lib/$(LIB) which in turn builds and copy the shared/static library to build/lib.
>
> If we do not add $(RTE_OUTPUT)/lib/$(LIB) to _INSTALL, then the rule will not trigger.
>
I get all of that, but something isn't right with either your reasoning, or my
coding, as If I make the change you suggest, nothing ever gets copied into the
build/lib directory, either for a static or DSO build.
Neil
> Regards,
> Sergio
>
> > Neil
> >
>
On Mon, Dec 22, 2014 at 02:00:17PM -0500, Neil Horman wrote:
> On Mon, Dec 22, 2014 at 05:09:55PM +0000, Gonzalez Monroy, Sergio wrote:
> > > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > > Sent: Monday, December 22, 2014 4:35 PM
> > >
> > > On Mon, Dec 22, 2014 at 02:01:10PM +0000, Gonzalez Monroy, Sergio wrote:
> > > >
> > > > > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > > > > Sent: Saturday, December 20, 2014 9:02 PM
> > > > We could move the ifneq($(LIB),) to the _INSTALL variable (top of the same
> > > file).
> > > > Something like this:
> > > >
> > > > -_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y)
> > > > $(RTE_OUTPUT)/lib/$(LIB)
> > > > +_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) ifneq ($(LIB),)
> > > > +_INSTALL += $(RTE_OUTPUT)/lib/$(LIB) endif
> > > >
> > > Actually, as I look at it, this second one doesn't seem to make any sense to
> > > me.
> > > _INSTALL as a variable doesn't seem to get used anywhere that I can see,
> > > certainly not in the capacity of copying shared libraries into the build/lib area
> > > so that the example apps can get linked with them. So I'm not sure this
> > > makes sense.
> > >
> > The _INSTALL var gets expanded for the rule '_install' in mk/internal/rte.install-post.mk if I am not mistaken.
> > That would trigger the rule $(RTE_OUTPUT)/lib/$(LIB) which in turn builds and copy the shared/static library to build/lib.
> >
> > If we do not add $(RTE_OUTPUT)/lib/$(LIB) to _INSTALL, then the rule will not trigger.
> >
> I get all of that, but something isn't right with either your reasoning, or my
> coding, as If I make the change you suggest, nothing ever gets copied into the
> build/lib directory, either for a static or DSO build.
>
> Neil
>
Ah, nm, I figured it out, I had accidentally deleted the copy operation which
needs to remain there. I'll fix this up and repost.
Neil
> > Regards,
> > Sergio
> >
> > > Neil
> > >
> >
>
@@ -31,6 +31,7 @@
include $(RTE_SDK)/mk/rte.vars.mk
+DIRS-y += librte_compat
DIRS-$(CONFIG_RTE_LIBRTE_EAL) += librte_eal
DIRS-$(CONFIG_RTE_LIBRTE_MALLOC) += librte_malloc
DIRS-$(CONFIG_RTE_LIBRTE_RING) += librte_ring
new file mode 100644
@@ -0,0 +1,38 @@
+# BSD LICENSE
+#
+# Copyright(c) 2010-2014 Neil Horman <nhorman@tuxdriver.com>
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in
+# the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Intel Corporation nor the names of its
+# contributors may be used to endorse or promote products derived
+# from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+include $(RTE_SDK)/mk/rte.vars.mk
+
+
+# install includes
+SYMLINK-y-include := rte_compat.h
+
+include $(RTE_SDK)/mk/rte.lib.mk
new file mode 100644
@@ -0,0 +1,96 @@
+/*-
+ * BSD LICENSE
+ *
+ * Copyright(c) 2010-2014 Neil Horman <nhorman@tuxdriver.com>.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in
+ * the documentation and/or other materials provided with the
+ * distribution.
+ * * Neither the name of Intel Corporation nor the names of its
+ * contributors may be used to endorse or promote products derived
+ * from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef _RTE_COMPAT_H_
+#define _RTE_COMPAT_H_
+
+/*
+ * This is just a stringification macro for use below.
+ */
+#define SA(x) #x
+
+#ifdef RTE_BUILD_SHARED_LIB
+
+/*
+ * Provides backwards compatibility when updating exported functions.
+ * When a symol is exported from a library to provide an API, it also provides a
+ * calling convention (ABI) that is embodied in its name, return type,
+ * arguments, etc. On occasion that function may need to change to accomodate
+ * new functionality, behavior, etc. When that occurs, it is desireable to
+ * allow for backwards compatibility for a time with older binaries that are
+ * dynamically linked to the dpdk. to support that the __vsym and
+ * 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 1.(X) contains a function int foo(char *string)
+ * DPDK 1.(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_1.(X+1) node, in which
+ * foo is exported as a global symbol.
+ *
+ * 2) rename the existing function int foo(char *string) to
+ * int __vsym foo_v18(char *string)
+ *
+ * 3) Add this macro immediately below the function
+ * VERSION_SYMBOL(foo, _v18, 1.8);
+ *
+ * 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, 1.9);
+ *
+ */
+#define VERSION_SYMBOL(b, e, v) __asm__(".symver " SA(b) SA(e) ", "SA(b)"@DPDK_"SA(v))
+#define BASE_SYMBOL(b, n) __asm__(".symver " SA(n) ", "SA(b)"@")
+#define BIND_DEFAULT_SYMBOL(b, v) __asm__(".symver " SA(b) ", "SA(b)"@@DPDK_"SA(v))
+#define __vsym __attribute__((used))
+
+#else
+/*
+ * No symbol versioning in use
+ */
+#define VERSION_SYMBOL(b, e, v)
+#define __vsym
+#define BASE_SYMBOL(b, n)
+#define BIND_DEFAULT_SYMBOL(b, v)
+
+/*
+ * RTE_BUILD_SHARED_LIB
+ */
+#endif
+
+
+#endif /* _RTE_COMPAT_H_ */
@@ -40,8 +40,12 @@ VPATH += $(SRCDIR)
ifeq ($(RTE_BUILD_SHARED_LIB),y)
LIB := $(patsubst %.a,%.so,$(LIB))
+
+CPU_LDFLAGS += --version-script=$(EXPORT_MAP)
+
endif
+
_BUILD = $(LIB)
_INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) $(RTE_OUTPUT)/lib/$(LIB)
_CLEAN = doclean
@@ -161,7 +165,9 @@ endif
$(RTE_OUTPUT)/lib/$(LIB): $(LIB)
@echo " INSTALL-LIB $(LIB)"
@[ -d $(RTE_OUTPUT)/lib ] || mkdir -p $(RTE_OUTPUT)/lib
+ifneq ($(LIB),)
$(Q)cp -f $(LIB) $(RTE_OUTPUT)/lib
+endif
#
# Clean all generated files