From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 3CC63A2EDB for ; Tue, 1 Oct 2019 14:50:05 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 029224C74; Tue, 1 Oct 2019 14:50:04 +0200 (CEST) Received: from EUR04-DB3-obe.outbound.protection.outlook.com (mail-eopbgr60065.outbound.protection.outlook.com [40.107.6.65]) by dpdk.org (Postfix) with ESMTP id 5248944C3 for ; Tue, 1 Oct 2019 14:50:03 +0200 (CEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=gki8ItttrlLbchNyIVVdbWwAjL2nDnSNBdm0FSSy/60uIeSLGSkJhXAe00UsI84ri7iKDu6J7i/deTEUFMutifof98Di7j4MskmS2slt6H0A9leeYyY6S64C8KbZV4pqMZzk2IvHoIclI5huOpnE7rE+QTvsN+2rjVxjO30LCMYW43RlSq42lWxbzO/TDa3LL102SJuT4sPbNUnYYz9vIHpqjDShjNsxS0yIbkBR9JjU9+R+YdtPBy14u92gkvPcwkojsb67C1knVCinsa0A9c3vkz33z4cCr+sTQSicyzu0XhZVudu7j0TgN2xUNlqyPghByvy2Wz3Vz1GmU0s1Yg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=UJlQ/souflrbP2CA4JN27KYUaOHdpe/DNs9QjzwYYSg=; b=iCE6UZbidWvWoMRb+0pD2+dSCtNGBpogiX9OCcc1B8UkWEs99+1+N/zdZBAT9UheeIom1r0RprVk2KaI9AErQFYoJRFfRhkVZkez+5iZCQBk/GMBBRJzBq45yBJi04OUuP5MZoZuFCXKNqJM4u0Ra+z1lxjBX7IWrzvJ/o/akYvUtfkKWA4D10zLWhSyVmI9YJ9LKIH+AdHHnNQ1QJeRTK7WuPV0EnzNhG7GxTIE6wb1h+GVyakpW04oCFCteBYsnlwDtO4ogAqxe5HTexM5Zoa3D0FOwhXfXbgwIwxOssOPv1BNQGp7T6WtTOJGBcliI7W0DSkQ8sUG02HPntH5/Q== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=nxp.com; dmarc=pass action=none header.from=nxp.com; dkim=pass header.d=nxp.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=UJlQ/souflrbP2CA4JN27KYUaOHdpe/DNs9QjzwYYSg=; b=a+DMPZCZVbBYbOjvgpf3bxKvNKGvRQA0FyziL8Jmpev8qdpUVRSwFC3j3vTCqFB5kPGaSBiYOEwyIN+yKElcT8G0lifptw6PVrzZD8HXlGpzSwaRL/0Dl8tnc/PeFKVWUW9dYDGhb/tpp5ttEJQqXPr4jw+8pIrWKZ6ANB6bTVM= Received: from VI1PR0401MB2541.eurprd04.prod.outlook.com (10.168.62.139) by VI1PR0401MB2511.eurprd04.prod.outlook.com (10.168.62.19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2305.20; Tue, 1 Oct 2019 12:50:01 +0000 Received: from VI1PR0401MB2541.eurprd04.prod.outlook.com ([fe80::4103:5f1e:64f9:50df]) by VI1PR0401MB2541.eurprd04.prod.outlook.com ([fe80::4103:5f1e:64f9:50df%8]) with mapi id 15.20.2305.017; Tue, 1 Oct 2019 12:50:01 +0000 From: Hemant Agrawal To: Ray Kinsella , "dev@dpdk.org" CC: "thomas@monjalon.net" , "stephen@networkplumber.org" , "bruce.richardson@intel.com" , "ferruh.yigit@intel.com" , "konstantin.ananyev@intel.com" , "jerinj@marvell.com" , "olivier.matz@6wind.com" , "nhorman@tuxdriver.com" , "maxime.coquelin@redhat.com" , "john.mcnamara@intel.com" , "marko.kovacevic@intel.com" , "ktraynor@redhat.com" , "aconole@redhat.com" Thread-Topic: [PATCH v6 1/4] doc: separate versioning.rst into version and policy Thread-Index: AQHVdVROk0J0o7UZIkW3g4lgFmpHOadFuYUg Date: Tue, 1 Oct 2019 12:50:01 +0000 Message-ID: References: <1569603283-1857-1-git-send-email-mdr@ashroe.eu> <1569603283-1857-2-git-send-email-mdr@ashroe.eu> In-Reply-To: <1569603283-1857-2-git-send-email-mdr@ashroe.eu> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: spf=none (sender IP is ) smtp.mailfrom=hemant.agrawal@nxp.com; x-originating-ip: [92.120.1.66] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 8fdec30f-4e06-41a9-1258-08d7466ddfe3 x-ms-office365-filtering-ht: Tenant x-ms-traffictypediagnostic: VI1PR0401MB2511: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-forefront-prvs: 0177904E6B x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(979002)(4636009)(366004)(136003)(39860400002)(346002)(376002)(396003)(199004)(189003)(229853002)(81156014)(86362001)(2906002)(186003)(476003)(33656002)(76176011)(8936002)(7696005)(8676002)(486006)(81166006)(6246003)(102836004)(26005)(14444005)(66066001)(11346002)(256004)(14454004)(99286004)(6506007)(446003)(76116006)(9686003)(6436002)(25786009)(5660300002)(74316002)(55016002)(52536014)(66556008)(71200400001)(66476007)(316002)(66946007)(305945005)(54906003)(66446008)(64756008)(44832011)(7736002)(478600001)(7416002)(2501003)(71190400001)(110136005)(6116002)(4326008)(3846002)(969003)(989001)(999001)(1009001)(1019001); DIR:OUT; SFP:1101; SCL:1; SRVR:VI1PR0401MB2511; H:VI1PR0401MB2541.eurprd04.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1; received-spf: None (protection.outlook.com: nxp.com does not designate permitted sender hosts) x-ms-exchange-senderadcheck: 1 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: 0MwDCFsU2f1s4cYuKnc0zSZu8I+ZHQuv+73OVtihppVviiH9EpK7ODUAUvacwhed3El/tR6yv9Ow7pP/y/RUnvg5KW/iIjhGza5l5vauyRJrvXAsxMU+1Q+5qFqb2xTybzSmKPINm1OCrkyruAmk5Le8JmVRmKJd0ZSAeUxph+urESm7XLwlFPrFl7gow7hba2qfKuQTu0j4NuUmgcCR+pmbFdFIZ+ce2T1FDPoICIdaTS1H2ls/Z6oFDHqf+6uhs1eEORAk2QvuHdBREEcAh8IW2prFz3ei2XsEiPl3FC4MUFNkeFwRYVqusMn9sIYruRZ0qJU8z47wZ/GZxLSQLyGXMPedt5wZPRvd9ervke9FTm/9Q/ZZQqTElHjumYgkO24L2/oQ4s3JHcAEKIp5AbgheyJHKpKxMyM6ift2/XY= x-ms-exchange-transport-forked: True Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-Network-Message-Id: 8fdec30f-4e06-41a9-1258-08d7466ddfe3 X-MS-Exchange-CrossTenant-originalarrivaltime: 01 Oct 2019 12:50:01.6835 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: cCODcB+gVHWh2rW2JkNc0DByVlYfi5jKFGUzzplCg30LtIbIv1fB5cv/uT7Zx1YEZKSoxWTvj/BVPQVBMM/+YA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR0401MB2511 Subject: Re: [dpdk-dev] [PATCH v6 1/4] doc: separate versioning.rst into version and policy X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Hi Ray, > +DPDK ABI/API policy > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +Description > +----------- > + > +This document details some methods for handling ABI management in the > DPDK. > + > +General Guidelines > +------------------ > + > +#. Whenever possible, ABI should be preserved #. ABI/API may be changed > +with a deprecation process #. The modification of symbols can generally > +be managed with versioning #. Libraries or APIs marked in > +``experimental`` state may change without constraint #. New APIs will > +be marked as ``experimental`` for at least one release to allow > + any issues found by users of the new API to be fixed quickly #. The > +addition of symbols is generally not problematic #. The removal of > +symbols generally is an ABI break and requires bumping of the > + LIBABIVER macro > +#. Updates to the minimum hardware requirements, which drop support > for hardware which > + was previously supported, should be treated as an ABI change. [Hemant] You mean the specific HW pmds?=20 1. Why dropping HW PMD is a ABI change?=20 2. Even if they are supported across releases, there is no guarantee that t= hey are not broken. > + > +What is an ABI > +~~~~~~~~~~~~~~ > + > +An ABI (Application Binary Interface) is the set of runtime interfaces > +exposed by a library. It is similar to an API (Application Programming > +Interface) but is the result of compilation. It is also effectively > +cloned when applications link to dynamic libraries. That is to say > +when an application is compiled to link against dynamic libraries, it > +is assumed that the ABI remains constant between the time the applicatio= n > is compiled/linked, and the time that it runs. > +Therefore, in the case of dynamic linking, it is critical that an ABI > +is preserved, or (when modified), done in such a way that the > +application is unable to behave improperly or in an unexpected fashion. > + > + > +ABI/API Deprecation > +------------------- > + > +The DPDK ABI policy > +~~~~~~~~~~~~~~~~~~~ > + > +ABI versions are set at the time of major release labeling, and the ABI > +may change multiple times, without warning, between the last release > +label and the HEAD label of the git tree. > + > +ABI versions, once released, are available until such time as their > +deprecation has been noted in the Release Notes for at least one major > +release cycle. For example consider the case where the ABI for DPDK 2.0 > +has been shipped and then a decision is made to modify it during the > +development of DPDK 2.1. The decision will be recorded in the Release > +Notes for the DPDK 2.1 release and the modification will be made availab= le > in the DPDK 2.2 release. > + [Hemant] Is it possible to update the DPDK numbering to current versioning= , instead of using old 2.x numbering? > +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. In those cases ABI's may be updated without backward > +compatibility being provided. The requirements for doing so are: > + > +#. At least 3 acknowledgments of the need to do so must be made on the > + dpdk.org mailing list. > + > + - The acknowledgment of the maintainer of the component is mandatory, > or if > + no maintainer is available for the component, the tree/sub-tree > maintainer > + for that component must acknowledge the ABI change instead. > + > + - It is also recommended that acknowledgments from different "areas o= f > + interest" be sought for each deprecation, for example: from NIC > vendors, > + CPU vendors, end-users, etc. > + > +#. The changes (including an alternative map file) can be included with > + deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option, > + to provide more details about oncoming changes. > + ``RTE_NEXT_ABI`` wrapper will be removed when it become the default > ABI. [Hemant] The older implementation will or can be removed at this point of = time?=20