[dpdk-dev,1/4,v4] compat: Add infrastructure to support symbol versioning
Commit Message
Add initial pass header files to support symbol versioning.
---
Change notes
v2)
* Fixed ifdef in rte_compat.h to test for RTE_BUILD_SHARED_LIB instead of the
non-existant RTE_SYMBOL_VERSIONING
* Fixed VERSION_SYMBOL macro to add the needed extra @ to make versioning work
properly
* Improved/Clarified documentation
v3)
* Added missing macros to fully export the symver directive specification
v4)
* Added macro definitions for !SHARED_LIB case
* Improved documentation
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
On Tue, Sep 30, 2014 at 11:18:00AM -0400, Neil Horman wrote:
> Add initial pass header files to support symbol versioning.
>
> ---
> Change notes
> v2)
> * Fixed ifdef in rte_compat.h to test for RTE_BUILD_SHARED_LIB instead of the
> non-existant RTE_SYMBOL_VERSIONING
>
> * Fixed VERSION_SYMBOL macro to add the needed extra @ to make versioning work
> properly
>
> * Improved/Clarified documentation
>
> v3)
> * Added missing macros to fully export the symver directive specification
>
> v4)
> * Added macro definitions for !SHARED_LIB case
> * Improved documentation
>
> 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
>
> diff --git a/lib/Makefile b/lib/Makefile
> index 10c5bb3..a85b55b 100644
> --- a/lib/Makefile
> +++ b/lib/Makefile
> @@ -32,6 +32,7 @@
> include $(RTE_SDK)/mk/rte.vars.mk
>
> DIRS-$(CONFIG_RTE_LIBC) += libc
> +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
> diff --git a/lib/librte_compat/Makefile b/lib/librte_compat/Makefile
> new file mode 100644
> index 0000000..3415c7b
> --- /dev/null
> +++ b/lib/librte_compat/Makefile
> @@ -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
> diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
> new file mode 100644
> index 0000000..d99e362
> --- /dev/null
> +++ b/lib/librte_compat/rte_compat.h
> @@ -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)"@")
Hi Neil,
I was wondering about the use of BASE_SYMBOL macro (as you left it out of the example/doc).
From what I understood (according to ld documentation on versioning), that macro would
bound the symbol to the unspecified base version of the symbol.
You would want that to provide backward compatibility to apps linked against DSOs pre-versioning.
I was under the impression that there would not be support for such apps (therefore no need
for BASE_SYMBOL macro).
Sergio
> +#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_ */
> diff --git a/mk/rte.lib.mk b/mk/rte.lib.mk
> index f458258..82ac309 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)
> +
> endif
>
> +
> _BUILD = $(LIB)
> _INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) $(RTE_OUTPUT)/lib/$(LIB)
> _CLEAN = doclean
> @@ -160,7 +164,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
> --
> 1.9.3
>
Looks good.
On Wed, Oct 01, 2014 at 11:15:31AM +0100, Sergio Gonzalez Monroy wrote:
> On Tue, Sep 30, 2014 at 11:18:00AM -0400, Neil Horman wrote:
> > Add initial pass header files to support symbol versioning.
> >
> > ---
> > Change notes
> > v2)
> > * Fixed ifdef in rte_compat.h to test for RTE_BUILD_SHARED_LIB instead of the
> > non-existant RTE_SYMBOL_VERSIONING
> >
> > * Fixed VERSION_SYMBOL macro to add the needed extra @ to make versioning work
> > properly
> >
> > * Improved/Clarified documentation
> >
> > v3)
> > * Added missing macros to fully export the symver directive specification
> >
> > v4)
> > * Added macro definitions for !SHARED_LIB case
> > * Improved documentation
> >
> > 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
> >
> > diff --git a/lib/Makefile b/lib/Makefile
> > index 10c5bb3..a85b55b 100644
> > --- a/lib/Makefile
> > +++ b/lib/Makefile
> > @@ -32,6 +32,7 @@
> > include $(RTE_SDK)/mk/rte.vars.mk
> >
> > DIRS-$(CONFIG_RTE_LIBC) += libc
> > +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
> > diff --git a/lib/librte_compat/Makefile b/lib/librte_compat/Makefile
> > new file mode 100644
> > index 0000000..3415c7b
> > --- /dev/null
> > +++ b/lib/librte_compat/Makefile
> > @@ -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
> > diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
> > new file mode 100644
> > index 0000000..d99e362
> > --- /dev/null
> > +++ b/lib/librte_compat/rte_compat.h
> > @@ -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)"@")
>
> Hi Neil,
>
> I was wondering about the use of BASE_SYMBOL macro (as you left it out of the example/doc).
>
> From what I understood (according to ld documentation on versioning), that macro would
> bound the symbol to the unspecified base version of the symbol.
> You would want that to provide backward compatibility to apps linked against DSOs pre-versioning.
> I was under the impression that there would not be support for such apps (therefore no need
> for BASE_SYMBOL macro).
>
You are correct, there really is no need for it in our immediate purpose. I
only provided it for completeness of the versioning specification language
(hence the lack of example). We can remove it if you like, but I figured it was
potentially useful to include.
Neil
> Sergio
>
>
> > +#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_ */
> > diff --git a/mk/rte.lib.mk b/mk/rte.lib.mk
> > index f458258..82ac309 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)
> > +
> > endif
> >
> > +
> > _BUILD = $(LIB)
> > _INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) $(RTE_OUTPUT)/lib/$(LIB)
> > _CLEAN = doclean
> > @@ -160,7 +164,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
> > --
> > 1.9.3
> >
> Looks good.
>
Acked-by: Sergio Gonzalez Monroy <sergio.gonzalez.monroy@intel.com>
On Tue, Sep 30, 2014 at 11:18:00AM -0400, Neil Horman wrote:
> Add initial pass header files to support symbol versioning.
>
> ---
> Change notes
> v2)
> * Fixed ifdef in rte_compat.h to test for RTE_BUILD_SHARED_LIB instead of the
> non-existant RTE_SYMBOL_VERSIONING
>
> * Fixed VERSION_SYMBOL macro to add the needed extra @ to make versioning work
> properly
>
> * Improved/Clarified documentation
>
> v3)
> * Added missing macros to fully export the symver directive specification
>
> v4)
> * Added macro definitions for !SHARED_LIB case
> * Improved documentation
>
> 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
>
> diff --git a/lib/Makefile b/lib/Makefile
> index 10c5bb3..a85b55b 100644
> --- a/lib/Makefile
> +++ b/lib/Makefile
> @@ -32,6 +32,7 @@
> include $(RTE_SDK)/mk/rte.vars.mk
>
> DIRS-$(CONFIG_RTE_LIBC) += libc
> +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
> diff --git a/lib/librte_compat/Makefile b/lib/librte_compat/Makefile
> new file mode 100644
> index 0000000..3415c7b
> --- /dev/null
> +++ b/lib/librte_compat/Makefile
> @@ -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
> diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
> new file mode 100644
> index 0000000..d99e362
> --- /dev/null
> +++ b/lib/librte_compat/rte_compat.h
> @@ -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_ */
> diff --git a/mk/rte.lib.mk b/mk/rte.lib.mk
> index f458258..82ac309 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)
> +
> endif
>
> +
> _BUILD = $(LIB)
> _INSTALL = $(INSTALL-FILES-y) $(SYMLINK-FILES-y) $(RTE_OUTPUT)/lib/$(LIB)
> _CLEAN = doclean
> @@ -160,7 +164,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
> --
> 1.9.3
>
@@ -32,6 +32,7 @@
include $(RTE_SDK)/mk/rte.vars.mk
DIRS-$(CONFIG_RTE_LIBC) += libc
+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
@@ -160,7 +164,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