From: Sergio Gonzalez Monroy <sergio.gonzalez.monroy@intel.com>
To: Neil Horman <nhorman@tuxdriver.com>
Cc: dev@dpdk.org
Subject: Re: [dpdk-dev] [PATCH 1/4] compat: Add infrastructure to support symbol versioning
Date: Tue, 23 Sep 2014 17:29:48 +0100 [thread overview]
Message-ID: <20140923162947.GA22463@sivswdev02.ir.intel.com> (raw)
In-Reply-To: <20140923145829.GB12884@hmsreliant.think-freely.org>
On Tue, Sep 23, 2014 at 10:58:29AM -0400, Neil Horman wrote:
> On Tue, Sep 23, 2014 at 11:39:29AM +0100, Sergio Gonzalez Monroy wrote:
> > Hi Neil,
> >
> > On Mon, Sep 15, 2014 at 03:23:48PM -0400, Neil Horman wrote:
> > > 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>
> > > ---
> > > lib/Makefile | 1 +
> > > lib/librte_compat/Makefile | 38 +++++++++++++++++++
> > > lib/librte_compat/rte_compat.h | 86 ++++++++++++++++++++++++++++++++++++++++++
> > > mk/rte.lib.mk | 6 +++
> > > 4 files changed, 131 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..a61511a
> > > --- /dev/null
> > > +++ b/lib/librte_compat/Makefile
> > > @@ -0,0 +1,38 @@
> > > +# BSD LICENSE
> > > +#
> > > +# Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
> > > +# 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..6d65a53
> > > --- /dev/null
> > > +++ b/lib/librte_compat/rte_compat.h
> > > @@ -0,0 +1,86 @@
> > > +/*-
> > > + * BSD LICENSE
> > > + *
> > > + * Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
> > > + * 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_SYMBOL_VERSIONING
> > > +
> > > +/*
> > > + * 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.8 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);
> > > + *
> > > + */
> > > +#define VERSION_SYMBOL(b, e, v) __asm__(".symver " SA(b) SA(e) ", "SA(b)"@DPDK_"SA(v))
> > > +#define __vsym __attribute__((used))
> > > +
> >
> > I may be missing something here but would it not be neccessary to define a
> > default symbol?
> > Otherwise there would be multiple definitions of a given symbol and the linker
> > won't know which symbol version to bind to.
> >
> > Following your example, something along these lines:
> > 4) Edit lib/<library>/library_version.map to add a DPDK_1.9 node that is a
> > successor to DPDK_1.8, in which foo is exported as a global symbol
> > DPDK_1.9 {
> > global: foo;
> > } DPDK_1.8;
> >
> > 5) rename new function int foo(int index) to
> > int __vsym foo_v19(int index)
> >
> > 6) Add this macro immediately below the function:
> > DEFAULT_SYMBOL(foo, _v19, 1.9);
> >
> > #define DEFAULT_SYMBOL(b, e, v) __asm__(".symver " SA(b) SA(e) ", "SA(b)"@@DPDK_"SA(v))
> >
>
> You're spot on (though the macro that I created in rte_compat.h is
> VERSION_SYMBOL).
>
> When you use a version script to create a DSO, at link time, the appropriate
> version is appended to the symbol name (you can see it with objdump -t in a
> linked binary). If you want to update the symbol to a new version, you do what
> I documented in the header file (though now that I re-read it, it could be more
> clear. Hows this for a change to the documentation:
>
> To make a new version of a function foo in a DSO:
>
> 1) Edit lib/<library>/library_version.map to add a DPDK_1.8 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 the new version of the function foo.
>
>
> Those steps above will create two symbols in your export table of the DSO:
>
> foo@@DPDK_1.8
> foo@@DPDK_1.9
>
> Any application linked against this DSO will link against the latest version
> (DPDK_1.9). But if you look at the symbols referenced in a binary linked
> against an older version of the same DSO, you'll note they explicitly look for
> foo@@DPDK_1.8. Thats how we provide backwards compatibility
>
> Does that answer your questions?
>
> Neil
>
Correct me if I am wrong but when we define multiple versions of a symbol we
need to specify a default one.
As an example, if we were to have three versions of foo the export table of the
DSO should look something like this:
foo@VER_1.0
foo@VER_1.1
foo@@VER_1.2
In the above example, foo VER_1.2 is the default one and is indicated by
having double @.
Effectively we would need two macros VERSION_SYMBOL and DEFAULT_VERSION_SYMBOL
(maybe this name is more appropriate).
#define VERSION_SYMBOL(b, e, v) \
__asm__(".symver " SA(b) SA(e) ", "SA(b)"@DPDK_"SA(v))
#define DEFAULT_VERSION_SYMBOL(b, e, v) \
__asm__(".symver " SA(b) SA(e) ", "SA(b)"@@DPDK_"SA(v))
Following on the example, we should have something like:
int __vsym foo_v18(char *string) {...}
VERSION_SYMBOL(foo, _v18, 1.8);
int __vsym foo_v19(int index) {...}
DEFAULT_VERSION_SYMBOL(foo, _v19, 1.9);
The DSO export table would have the following symbols:
foo@DPDK_1.8
foo@@DPDK_1.9
Old binaries linked against DPDK 1.8 would have references to:
foo@@DPDK_1.8
and new binaries linked against DPDK 1.9 would have to:
foo@@DPDK_1.9
Sergio
> > > +#else
> > > +/*
> > > + * No symbol versioning in use
> > > + */
> > > +#define VERSION_SYMBOL(b, e, v)
> > > +#define __vsym
> > > +
> > > +/*
> > > + * RTE_SYMBOL_VERSIONING
> > > + */
> > > +#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
> > >
> >
> > Sergio
> >
next prev parent reply other threads:[~2014-09-23 16:37 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-09-15 19:23 [dpdk-dev] [PATCH 0/4] Add DSO symbol versioning to support backwards compatibility Neil Horman
2014-09-15 19:23 ` [dpdk-dev] [PATCH 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2014-09-23 10:39 ` Sergio Gonzalez Monroy
2014-09-23 14:58 ` Neil Horman
2014-09-23 16:29 ` Sergio Gonzalez Monroy [this message]
2014-09-23 17:31 ` Neil Horman
2014-09-25 18:52 ` [dpdk-dev] [PATCH 1/4 v2] " Neil Horman
2014-09-26 14:16 ` Sergio Gonzalez Monroy
2014-09-26 15:16 ` Neil Horman
2014-09-26 15:33 ` Sergio Gonzalez Monroy
2014-09-26 16:22 ` Neil Horman
2014-09-26 19:19 ` Neil Horman
2014-09-29 15:44 ` [dpdk-dev] [PATCH 1/4 v3] " Neil Horman
2014-09-30 8:13 ` Sergio Gonzalez Monroy
2014-09-30 15:18 ` [dpdk-dev] [PATCH 1/4 v4] " Neil Horman
2014-10-01 10:15 ` Sergio Gonzalez Monroy
2014-10-01 10:38 ` Neil Horman
2014-10-01 11:28 ` Sergio Gonzalez Monroy
2014-09-15 19:23 ` [dpdk-dev] [PATCH 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-09-19 9:45 ` Bruce Richardson
2014-09-19 10:22 ` Neil Horman
2014-10-01 11:25 ` Sergio Gonzalez Monroy
2014-10-01 14:43 ` Neil Horman
2014-09-15 19:23 ` [dpdk-dev] [PATCH 3/4] Add library version extenstion Neil Horman
2014-10-01 11:27 ` Sergio Gonzalez Monroy
2014-09-15 19:23 ` [dpdk-dev] [PATCH 4/4] docs: Add ABI documentation Neil Horman
2014-10-01 16:06 ` Sergio Gonzalez Monroy
2014-09-18 18:23 ` [dpdk-dev] [PATCH 0/4] Add DSO symbol versioning to support backwards compatibility Thomas Monjalon
2014-09-18 19:14 ` Neil Horman
2014-09-19 8:57 ` Richardson, Bruce
2014-09-19 14:18 ` Venkatesan, Venky
2014-09-19 17:45 ` Neil Horman
2014-09-24 18:19 ` Neil Horman
2014-09-26 10:41 ` Thomas Monjalon
2014-09-26 14:45 ` Neil Horman
2014-09-26 22:02 ` Stephen Hemminger
2014-09-27 2:22 ` Neil Horman
2014-10-01 18:59 ` Neil Horman
2014-10-07 21:01 ` Neil Horman
2014-10-08 15:57 ` Thomas Monjalon
2014-10-08 18:46 ` Butler, Siobhan A
2014-10-08 19:09 ` Neil Horman
2014-12-20 21:01 [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2014-12-22 14:01 ` Gonzalez Monroy, Sergio
2014-12-22 16:22 ` Neil Horman
2014-12-22 16:34 ` Neil Horman
2014-12-22 17:09 ` Gonzalez Monroy, Sergio
2014-12-22 19:00 ` Neil Horman
2014-12-22 20:04 ` Neil Horman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20140923162947.GA22463@sivswdev02.ir.intel.com \
--to=sergio.gonzalez.monroy@intel.com \
--cc=dev@dpdk.org \
--cc=nhorman@tuxdriver.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).