DPDK patches and discussions
 help / color / mirror / Atom feed
From: Thomas Monjalon <thomas.monjalon@6wind.com>
To: Neil Horman <nhorman@tuxdriver.com>
Cc: dev@dpdk.org
Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
Date: Tue, 20 Jan 2015 16:06:07 +0100
Message-ID: <3451650.yEcfPMJlme@xps13> (raw)
In-Reply-To: <20150120143737.GB18449@hmsreliant.think-freely.org>

2015-01-20 09:37, Neil Horman:
> On Tue, Jan 20, 2015 at 03:00:01PM +0100, Thomas Monjalon wrote:
> > 2015-01-16 10:33, Neil Horman:
> > > --- /dev/null
> > > +++ b/doc/abi.txt
> > > @@ -0,0 +1,36 @@
> > > +ABI policy:
> > > +	ABI versions are set at the time of major release labeling, and ABI may
> > > +change multiple times between the last labeling and the HEAD label of the git
> > > +tree without warning
> > > +
> > > +	ABI versions, once released are available until such time as their
> > > +deprecation has been noted here for at least one major release cycle, after it
> > > +has been tagged.  E.g. the ABI for DPDK 1.8 is shipped, and then the decision to
> > > +remove it is made during the development of DPDK 1.9.  The decision will be
> > > +recorded here, shipped with the DPDK 1.9 release, and actually removed when DPDK
> > > +1.10 ships.
> > > +
> > > +	ABI versions may be deprecated in whole, or in part as needed by a given
> > > +update.
> > > +
> > > +	Some ABI changes may be too significant to reasonably maintain multiple
> > > +versions of.  In those events ABI's may be updated without backward
> > > +compatibility provided.  The requirements for doing so are:
> > > +	1) At least 3 acknoweldgements of the need on the dpdk.org
> > > +	2) A full deprecation cycle must be made to offer downstream consumers
> > > +sufficient warning of the change.  E.g. if dpdk 2.0 is under development when
> > > +the change is proposed, a deprecation notice must be added to this file, and
> > > +released with dpdk 2.0.  Then the change may be incorporated for dpdk 2.1
> > > +	3) The LIBABIVER variable in the makefilei(s) where the ABI changes are
> > > +incorporated must be incremented in parallel with the ABI changes themselves
> > > +
> > > +	Note that the above process for ABI deprecation should not be undertaken
> > > +lightly.  ABI stability is extreemely important for downstream consumers of the
> > > +DPDK, especially when distributed in shared object form.  Every effort should be
> > > +made to preserve ABI whenever possible.  For instance, reorganizing public
> > > +structure field for astetic or readability purposes should be avoided as it will
> > 
> > astetic? typo?
> > 
> > > +cause ABI breakage.  Only significant (e.g. performance) reasons should be seen
> > > +as cause to alter ABI.
> > > +  
> > > +Deprecation Notices:
> > 
> > Neil, are you sure it's a good idea to put deprecations notices here instead
> > of release notes?
> > 
> Funny, I just made mention of that in my last note.  I do think that the release
> notes is the right place to "officially" announce deprecation warnings, but I
> think we need a way for developers to communicate that efficiently (given that
> the release notes aren't stored in the git tree).

Yes, they are:
	http://dpdk.org/browse/dpdk/tree/doc/guides/rel_notes
So I suggest to remove Deprecation Notices from abi.txt and create an entry
in release notes.

> I think this is the place for
> developers to canonically list deprecations, and make reading this file part of
> the release notes generation process.  That way, updates can be made as part of
> the commit process easily.

Developpers can update the release notes themselves.

> > I'm also thinking that we need to add more things in this doc:
> > 	- case of macros/constant deprecation (API only)
> > 	- case of structure update: must be renamed to provide ABI compatibility?
> > 
> I'm definately in favor of adding such notices here, but I hadn't planned for
> any strict formatting of any given notice.  That is to say, I considered you're
> two issues above to be able to be included here.  I have no issue with listing a
> deprecation note that indicates macros are being removed or that sections of api
> are being versioned to accomodate structure changes. of any sort

No, I was suggesting to explain in this doc that macro removal must be
announced with a deprecation notice,
and that in case structure must be reworked, the name must change if we
want to preserve ABI compatibility with old structure.

> > Do you think we can have a tool to test the ABI compatibility by building
> > examples/apps of previous version and checking them with built DSO of
> > current version?
> > 
> I do, though I'm not sure its within the scope of this update.  The easiest way
> to do it currently is to checkout the last released version of the dpdk, build
> it as a DSO build, copy out one of the test/example apps, checkout the HEAD of
> the tree, rebuild, and run the saved off test app from the first build using the
> shared objects of the second build.  That does some rudimentary validation,
> but it only touches on the API aspects that the application you're using makes
> use of.  What would be better would be if we had a test application that made a
> call to every exported API call that we have, so that we could be confident that
> we were exhaustively testing the ABI surface.  I think thats a large piece of
> work, but it would be beneficial to have.

Yes, it should be another patchset.
Do you plan to work on it? It would be very convenient for developpers and
maintainers to test ABI compatibility.

Thanks
-- 
Thomas

  reply	other threads:[~2015-01-20 15:06 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
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 [this message]
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=3451650.yEcfPMJlme@xps13 \
    --to=thomas.monjalon@6wind.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

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