From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 0CF21DE4 for ; Wed, 1 Oct 2014 12:31:56 +0200 (CEST) Received: from [2001:470:8:a08:9833:6894:f2b2:43a] (helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1XZHIl-0007Gm-JC; Wed, 01 Oct 2014 06:38:38 -0400 Date: Wed, 1 Oct 2014 06:38:30 -0400 From: Neil Horman To: Sergio Gonzalez Monroy Message-ID: <20141001103830.GA21151@hmsreliant.think-freely.org> References: <1410809031-19114-2-git-send-email-nhorman@tuxdriver.com> <1412090280-9306-1-git-send-email-nhorman@tuxdriver.com> <20141001101530.GA28292@sivswdev02.ir.intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20141001101530.GA28292@sivswdev02.ir.intel.com> User-Agent: Mutt/1.5.23 (2014-03-12) X-Spam-Score: -2.9 (--) X-Spam-Status: No Cc: dev@dpdk.org Subject: Re: [dpdk-dev] [PATCH 1/4 v4] compat: Add infrastructure to support symbol versioning X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 01 Oct 2014 10:31:56 -0000 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 > > CC: Thomas Monjalon > > CC: "Richardson, Bruce" > > CC: "Gonzalez Monroy, Sergio" > > --- > > 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 > > +# 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 . > > + * 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 > > + * _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_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. >