From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id D84205AA2 for ; Thu, 22 Jan 2015 17:46:40 +0100 (CET) Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by orsmga103.jf.intel.com with ESMTP; 22 Jan 2015 08:42:36 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.09,450,1418112000"; d="scan'208";a="654987132" Received: from irsmsx101.ger.corp.intel.com ([163.33.3.153]) by fmsmga001.fm.intel.com with ESMTP; 22 Jan 2015 08:46:37 -0800 Received: from irsmsx109.ger.corp.intel.com ([169.254.13.11]) by IRSMSX101.ger.corp.intel.com ([169.254.1.245]) with mapi id 14.03.0195.001; Thu, 22 Jan 2015 16:46:36 +0000 From: "Butler, Siobhan A" To: Neil Horman , "dev@dpdk.org" Thread-Topic: [dpdk-dev] [PATCH v8 4/4] docs: Add ABI documentation Thread-Index: AQHQNlsaeN5fX8fZ/UeiK4NqTI4DA5zMWNxA Date: Thu, 22 Jan 2015 16:46:36 +0000 Message-ID: <0C5AFCA4B3408848ADF2A3073F7D8CC86D4C27A7@IRSMSX109.ger.corp.intel.com> References: <1419109299-9603-1-git-send-email-nhorman@tuxdriver.com> <1421941756-30948-1-git-send-email-nhorman@tuxdriver.com> <1421941756-30948-4-git-send-email-nhorman@tuxdriver.com> In-Reply-To: <1421941756-30948-4-git-send-email-nhorman@tuxdriver.com> Accept-Language: en-IE, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [163.33.239.181] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Subject: Re: [dpdk-dev] [PATCH v8 4/4] docs: Add ABI documentation 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: Thu, 22 Jan 2015 16:46:42 -0000 > -----Original Message----- > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman > Sent: Thursday, January 22, 2015 3:49 PM > To: dev@dpdk.org > Subject: [dpdk-dev] [PATCH v8 4/4] docs: Add ABI documentation >=20 > Adding a document describing rudimentary ABI policy and adding notice > space for any deprecation announcements >=20 > Signed-off-by: Neil Horman > CC: Thomas Monjalon > CC: "Richardson, Bruce" >=20 > --- > Change notes: >=20 > v5) Updated documentation to add notes from Thomas M. >=20 > v6) Moved abi.txt to guides/rel_notes/abi.rst >=20 > v7) Updated abi.rst to integrate with index file > Updated abi.rst to conform to rst formatting > Updated abi.rst to include example deprecation notices. Its not exac= tly the > language that Thomas indicated, but I think it makes the idea clear. >=20 > v8) Add missing file index.rst which was left out of the prior commit > --- > doc/guides/rel_notes/abi.rst | 40 > ++++++++++++++++++++++++++++++++++++++++ > doc/guides/rel_notes/index.rst | 1 + > 2 files changed, 41 insertions(+) > create mode 100644 doc/guides/rel_notes/abi.rst >=20 > diff --git a/doc/guides/rel_notes/abi.rst b/doc/guides/rel_notes/abi.rst = new > file mode 100644 index 0000000..73d88ca > --- /dev/null > +++ b/doc/guides/rel_notes/abi.rst > @@ -0,0 +1,40 @@ > +ABI policy > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > +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: > + > +#. At least 3 acknoweldgements of the need on the dpdk.org #. 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 #. 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 cause ABI > +breakage. Only significant (e.g. performance) reasons should be seen as > cause to alter ABI. > + > +Examples of Deprecation notices > +------------------------------- > +* The Macro #RTE_FOO is deprecated and will be removed with version > +2.0, to be replaced with the inline function rte_bar() > +* The function rte_mbuf_grok has been updated to include new parameter > +in version 2.0. Backwards compatibility will be maintained for this > +function until the release of version 2.1 > +* The members struct foo have been reorganized in release 2.0. Existing > binary applications will have backwards compatibility in release 2.0, whi= le > newly built binaries will need to reference new structure variant struct = foo2. > Compatibility will be removed in release 2.2, and all applications will r= equire > updating a rebuilding to the new structure at that time, which will be > renamed to the origional struct foo. > +* Significant ABI changes are planned for the librte_dostuff library. T= he > upcomming release 2.0 will not contain these changes, but release 2.1 wil= l, > and no backwards compatibility is planned due to the invasive nature of > these changes. Binaries using this library built prior to version 2.1 wi= ll require > updating and recompilation. > + > +Deprecation Notices > +------------------- > diff --git a/doc/guides/rel_notes/index.rst b/doc/guides/rel_notes/index.= rst > index 2724149..cf712b2 100644 > --- a/doc/guides/rel_notes/index.rst > +++ b/doc/guides/rel_notes/index.rst > @@ -48,4 +48,5 @@ Contents > updating_apps > known_issues > resolved_issues > + abi > faq > -- > 2.1.0 Acked-by: Siobhan Butler