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 012BFA00BE; Fri, 15 May 2020 17:02:14 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id B9E391DACF; Fri, 15 May 2020 17:02:13 +0200 (CEST) Received: from qrelay19.mxroute.com (qrelay19.mxroute.com [172.82.139.19]) by dpdk.org (Postfix) with ESMTP id A40051DACF for ; Fri, 15 May 2020 17:02:11 +0200 (CEST) Received: from filter004.mxroute.com ([149.28.56.236] 149.28.56.236.vultr.com) (Authenticated sender: mN4UYu2MZsgR) by qrelay19.mxroute.com (ZoneMTA) with ESMTPA id 17218db5c56000add6.002 for ; Fri, 15 May 2020 15:02:08 +0000 X-Zone-Loop: 049eec84a3e880371059dcf9a702f0acfef403bf1bc0 X-Originating-IP: [149.28.56.236] Received: from galaxy.mxroute.com (unknown [23.92.70.113]) by filter004.mxroute.com (Postfix) with ESMTPS id 0F1413E83E; Fri, 15 May 2020 15:02:06 +0000 (UTC) Received: from [192.198.151.44] (helo=localhost) by galaxy.mxroute.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128) (Exim 4.91) (envelope-from ) id 1jZbPA-0001gN-No; Fri, 15 May 2020 10:33:41 -0400 From: Ray Kinsella To: dev@dpdk.org Cc: Ferruh Yigit , Ray Kinsella , Neil Horman , Thomas Monjalon , Luca Boccassi , David Marchand , Bruce Richardson , Ian Stokes , Eelco Chaudron , Andrzej Ostruszka , Kevin Traynor , John McNamara , Marko Kovacevic , Cristian Dumitrescu Date: Fri, 15 May 2020 16:01:53 +0100 Message-Id: <1589554922-4549-1-git-send-email-mdr@ashroe.eu> X-Mailer: git-send-email 2.7.4 In-Reply-To: <20200514161104.1546493-1-ferruh.yigit@intel.com> References: <20200513121149.2283385-1-ferruh.yigit@intel.com> <20200514161104.1546493-1-ferruh.yigit@intel.com> X-AuthUser: mdr@ashroe.eu Subject: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps 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" From: Ferruh Yigit On v20.02 some APIs matured and symbols moved from EXPERIMENTAL to DPDK_20.0.1 block. This had the affect of breaking the applications that were using these APIs on v19.11. Although there is no modification of the APIs and the action is positive and matures the APIs, the affect can be negative to applications. When a maintainer is promoting an API to become part of the next major ABI version by removing the experimental tag. The maintainer may choose to offer an alias to the experimental tag, to prevent these breakages in future. The following changes are made to enabling aliasing: Updated to the abi policy and abi versioning documents. Created VERSION_SYMBOL_EXPERIMENTAL helper macro. Updated the 'check-symbols.sh' buildtool, which was complaining that the symbol is in EXPERIMENTAL tag in .map file but it is not in the .experimental section (__rte_experimental tag is missing). Updated tool in a way it won't complain if the symbol in the EXPERIMENTAL tag duplicated in some other block in .map file (versioned) Signed-off-by: Ferruh Yigit Signed-off-by: Ray Kinsella --- This patch depends on "doc: fix references to bind_default_symbol". https://patches.dpdk.org/patch/69850/ Cc: Neil Horman Cc: Thomas Monjalon Cc: Luca Boccassi Cc: David Marchand Cc: Bruce Richardson Cc: Ian Stokes Cc: Eelco Chaudron Cc: Andrzej Ostruszka Cc: Ray Kinsella CC: Kevin Traynor v2: * Commit log updated v3: * added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro v4: * update script name in commit log, remove empty line v5: * incorporate policy and version doc changes * remove changes to librte_meter v6: * clarified dependency chain includes "doc: fix references to bind_default_symbol". buildtools/check-symbols.sh | 3 +- doc/guides/contributing/abi_policy.rst | 10 ++ doc/guides/contributing/abi_versioning.rst | 158 ++++++++++++++++++++++- lib/librte_eal/include/rte_function_versioning.h | 9 ++ 4 files changed, 178 insertions(+), 2 deletions(-) diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh index 3df57c3..e407553 100755 --- a/buildtools/check-symbols.sh +++ b/buildtools/check-symbols.sh @@ -26,7 +26,8 @@ ret=0 for SYM in `$LIST_SYMBOL -S EXPERIMENTAL $MAPFILE |cut -d ' ' -f 3` do if grep -q "\.text.*[[:space:]]$SYM$" $DUMPFILE && - ! grep -q "\.text\.experimental.*[[:space:]]$SYM$" $DUMPFILE + ! grep -q "\.text\.experimental.*[[:space:]]$SYM$" $DUMPFILE && + $LIST_SYMBOL -s $SYM $MAPFILE | grep -q EXPERIMENTAL then cat >&2 <<- END_OF_MESSAGE $SYM is not flagged as experimental diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst index 86e7dd9..c33bff1 100644 --- a/doc/guides/contributing/abi_policy.rst +++ b/doc/guides/contributing/abi_policy.rst @@ -160,6 +160,11 @@ The requirements for changing the ABI are: ``experimental``, as described in the section on :ref:`Experimental APIs and Libraries `. + - In situations in which an ``experimental`` symbol has been stable for some + time. When promoting the symbol to become part of the next ABI version, the + maintainer may choose to provide an alias to the ``experimental`` tag, so + as not to break consuming applications. + #. If a newly proposed API functionally replaces an existing one, when the new API becomes non-experimental, then the old one is marked with ``__rte_deprecated``. @@ -318,6 +323,11 @@ not required. Though, an API should remain in experimental state for at least one release. Thereafter, the normal process of posting patch for review to mailing list can be followed. +After the experimental tag has been formally removed, a tree/sub-tree maintainer +may choose to offer an alias to the experimental tag so as not to break +applications using the symbol. The alias is then dropped at the declaration of +next major ABI version. + Libraries ~~~~~~~~~ diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst index 7065979..27b5231 100644 --- a/doc/guides/contributing/abi_versioning.rst +++ b/doc/guides/contributing/abi_versioning.rst @@ -156,6 +156,11 @@ The macros exported are: ``be`` to signal that it is being used as an implementation of a particular version of symbol ``b``. +* ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry + binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``. + The macro is used when a symbol matures to become part of the stable ABI, to + provide an alias to experimental for some time. + .. _example_abi_macro_usage: Examples of ABI Macro use @@ -361,7 +366,7 @@ and a new DPDK_21 version, used by future built applications. .. note:: **Before you leave**, please take care to the review the sections on - :ref:`Mapping static symbols `, :ref:`Enabling + :ref:`mapping static symbols `, :ref:`enabling versioning macros ` and :ref:`ABI deprecation `. @@ -415,6 +420,157 @@ at the start of the head of the file. This will indicate to the tool-chain to enable the function version macros when building. There is no corresponding directive required for the ``make`` build system. +.. _aliasing_experimental_symbols: + +Aliasing experimental symbols +_____________________________ + +In situations in which an ``experimental`` symbol has been stable for some time, +and it becomes a candidate for promotion to the stable ABI. At this time, when +promoting the symbol, maintainer may choose to provide an alias to the +``experimental`` symbol version, so as not to break consuming applications. + +The process to provide an alias to ``experimental`` is similar to that, of +:ref:`symbol visioning ` described above. Assume we +have an experimental function ``rte_acl_create`` as follows + +.. code-block:: c + + #include ; + + /* + * Create an acl context object for apps to + * manipulate + */ + __rte_experimental + struct rte_acl_ctx * + rte_acl_create(const struct rte_acl_param *param) + { + ... + } + +In the map file, experimental symbols are listed as part of the ``experimental`` +version node. + +.. code-block:: none + + DPDK_20 { + global: + ... + + local: *; + }; + + EXPERIMENTAL { + global: + + rte_acl_create; + }; + +When we promote the symbol to the stable ABI, we simply strip the +``rte_experimental`` annotation from the function and move the symbol from the +``experimental`` node, to the node of the next major ABI version as follow. + +.. code-block:: c + + /* + * Create an acl context object for apps to + * manipulate + */ + struct rte_acl_ctx * + rte_acl_create(const struct rte_acl_param *param) + { + ... + } + +We then update the map file, adding the symbol ``rte_acl_create`` to the ``v21`` +version node. + +.. code-block:: none + + DPDK_20 { + global: + ... + + local: *; + }; + + DPDK_21 { + global: + + rte_acl_create; + } DPDK_20; + + +Although there are strictly no guarantees or commitments associated with +:ref:`experimental symbols `, a maintainer may wish to offer +an alias to experimental. The process to add an alias to experimental, is +similar to the symbol versioning process. Assuming we have an experimental +symbol as before, we now add the symbol to both the ``experimental`` and ``v21`` +version nodes. + +.. code-block:: c + + #include ; + #include ; + + /* + * Create an acl context object for apps to + * manipulate + */ + struct rte_acl_ctx * + rte_acl_create(const struct rte_acl_param *param) + { + ... + } + + __rte_experimental + struct rte_acl_ctx * + rte_acl_create_e(const struct rte_acl_param *param) + { + return rte_acl_create(param); + } + VERSION_SYMBOL_EXPERIMENTAL(rte_acl_create, _e); + + struct rte_acl_ctx * + rte_acl_create_v21(const struct rte_acl_param *param) + { + return rte_acl_create(param); + } + BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 21); + + +In the map file, we map the symbol to both the experimental and ``v21`` version +nodes. + +.. code-block:: none + + DPDK_20 { + global: + ... + + local: *; + }; + + DPDK_21 { + global: + + rte_acl_create; + } DPDK_20; + + EXPERIMENTAL { + global: + + rte_acl_create; + }; + +.. note:: + + Please note, similar to :ref:`symbol visioning ` + when aliasing to experimental you will also need to take care of + :ref:`mapping static symbols `. + + .. _abi_decprecation: Deprecating part of a public API diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h index b9f862d..f588f26 100644 --- a/lib/librte_eal/include/rte_function_versioning.h +++ b/lib/librte_eal/include/rte_function_versioning.h @@ -47,6 +47,14 @@ #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n)) /* + * VERSION_SYMBOL_EXPERIMENTAL + * Creates a symbol version table entry binding the symbol @EXPERIMENTAL to the internal + * function name . The macro is used when a symbol matures to become part of the stable ABI, + * to provide an alias to experimental for some time. + */ +#define VERSION_SYMBOL_EXPERIMENTAL(b, e) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@EXPERIMENTAL") + +/* * BIND_DEFAULT_SYMBOL * Creates a symbol version entry instructing the linker to bind references to * symbol to the internal symbol @@ -79,6 +87,7 @@ * No symbol versioning in use */ #define VERSION_SYMBOL(b, e, n) +#define VERSION_SYMBOL_EXPERIMENTAL(b, e) #define __vsym #define BIND_DEFAULT_SYMBOL(b, e, n) #define MAP_STATIC_SYMBOL(f, p) f __attribute__((alias(RTE_STR(p)))) -- 2.7.4