DPDK patches and discussions
 help / color / mirror / Atom feed
From: Neil Horman <nhorman@tuxdriver.com>
To: Thomas Monjalon <thomas.monjalon@6wind.com>
Cc: dev@dpdk.org
Subject: Re: [dpdk-dev] [PATCH v3 1/4] compat: Add infrastructure to support symbol versioning
Date: Wed, 14 Jan 2015 15:29:50 -0500
Message-ID: <20150114202950.GC28492@hmsreliant.think-freely.org> (raw)
In-Reply-To: <2338166.O6glFPMYza@xps13>

On Wed, Jan 14, 2015 at 04:25:19PM +0100, Thomas Monjalon wrote:
> Hi Neil,
> 
> 2014-12-23 10:51, Neil Horman:
> > Add initial pass header files to support symbol versioning.
> 
> [...]
> 
> > +#   Copyright(c) 2010-2014 Neil Horman <nhorman@tuxdriver.com>
> 
> Why these dates?
> 
Because I copied the Makefile from librte_acl, and modified the name but not the
dates.

> > +#   All rights reserved.
> 
> I think this line is not required anymore:
> 	http://en.wikipedia.org/wiki/All_rights_reserved
> 
Hmm, apparently so.  However, since it exists in every other copyright notice in
the tree, I'd just as soon keep this language consistent, and make a tree wide
change in a separate patch if the consensus is to do so.

> [...]
> 
> > +#ifndef _RTE_COMPAT_H_
> > +#define _RTE_COMPAT_H_
> 
> Why using underscores?
> I think it's reserved:
> 	http://en.wikipedia.org/wiki/Include_guard#Use_of_.23include_guards
> 
Its reserved for the implementation, and must not be used by a user using the
header file.  Its ok, and is common practice.  See every other symlinked header
file in the DPDK.

> > +#define SA(x) #x
> 
> It should be prefixed. But it's better to use RTE_STR.
> 
very well

> > +#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
> 
> Should be "To support that," with uppercase and comma.
> 
yup

> > + * 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);
> > + *
> > + */
> 
> Thanks for this good tutorial.
> 
> > +#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))
> 
> OK. It would be simpler to read if b, e, v and n were formally defined in a comment.
> 
> > +#else
> [...]
> > +/*
> > + * RTE_BUILD_SHARED_LIB
> > + */
> 
> This type of comment is strange. It makes me think that we are in the case
> RTE_BUILD_SHARED_LIB=y
> 
> > +#endif
> 
> [...]
> 
> > +
> > +CPU_LDFLAGS += --version-script=$(EXPORT_MAP)
> 
> Why this variable name? VERSION_SCRIPT or VERSION_MAP seems more appropriate.
> 
> > +
> >  endif
> >  
> > +
> 
> Why this newline?
> 
> >  _BUILD = $(LIB)
> 
> -- 
> Thomas
> 

  reply	other threads:[~2015-01-14 20:30 UTC|newest]

Thread overview: 99+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
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
2014-12-20 21:01 ` [dpdk-dev] [PATCH 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 3/4] Add library version extenstion Neil Horman
2014-12-20 21:01 ` [dpdk-dev] [PATCH 4/4] docs: Add ABI documentation Neil Horman
2014-12-22 20:24 ` [dpdk-dev] [PATCH v2 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2014-12-22 20:24   ` [dpdk-dev] [PATCH v2 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-22 20:24   ` [dpdk-dev] [PATCH v2 3/4] Add library version extenstion Neil Horman
2014-12-23 13:05     ` Gonzalez Monroy, Sergio
2014-12-23 15:50       ` Neil Horman
2014-12-22 20:24   ` [dpdk-dev] [PATCH v2 4/4] docs: Add ABI documentation Neil Horman
2014-12-23  9:48     ` Iremonger, Bernard
2014-12-23 13:01       ` Neil Horman
2014-12-23 13:27   ` [dpdk-dev] [PATCH v2 1/4] compat: Add infrastructure to support symbol versioning Gonzalez Monroy, Sergio
2014-12-23 15:50     ` Neil Horman
2014-12-23 15:51 ` [dpdk-dev] [PATCH v3 " Neil Horman
2014-12-23 15:51   ` [dpdk-dev] [PATCH v3 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2014-12-29 16:21     ` Sergio Gonzalez Monroy
2015-01-14 15:29     ` Thomas Monjalon
2015-01-14 16:24       ` Neil Horman
2014-12-23 15:51   ` [dpdk-dev] [PATCH v3 3/4] Add library version extenstion Neil Horman
2014-12-23 16:44     ` Gonzalez Monroy, Sergio
2014-12-23 17:08       ` Neil Horman
2014-12-29 16:23     ` Sergio Gonzalez Monroy
2015-01-14 15:48     ` Thomas Monjalon
2014-12-23 15:51   ` [dpdk-dev] [PATCH v3 4/4] docs: Add ABI documentation Neil Horman
2014-12-29 16:24     ` Sergio Gonzalez Monroy
2015-01-14 15:59     ` Thomas Monjalon
2015-01-14 20:07       ` Neil Horman
2015-01-16 13:34         ` Thomas Monjalon
2014-12-29 16:20   ` [dpdk-dev] [PATCH v3 1/4] compat: Add infrastructure to support symbol versioning Sergio Gonzalez Monroy
2015-01-14 15:25   ` Thomas Monjalon
2015-01-14 20:29     ` Neil Horman [this message]
2015-01-09 12:35 ` [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Neil Horman
2015-01-15 19:35 ` [dpdk-dev] [PATCH v4 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-15 19:35   ` [dpdk-dev] [PATCH v4 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-15 19:35   ` [dpdk-dev] [PATCH v4 3/4] Add library version extenstion Neil Horman
2015-01-15 19:35   ` [dpdk-dev] [PATCH v4 4/4] docs: Add ABI documentation Neil Horman
2015-01-30 17:13   ` [dpdk-dev] [PATCH v4 1/4] compat: Add infrastructure to support symbol versioning Gray, Mark D
2015-01-16 15:33 ` [dpdk-dev] [PATCH v5 " Neil Horman
2015-01-16 15:33   ` [dpdk-dev] [PATCH v5 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-16 15:33   ` [dpdk-dev] [PATCH v5 3/4] Add library version extenstion Neil Horman
2015-01-16 15:33   ` [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation Neil Horman
2015-01-20  7:14     ` Thomas Monjalon
2015-01-20 10:47       ` Bruce Richardson
2015-01-20 13:37       ` Iremonger, Bernard
2015-01-20 13:46         ` Thomas Monjalon
2015-01-20 14:24         ` Neil Horman
2015-01-20 14:29           ` Butler, Siobhan A
2015-01-20 14:41             ` Neil Horman
2015-01-20 14:50               ` Butler, Siobhan A
2015-01-20 15:30                 ` Neil Horman
2015-01-20 14:32           ` O'driscoll, Tim
2015-01-20 14:00     ` Thomas Monjalon
2015-01-20 14:37       ` Neil Horman
2015-01-20 15:06         ` Thomas Monjalon
2015-01-20 15:35           ` Neil Horman
2015-01-20 21:17 ` [dpdk-dev] [PATCH v6 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-20 21:17   ` [dpdk-dev] [PATCH v6 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-20 21:17   ` [dpdk-dev] [PATCH v6 3/4] Add library version extenstion Neil Horman
2015-01-20 21:17   ` [dpdk-dev] [PATCH v6 4/4] docs: Add ABI documentation Neil Horman
2015-01-21 10:13     ` Iremonger, Bernard
2015-01-21 10:25     ` Thomas Monjalon
2015-01-21 14:59       ` Neil Horman
2015-01-21 16:05         ` Thomas Monjalon
2015-01-21 19:43           ` Neil Horman
2015-01-21 22:24             ` Thomas Monjalon
2015-01-22 19:21               ` Neil Horman
2015-01-21 20:57 ` [dpdk-dev] [PATCH v7 01/26] version: 2.0.0-rc0 Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 02/26] mk: fix link to static combined library Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 03/26] eal: fix check for power of 2 in 0 case Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 04/26] ethdev: fix missing parenthesis in mac check Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 05/26] mem: search only dpdk hugetlbfs maps Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 06/26] log: remove unnecessary stubs Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 07/26] vfio: avoid enabling while the module is not loaded Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 08/26] bond: fix vlan flag interpretation Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 09/26] app/testpmd: remove duplicated function for list parsing Neil Horman
2015-01-21 20:57   ` [dpdk-dev] [PATCH v7 10/26] nic_uio: fix thread structure compatibility for future FreeBSD Neil Horman
2015-01-21 20:58   ` [dpdk-dev] [PATCH v7 01/26] version: 2.0.0-rc0 Neil Horman
2015-01-21 20:59 ` [dpdk-dev] [PATCH v7 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-21 20:59   ` [dpdk-dev] [PATCH v7 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-21 20:59   ` [dpdk-dev] [PATCH v7 3/4] Add library version extenstion Neil Horman
2015-01-21 20:59   ` [dpdk-dev] [PATCH v7 4/4] docs: Add ABI documentation Neil Horman
2015-01-22 10:56     ` Iremonger, Bernard
2015-01-22 15:37       ` Neil Horman
2015-01-22 15:49 ` [dpdk-dev] [PATCH v8 1/4] compat: Add infrastructure to support symbol versioning Neil Horman
2015-01-22 15:49   ` [dpdk-dev] [PATCH v8 2/4] Provide initial versioning for all DPDK libraries Neil Horman
2015-01-22 15:49   ` [dpdk-dev] [PATCH v8 3/4] Add library version extenstion Neil Horman
2015-01-22 15:49   ` [dpdk-dev] [PATCH v8 4/4] docs: Add ABI documentation Neil Horman
2015-01-22 16:46     ` Butler, Siobhan A
     [not found] ` <1422898822-16422-1-git-send-email-nhorman@tuxdriver.com>
     [not found]   ` <1422898822-16422-4-git-send-email-nhorman@tuxdriver.com>
2015-02-03 15:24     ` [dpdk-dev] [PATCH v9 " Thomas Monjalon
2015-02-03 16:01 ` [dpdk-dev] Add DSO symbol versioning to supportbackwards compatibility Thomas Monjalon
2015-02-03 20:20   ` 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=20150114202950.GC28492@hmsreliant.think-freely.org \
    --to=nhorman@tuxdriver.com \
    --cc=dev@dpdk.org \
    --cc=thomas.monjalon@6wind.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

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git