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 14D301B00F for ; Wed, 13 Dec 2017 16:18:22 +0100 (CET) Received: from cpe-2606-a000-111b-423c-e874-da8e-c543-d863.dyn6.twc.com ([2606:a000:111b:423c:e874:da8e:c543:d863] helo=hmswarspite.think-freely.org) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1eP8nU-0003Qs-W9; Wed, 13 Dec 2017 10:18:17 -0500 Received: from hmswarspite.think-freely.org (localhost [127.0.0.1]) by hmswarspite.think-freely.org (8.15.2/8.15.2) with ESMTP id vBDFHePo016817; Wed, 13 Dec 2017 10:17:40 -0500 Received: (from nhorman@localhost) by hmswarspite.think-freely.org (8.15.2/8.15.2/Submit) id vBDFHeWA016816; Wed, 13 Dec 2017 10:17:40 -0500 From: Neil Horman To: dev@dpdk.org Cc: thomas@monjalon.net, john.mcnamara@intel.com, bruce.richardson@intel.com, Neil Horman Date: Wed, 13 Dec 2017 10:17:28 -0500 Message-Id: <20171213151728.16747-6-nhorman@tuxdriver.com> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20171213151728.16747-1-nhorman@tuxdriver.com> References: <20171201185628.16261-1-nhorman@tuxdriver.com> <20171213151728.16747-1-nhorman@tuxdriver.com> X-Spam-Score: -2.9 (--) X-Spam-Status: No Subject: [dpdk-dev] [PATCHv4 5/5] doc: Add ABI __experimental tag documentation 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: , X-List-Received-Date: Wed, 13 Dec 2017 15:18:23 -0000 Document the need to add the __experimental tag to appropriate functions Signed-off-by: Neil Horman CC: Thomas Monjalon CC: "Mcnamara, John" CC: Bruce Richardson --- doc/guides/contributing/versioning.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst index 400090628..53f56397e 100644 --- a/doc/guides/contributing/versioning.rst +++ b/doc/guides/contributing/versioning.rst @@ -50,6 +50,15 @@ those new APIs and start finding issues with them, new DPDK APIs will be automatically marked as ``experimental`` to allow for a period of stabilization before they become part of a tracked ABI. +Note that marking an API as experimental is a two step process. To mark an API +as experimental, the symbols which are desired to be exported must be placed in +an EXPERIMENTAL version block in the corresponding libraries' version map +script. Secondly, the corresponding definitions of those exported functions, and +their forward declarations (in the development header files), must be marked +with the __experimental tag (see rte_compat.h). The DPDK build makefiles +preform a check to ensure that the map file and the C code reflect the same +list of symbols. + 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 -- 2.14.3