Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/62828/?format=api
{ "id": 62828, "url": "http://patches.dpdk.org/api/patches/62828/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/1573473478-8669-2-git-send-email-mdr@ashroe.eu/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<1573473478-8669-2-git-send-email-mdr@ashroe.eu>", "list_archive_url": "https://inbox.dpdk.org/dev/1573473478-8669-2-git-send-email-mdr@ashroe.eu", "date": "2019-11-11T11:57:56", "name": "[v11,1/3] doc: separate versioning.rst into version and policy", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": true, "hash": "afc6b7f9caab28e90a52487d9cd67cb045f6cca2", "submitter": { "id": 1310, "url": "http://patches.dpdk.org/api/people/1310/?format=api", "name": "Ray Kinsella", "email": "mdr@ashroe.eu" }, "delegate": { "id": 1, "url": "http://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/1573473478-8669-2-git-send-email-mdr@ashroe.eu/mbox/", "series": [ { "id": 7383, "url": "http://patches.dpdk.org/api/series/7383/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=7383", "date": "2019-11-11T11:57:55", "name": "doc: changes to abi policy introducing major abi versions", "version": 11, "mbox": "http://patches.dpdk.org/series/7383/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/62828/comments/", "check": "warning", "checks": "http://patches.dpdk.org/api/patches/62828/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from dpdk.org (dpdk.org [92.243.14.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 40E21A04B8;\n\tMon, 11 Nov 2019 12:58:17 +0100 (CET)", "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id A88C929C6;\n\tMon, 11 Nov 2019 12:58:14 +0100 (CET)", "from q2relay135.mxroute.com (q2relay135.mxroute.com\n [160.202.107.135]) by dpdk.org (Postfix) with ESMTP id 526A329AC\n for <dev@dpdk.org>; Mon, 11 Nov 2019 12:58:13 +0100 (CET)", "from filter003.mxroute.com [168.235.111.26] (Authenticated sender:\n mN4UYu2MZsgR)\n by q2relay135.mxroute.com (ZoneMTA) with ESMTPSA id 16e5a540e33000f0dc.002\n for <dev@dpdk.org>\n (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES128-GCM-SHA256);\n Mon, 11 Nov 2019 11:58:08 +0000", "from galaxy.mxroute.com (unknown [23.92.70.113])\n by filter003.mxroute.com (Postfix) with ESMTPS id 037E261147;\n Mon, 11 Nov 2019 11:58:06 +0000 (UTC)", "from [192.198.151.43] (helo=localhost)\n by galaxy.mxroute.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128)\n (Exim 4.91) (envelope-from <mdr@ashroe.eu>)\n id 1iU882-0003tP-Lh; Mon, 11 Nov 2019 06:45:07 -0500" ], "X-Zone-Loop": "50db42260e83f45488105e9832bb59934ba23ccbd2c4", "X-Originating-IP": "[168.235.111.26]", "From": "Ray Kinsella <mdr@ashroe.eu>", "To": "dev@dpdk.org", "Cc": "mdr@ashroe.eu, thomas@monjalon.net, stephen@networkplumber.org,\n bruce.richardson@intel.com, ferruh.yigit@intel.com,\n konstantin.ananyev@intel.com, jerinj@marvell.com, olivier.matz@6wind.com,\n nhorman@tuxdriver.com, maxime.coquelin@redhat.com, john.mcnamara@intel.com,\n marko.kovacevic@intel.com, hemant.agrawal@nxp.com, ktraynor@redhat.com,\n aconole@redhat.com", "Date": "Mon, 11 Nov 2019 11:57:56 +0000", "Message-Id": "<1573473478-8669-2-git-send-email-mdr@ashroe.eu>", "X-Mailer": "git-send-email 2.7.4", "In-Reply-To": "<1573473478-8669-1-git-send-email-mdr@ashroe.eu>", "References": "<1573217185-4101-1-git-send-email-mdr@ashroe.eu>\n <1573473478-8669-1-git-send-email-mdr@ashroe.eu>", "X-AuthUser": "mdr@ashroe.eu", "Subject": "[dpdk-dev] [PATCH v11 1/3] doc: separate versioning.rst into\n\tversion and policy", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Separate versioning.rst into abi versioning and abi policy guidance, in\npreparation for adding more detail to the abi policy. Add an entry to the\nmaintainer file for the abi policy.\n\nSigned-off-by: Ray Kinsella <mdr@ashroe.eu>\nAcked-by: John Mcnamara <john.mcnamara@intel.com>\nAcked-by: Stephen Hemminger <stephen@networkplumber.org>\n---\n MAINTAINERS | 4 +\n doc/guides/contributing/abi_policy.rst | 167 ++++++++\n doc/guides/contributing/abi_versioning.rst | 433 +++++++++++++++++++++\n doc/guides/contributing/index.rst | 3 +-\n doc/guides/contributing/patches.rst | 2 +-\n doc/guides/contributing/versioning.rst | 597 -----------------------------\n doc/guides/rel_notes/deprecation.rst | 2 +-\n 7 files changed, 608 insertions(+), 600 deletions(-)\n create mode 100644 doc/guides/contributing/abi_policy.rst\n create mode 100644 doc/guides/contributing/abi_versioning.rst\n delete mode 100644 doc/guides/contributing/versioning.rst", "diff": "diff --git a/MAINTAINERS b/MAINTAINERS\nindex e8d79ea..aedb593 100644\n--- a/MAINTAINERS\n+++ b/MAINTAINERS\n@@ -84,6 +84,10 @@ M: Marko Kovacevic <marko.kovacevic@intel.com>\n F: README\n F: doc/\n \n+ABI Policy\n+M: Ray Kinsella <mdr@ashroe.eu>\n+F: doc/guides/contributing/abi_*.rst\n+\n Developers and Maintainers Tools\n M: Thomas Monjalon <thomas@monjalon.net>\n F: MAINTAINERS\ndiff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst\nnew file mode 100644\nindex 0000000..d4f4e9f\n--- /dev/null\n+++ b/doc/guides/contributing/abi_policy.rst\n@@ -0,0 +1,167 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright 2018 The DPDK contributors\n+\n+DPDK ABI/API policy\n+===================\n+\n+Description\n+-----------\n+\n+This document details some methods for handling ABI management in the DPDK.\n+\n+General Guidelines\n+------------------\n+\n+#. Whenever possible, ABI should be preserved\n+#. ABI/API may be changed with a deprecation process\n+#. The modification of symbols can generally be managed with versioning\n+#. Libraries or APIs marked in ``experimental`` state may change without constraint\n+#. New APIs will be marked as ``experimental`` for at least one release to allow\n+ any issues found by users of the new API to be fixed quickly\n+#. The addition of symbols is generally not problematic\n+#. The removal of symbols generally is an ABI break and requires bumping of the\n+ LIBABIVER macro\n+#. Updates to the minimum hardware requirements, which drop support for hardware which\n+ was previously supported, should be treated as an ABI change.\n+\n+What is an ABI\n+~~~~~~~~~~~~~~\n+\n+An ABI (Application Binary Interface) is the set of runtime interfaces exposed\n+by a library. It is similar to an API (Application Programming Interface) but\n+is the result of compilation. It is also effectively cloned when applications\n+link to dynamic libraries. That is to say when an application is compiled to\n+link against dynamic libraries, it is assumed that the ABI remains constant\n+between the time the application is compiled/linked, and the time that it runs.\n+Therefore, in the case of dynamic linking, it is critical that an ABI is\n+preserved, or (when modified), done in such a way that the application is unable\n+to behave improperly or in an unexpected fashion.\n+\n+\n+ABI/API Deprecation\n+-------------------\n+\n+The DPDK ABI policy\n+~~~~~~~~~~~~~~~~~~~\n+\n+ABI versions are set at the time of major release labeling, and the ABI may\n+change multiple times, without warning, between the last release label and the\n+HEAD label of the git tree.\n+\n+ABI versions, once released, are available until such time as their\n+deprecation has been noted in the Release Notes for at least one major release\n+cycle. For example consider the case where the ABI for DPDK 2.0 has been\n+shipped and then a decision is made to modify it during the development of\n+DPDK 2.1. The decision will be recorded in the Release Notes for the DPDK 2.1\n+release and the modification will be made available in the DPDK 2.2 release.\n+\n+ABI versions may be deprecated in whole or in part as needed by a given\n+update.\n+\n+Some ABI changes may be too significant to reasonably maintain multiple\n+versions. In those cases ABI's may be updated without backward compatibility\n+being provided. The requirements for doing so are:\n+\n+#. At least 3 acknowledgments of the need to do so must be made on the\n+ dpdk.org mailing list.\n+\n+ - The acknowledgment of the maintainer of the component is mandatory, or if\n+ no maintainer is available for the component, the tree/sub-tree maintainer\n+ for that component must acknowledge the ABI change instead.\n+\n+ - It is also recommended that acknowledgments from different \"areas of\n+ interest\" be sought for each deprecation, for example: from NIC vendors,\n+ CPU vendors, end-users, etc.\n+\n+#. The changes (including an alternative map file) can be included with\n+ deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option,\n+ to provide more details about oncoming changes.\n+ ``RTE_NEXT_ABI`` wrapper will be removed when it become the default ABI.\n+ More preferred way to provide this information is sending the feature\n+ as a separate patch and reference it in deprecation notice.\n+\n+#. A full deprecation cycle, as explained above, must be made to offer\n+ downstream consumers sufficient warning of the change.\n+\n+Note that the above process for ABI deprecation should not be undertaken\n+lightly. ABI stability is extremely important for downstream consumers of the\n+DPDK, especially when distributed in shared object form. Every effort should\n+be made to preserve the ABI whenever possible. The ABI should only be changed\n+for significant reasons, such as performance enhancements. ABI breakage due to\n+changes such as reorganizing public structure fields for aesthetic or\n+readability purposes should be avoided.\n+\n+.. note::\n+\n+ Updates to the minimum hardware requirements, which drop support for hardware\n+ which was previously supported, should be treated as an ABI change, and\n+ follow the relevant deprecation policy procedures as above: 3 acks and\n+ announcement at least one release in advance.\n+\n+Examples of Deprecation Notices\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+The following are some examples of ABI deprecation notices which would be\n+added to the Release Notes:\n+\n+* The Macro ``#RTE_FOO`` is deprecated and will be removed with version 2.0,\n+ to be replaced with the inline function ``rte_foo()``.\n+\n+* The function ``rte_mbuf_grok()`` has been updated to include a new parameter\n+ in version 2.0. Backwards compatibility will be maintained for this function\n+ until the release of version 2.1\n+\n+* The members of ``struct rte_foo`` have been reorganized in release 2.0 for\n+ performance reasons. Existing binary applications will have backwards\n+ compatibility in release 2.0, while newly built binaries will need to\n+ reference the new structure variant ``struct rte_foo2``. Compatibility will\n+ be removed in release 2.2, and all applications will require updating and\n+ rebuilding to the new structure at that time, which will be renamed to the\n+ original ``struct rte_foo``.\n+\n+* Significant ABI changes are planned for the ``librte_dostuff`` library. The\n+ upcoming release 2.0 will not contain these changes, but release 2.1 will,\n+ and no backwards compatibility is planned due to the extensive nature of\n+ these changes. Binaries using this library built prior to version 2.1 will\n+ require updating and recompilation.\n+\n+New API replacing previous one\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+If a new API proposed functionally replaces an existing one, when the new API\n+becomes non-experimental then the old one is marked with ``__rte_deprecated``.\n+Deprecated APIs are removed completely just after the next LTS.\n+\n+Reminder that old API should follow deprecation process to be removed.\n+\n+\n+Experimental APIs\n+-----------------\n+\n+APIs marked as ``experimental`` are not considered part of the ABI and may\n+change without warning at any time. Since changes to APIs are most likely\n+immediately after their introduction, as users begin to take advantage of\n+those new APIs and start finding issues with them, new DPDK APIs will be\n+automatically marked as ``experimental`` to allow for a period of stabilization\n+before they become part of a tracked ABI.\n+\n+Note that marking an API as experimental is a multi step process.\n+To mark an API as experimental, the symbols which are desired to be exported\n+must be placed in an EXPERIMENTAL version block in the corresponding libraries'\n+version map script.\n+Secondly, the corresponding prototypes of those exported functions (in the\n+development header files), must be marked with the ``__rte_experimental`` tag\n+(see ``rte_compat.h``).\n+The DPDK build makefiles perform a check to ensure that the map file and the\n+C code reflect the same list of symbols.\n+This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``\n+during compilation in the corresponding library Makefile.\n+\n+In addition to tagging the code with ``__rte_experimental``,\n+the doxygen markup must also contain the EXPERIMENTAL string,\n+and the MAINTAINERS file should note the EXPERIMENTAL libraries.\n+\n+For removing the experimental tag associated with an API, deprecation notice\n+is not required. Though, an API should remain in experimental state for at least\n+one release. Thereafter, normal process of posting patch for review to mailing\n+list can be followed.\ndiff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst\nnew file mode 100644\nindex 0000000..d278de4\n--- /dev/null\n+++ b/doc/guides/contributing/abi_versioning.rst\n@@ -0,0 +1,433 @@\n+.. SPDX-License-Identifier: BSD-3-Clause\n+ Copyright 2018 The DPDK contributors\n+\n+.. library_versioning:\n+\n+Library versioning\n+------------------\n+\n+Downstreams might want to provide different DPDK releases at the same time to\n+support multiple consumers of DPDK linked against older and newer sonames.\n+\n+Also due to the interdependencies that DPDK libraries can have applications\n+might end up with an executable space in which multiple versions of a library\n+are mapped by ld.so.\n+\n+Think of LibA that got an ABI bump and LibB that did not get an ABI bump but is\n+depending on LibA.\n+\n+.. note::\n+\n+ Application\n+ \\-> LibA.old\n+ \\-> LibB.new -> LibA.new\n+\n+That is a conflict which can be avoided by setting ``CONFIG_RTE_MAJOR_ABI``.\n+If set, the value of ``CONFIG_RTE_MAJOR_ABI`` overwrites all - otherwise per\n+library - versions defined in the libraries ``LIBABIVER``.\n+An example might be ``CONFIG_RTE_MAJOR_ABI=16.11`` which will make all libraries\n+``librte<?>.so.16.11`` instead of ``librte<?>.so.<LIBABIVER>``.\n+\n+\n+ABI versioning\n+--------------\n+\n+Versioning Macros\n+~~~~~~~~~~~~~~~~~\n+\n+When a symbol is exported from a library to provide an API, it also provides a\n+calling convention (ABI) that is embodied in its name, return type and\n+arguments. Occasionally that function may need to change to accommodate new\n+functionality or behavior. When that occurs, it is desirable to allow for\n+backward compatibility for a time with older binaries that are dynamically\n+linked to the DPDK.\n+\n+To support backward compatibility the ``rte_function_versioning.h``\n+header file provides macros to use when updating exported functions. These\n+macros are used in conjunction with the ``rte_<library>_version.map`` file for\n+a given library to allow multiple versions of a symbol to exist in a shared\n+library so that older binaries need not be immediately recompiled.\n+\n+The macros exported are:\n+\n+* ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry binding\n+ versioned symbol ``b@DPDK_n`` to the internal function ``be``.\n+\n+* ``BIND_DEFAULT_SYMBOL(b, e, n)``: Creates a symbol version entry instructing\n+ the linker to bind references to symbol ``b`` to the internal symbol\n+ ``be``.\n+\n+* ``MAP_STATIC_SYMBOL(f, p)``: Declare the prototype ``f``, and map it to the\n+ fully qualified function ``p``, so that if a symbol becomes versioned, it\n+ can still be mapped back to the public symbol name.\n+\n+* ``__vsym``: Annotation to be used in a declaration of the internal symbol\n+ ``be`` to signal that it is being used as an implementation of a particular\n+ version of symbol ``b``.\n+\n+Examples of ABI Macro use\n+^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+Updating a public API\n+_____________________\n+\n+Assume we have a function as follows\n+\n+.. code-block:: c\n+\n+ /*\n+ * Create an acl context object for apps to\n+ * manipulate\n+ */\n+ struct rte_acl_ctx *\n+ rte_acl_create(const struct rte_acl_param *param)\n+ {\n+ ...\n+ }\n+\n+\n+Assume that struct rte_acl_ctx is a private structure, and that a developer\n+wishes to enhance the acl api so that a debugging flag can be enabled on a\n+per-context basis. This requires an addition to the structure (which, being\n+private, is safe), but it also requires modifying the code as follows\n+\n+.. code-block:: c\n+\n+ /*\n+ * Create an acl context object for apps to\n+ * manipulate\n+ */\n+ struct rte_acl_ctx *\n+ rte_acl_create(const struct rte_acl_param *param, int debug)\n+ {\n+ ...\n+ }\n+\n+\n+Note also that, being a public function, the header file prototype must also be\n+changed, as must all the call sites, to reflect the new ABI footprint. We will\n+maintain previous ABI versions that are accessible only to previously compiled\n+binaries\n+\n+The addition of a parameter to the function is ABI breaking as the function is\n+public, and existing application may use it in its current form. However, the\n+compatibility macros in DPDK allow a developer to use symbol versioning so that\n+multiple functions can be mapped to the same public symbol based on when an\n+application was linked to it. To see how this is done, we start with the\n+requisite libraries version map file. Initially the version map file for the\n+acl library looks like this\n+\n+.. code-block:: none\n+\n+ DPDK_2.0 {\n+ global:\n+\n+ rte_acl_add_rules;\n+ rte_acl_build;\n+ rte_acl_classify;\n+ rte_acl_classify_alg;\n+ rte_acl_classify_scalar;\n+ rte_acl_create;\n+ rte_acl_dump;\n+ rte_acl_find_existing;\n+ rte_acl_free;\n+ rte_acl_ipv4vlan_add_rules;\n+ rte_acl_ipv4vlan_build;\n+ rte_acl_list_dump;\n+ rte_acl_reset;\n+ rte_acl_reset_rules;\n+ rte_acl_set_ctx_classify;\n+\n+ local: *;\n+ };\n+\n+This file needs to be modified as follows\n+\n+.. code-block:: none\n+\n+ DPDK_2.0 {\n+ global:\n+\n+ rte_acl_add_rules;\n+ rte_acl_build;\n+ rte_acl_classify;\n+ rte_acl_classify_alg;\n+ rte_acl_classify_scalar;\n+ rte_acl_create;\n+ rte_acl_dump;\n+ rte_acl_find_existing;\n+ rte_acl_free;\n+ rte_acl_ipv4vlan_add_rules;\n+ rte_acl_ipv4vlan_build;\n+ rte_acl_list_dump;\n+ rte_acl_reset;\n+ rte_acl_reset_rules;\n+ rte_acl_set_ctx_classify;\n+\n+ local: *;\n+ };\n+\n+ DPDK_2.1 {\n+ global:\n+ rte_acl_create;\n+\n+ } DPDK_2.0;\n+\n+The addition of the new block tells the linker that a new version node is\n+available (DPDK_2.1), which contains the symbol rte_acl_create, and inherits the\n+symbols from the DPDK_2.0 node. This list is directly translated into a list of\n+exported symbols when DPDK is compiled as a shared library\n+\n+Next, we need to specify in the code which function map to the rte_acl_create\n+symbol at which versions. First, at the site of the initial symbol definition,\n+we need to update the function so that it is uniquely named, and not in conflict\n+with the public symbol name\n+\n+.. code-block:: c\n+\n+ -struct rte_acl_ctx *\n+ -rte_acl_create(const struct rte_acl_param *param)\n+ +struct rte_acl_ctx * __vsym\n+ +rte_acl_create_v20(const struct rte_acl_param *param)\n+ {\n+ size_t sz;\n+ struct rte_acl_ctx *ctx;\n+ ...\n+\n+Note that the base name of the symbol was kept intact, as this is conducive to\n+the macros used for versioning symbols and we have annotated the function as an\n+implementation of versioned symbol. That is our next step, mapping this new\n+symbol name to the initial symbol name at version node 2.0. Immediately after\n+the function, we add this line of code\n+\n+.. code-block:: c\n+\n+ VERSION_SYMBOL(rte_acl_create, _v20, 2.0);\n+\n+Remembering to also add the rte_function_versioning.h header to the requisite c file where\n+these changes are being made. The above macro instructs the linker to create a\n+new symbol ``rte_acl_create@DPDK_2.0``, which matches the symbol created in older\n+builds, but now points to the above newly named function. We have now mapped\n+the original rte_acl_create symbol to the original function (but with a new\n+name)\n+\n+Next, we need to create the 2.1 version of the symbol. We create a new function\n+name, with a different suffix, and implement it appropriately\n+\n+.. code-block:: c\n+\n+ struct rte_acl_ctx * __vsym\n+ rte_acl_create_v21(const struct rte_acl_param *param, int debug);\n+ {\n+ struct rte_acl_ctx *ctx = rte_acl_create_v20(param);\n+\n+ ctx->debug = debug;\n+\n+ return ctx;\n+ }\n+\n+This code serves as our new API call. Its the same as our old call, but adds\n+the new parameter in place. Next we need to map this function to the symbol\n+``rte_acl_create@DPDK_2.1``. To do this, we modify the public prototype of the call\n+in the header file, adding the macro there to inform all including applications,\n+that on re-link, the default rte_acl_create symbol should point to this\n+function. Note that we could do this by simply naming the function above\n+rte_acl_create, and the linker would chose the most recent version tag to apply\n+in the version script, but we can also do this in the header file\n+\n+.. code-block:: c\n+\n+ struct rte_acl_ctx *\n+ -rte_acl_create(const struct rte_acl_param *param);\n+ +rte_acl_create(const struct rte_acl_param *param, int debug);\n+ +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1);\n+\n+The BIND_DEFAULT_SYMBOL macro explicitly tells applications that include this\n+header, to link to the rte_acl_create_v21 function and apply the DPDK_2.1\n+version node to it. This method is more explicit and flexible than just\n+re-implementing the exact symbol name, and allows for other features (such as\n+linking to the old symbol version by default, when the new ABI is to be opt-in\n+for a period.\n+\n+One last thing we need to do. Note that we've taken what was a public symbol,\n+and duplicated it into two uniquely and differently named symbols. We've then\n+mapped each of those back to the public symbol ``rte_acl_create`` with different\n+version tags. This only applies to dynamic linking, as static linking has no\n+notion of versioning. That leaves this code in a position of no longer having a\n+symbol simply named ``rte_acl_create`` and a static build will fail on that\n+missing symbol.\n+\n+To correct this, we can simply map a function of our choosing back to the public\n+symbol in the static build with the ``MAP_STATIC_SYMBOL`` macro. Generally the\n+assumption is that the most recent version of the symbol is the one you want to\n+map. So, back in the C file where, immediately after ``rte_acl_create_v21`` is\n+defined, we add this\n+\n+.. code-block:: c\n+\n+ struct rte_acl_ctx * __vsym\n+ rte_acl_create_v21(const struct rte_acl_param *param, int debug)\n+ {\n+ ...\n+ }\n+ MAP_STATIC_SYMBOL(struct rte_acl_ctx *rte_acl_create(const struct rte_acl_param *param, int debug), rte_acl_create_v21);\n+\n+That tells the compiler that, when building a static library, any calls to the\n+symbol ``rte_acl_create`` should be linked to ``rte_acl_create_v21``\n+\n+That's it, on the next shared library rebuild, there will be two versions of\n+rte_acl_create, an old DPDK_2.0 version, used by previously built applications,\n+and a new DPDK_2.1 version, used by future built applications.\n+\n+\n+Deprecating part of a public API\n+________________________________\n+\n+Lets assume that you've done the above update, and after a few releases have\n+passed you decide you would like to retire the old version of the function.\n+After having gone through the ABI deprecation announcement process, removal is\n+easy. Start by removing the symbol from the requisite version map file:\n+\n+.. code-block:: none\n+\n+ DPDK_2.0 {\n+ global:\n+\n+ rte_acl_add_rules;\n+ rte_acl_build;\n+ rte_acl_classify;\n+ rte_acl_classify_alg;\n+ rte_acl_classify_scalar;\n+ rte_acl_dump;\n+ - rte_acl_create\n+ rte_acl_find_existing;\n+ rte_acl_free;\n+ rte_acl_ipv4vlan_add_rules;\n+ rte_acl_ipv4vlan_build;\n+ rte_acl_list_dump;\n+ rte_acl_reset;\n+ rte_acl_reset_rules;\n+ rte_acl_set_ctx_classify;\n+\n+ local: *;\n+ };\n+\n+ DPDK_2.1 {\n+ global:\n+ rte_acl_create;\n+ } DPDK_2.0;\n+\n+\n+Next remove the corresponding versioned export.\n+\n+.. code-block:: c\n+\n+ -VERSION_SYMBOL(rte_acl_create, _v20, 2.0);\n+\n+\n+Note that the internal function definition could also be removed, but its used\n+in our example by the newer version _v21, so we leave it in place. This is a\n+coding style choice.\n+\n+Lastly, we need to bump the LIBABIVER number for this library in the Makefile to\n+indicate to applications doing dynamic linking that this is a later, and\n+possibly incompatible library version:\n+\n+.. code-block:: c\n+\n+ -LIBABIVER := 1\n+ +LIBABIVER := 2\n+\n+Deprecating an entire ABI version\n+_________________________________\n+\n+While removing a symbol from and ABI may be useful, it is often more practical\n+to remove an entire version node at once. If a version node completely\n+specifies an API, then removing part of it, typically makes it incomplete. In\n+those cases it is better to remove the entire node\n+\n+To do this, start by modifying the version map file, such that all symbols from\n+the node to be removed are merged into the next node in the map\n+\n+In the case of our map above, it would transform to look as follows\n+\n+.. code-block:: none\n+\n+ DPDK_2.1 {\n+ global:\n+\n+ rte_acl_add_rules;\n+ rte_acl_build;\n+ rte_acl_classify;\n+ rte_acl_classify_alg;\n+ rte_acl_classify_scalar;\n+ rte_acl_dump;\n+ rte_acl_create\n+ rte_acl_find_existing;\n+ rte_acl_free;\n+ rte_acl_ipv4vlan_add_rules;\n+ rte_acl_ipv4vlan_build;\n+ rte_acl_list_dump;\n+ rte_acl_reset;\n+ rte_acl_reset_rules;\n+ rte_acl_set_ctx_classify;\n+\n+ local: *;\n+ };\n+\n+Then any uses of BIND_DEFAULT_SYMBOL that pointed to the old node should be\n+updated to point to the new version node in any header files for all affected\n+symbols.\n+\n+.. code-block:: c\n+\n+ -BIND_DEFAULT_SYMBOL(rte_acl_create, _v20, 2.0);\n+ +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1);\n+\n+Lastly, any VERSION_SYMBOL macros that point to the old version node should be\n+removed, taking care to keep, where need old code in place to support newer\n+versions of the symbol.\n+\n+\n+Running the ABI Validator\n+-------------------------\n+\n+The ``devtools`` directory in the DPDK source tree contains a utility program,\n+``validate-abi.sh``, for validating the DPDK ABI based on the Linux `ABI\n+Compliance Checker\n+<http://ispras.linuxbase.org/index.php/ABI_compliance_checker>`_.\n+\n+This has a dependency on the ``abi-compliance-checker`` and ``and abi-dumper``\n+utilities which can be installed via a package manager. For example::\n+\n+ sudo yum install abi-compliance-checker\n+ sudo yum install abi-dumper\n+\n+The syntax of the ``validate-abi.sh`` utility is::\n+\n+ ./devtools/validate-abi.sh <REV1> <REV2>\n+\n+Where ``REV1`` and ``REV2`` are valid gitrevisions(7)\n+https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html\n+on the local repo.\n+\n+For example::\n+\n+ # Check between the previous and latest commit:\n+ ./devtools/validate-abi.sh HEAD~1 HEAD\n+\n+ # Check on a specific compilation target:\n+ ./devtools/validate-abi.sh -t x86_64-native-linux-gcc HEAD~1 HEAD\n+\n+ # Check between two tags:\n+ ./devtools/validate-abi.sh v2.0.0 v2.1.0\n+\n+ # Check between git master and local topic-branch \"vhost-hacking\":\n+ ./devtools/validate-abi.sh master vhost-hacking\n+\n+After the validation script completes (it can take a while since it need to\n+compile both tags) it will create compatibility reports in the\n+``./abi-check/compat_report`` directory. Listed incompatibilities can be found\n+as follows::\n+\n+ grep -lr Incompatible abi-check/compat_reports/\ndiff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst\nindex e2608d3..2fefd91 100644\n--- a/doc/guides/contributing/index.rst\n+++ b/doc/guides/contributing/index.rst\n@@ -10,7 +10,8 @@ Contributor's Guidelines\n \n coding_style\n design\n- versioning\n+ abi_policy\n+ abi_versioning\n documentation\n patches\n vulnerability\ndiff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst\nindex 9e1013b..c9ec529 100644\n--- a/doc/guides/contributing/patches.rst\n+++ b/doc/guides/contributing/patches.rst\n@@ -157,7 +157,7 @@ Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines\n * For other PMDs and more info, refer to the ``MAINTAINERS`` file.\n \n * New external functions should be added to the local ``version.map`` file.\n- See the :doc:`Guidelines for ABI policy and versioning </contributing/versioning>`.\n+ See the :doc:`Guidelines for ABI policy and versioning </contributing/abi_versioning>`.\n New external functions should also be added in alphabetical order.\n \n * Important changes will require an addition to the release notes in ``doc/guides/rel_notes/``.\ndiff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst\ndeleted file mode 100644\nindex fcd2d50..0000000\n--- a/doc/guides/contributing/versioning.rst\n+++ /dev/null\n@@ -1,597 +0,0 @@\n-.. SPDX-License-Identifier: BSD-3-Clause\n- Copyright 2018 The DPDK contributors\n-\n-DPDK ABI/API policy\n-===================\n-\n-Description\n------------\n-\n-This document details some methods for handling ABI management in the DPDK.\n-\n-General Guidelines\n-------------------\n-\n-#. Whenever possible, ABI should be preserved\n-#. ABI/API may be changed with a deprecation process\n-#. The modification of symbols can generally be managed with versioning\n-#. Libraries or APIs marked in ``experimental`` state may change without constraint\n-#. New APIs will be marked as ``experimental`` for at least one release to allow\n- any issues found by users of the new API to be fixed quickly\n-#. The addition of symbols is generally not problematic\n-#. The removal of symbols generally is an ABI break and requires bumping of the\n- LIBABIVER macro\n-#. Updates to the minimum hardware requirements, which drop support for hardware which\n- was previously supported, should be treated as an ABI change.\n-\n-What is an ABI\n-~~~~~~~~~~~~~~\n-\n-An ABI (Application Binary Interface) is the set of runtime interfaces exposed\n-by a library. It is similar to an API (Application Programming Interface) but\n-is the result of compilation. It is also effectively cloned when applications\n-link to dynamic libraries. That is to say when an application is compiled to\n-link against dynamic libraries, it is assumed that the ABI remains constant\n-between the time the application is compiled/linked, and the time that it runs.\n-Therefore, in the case of dynamic linking, it is critical that an ABI is\n-preserved, or (when modified), done in such a way that the application is unable\n-to behave improperly or in an unexpected fashion.\n-\n-\n-ABI/API Deprecation\n--------------------\n-\n-The DPDK ABI policy\n-~~~~~~~~~~~~~~~~~~~\n-\n-ABI versions are set at the time of major release labeling, and the ABI may\n-change multiple times, without warning, between the last release label and the\n-HEAD label of the git tree.\n-\n-ABI versions, once released, are available until such time as their\n-deprecation has been noted in the Release Notes for at least one major release\n-cycle. For example consider the case where the ABI for DPDK 2.0 has been\n-shipped and then a decision is made to modify it during the development of\n-DPDK 2.1. The decision will be recorded in the Release Notes for the DPDK 2.1\n-release and the modification will be made available in the DPDK 2.2 release.\n-\n-ABI versions may be deprecated in whole or in part as needed by a given\n-update.\n-\n-Some ABI changes may be too significant to reasonably maintain multiple\n-versions. In those cases ABI's may be updated without backward compatibility\n-being provided. The requirements for doing so are:\n-\n-#. At least 3 acknowledgments of the need to do so must be made on the\n- dpdk.org mailing list.\n-\n- - The acknowledgment of the maintainer of the component is mandatory, or if\n- no maintainer is available for the component, the tree/sub-tree maintainer\n- for that component must acknowledge the ABI change instead.\n-\n- - It is also recommended that acknowledgments from different \"areas of\n- interest\" be sought for each deprecation, for example: from NIC vendors,\n- CPU vendors, end-users, etc.\n-\n-#. The changes (including an alternative map file) can be included with\n- deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option,\n- to provide more details about oncoming changes.\n- ``RTE_NEXT_ABI`` wrapper will be removed when it become the default ABI.\n- More preferred way to provide this information is sending the feature\n- as a separate patch and reference it in deprecation notice.\n-\n-#. A full deprecation cycle, as explained above, must be made to offer\n- downstream consumers sufficient warning of the change.\n-\n-Note that the above process for ABI deprecation should not be undertaken\n-lightly. ABI stability is extremely important for downstream consumers of the\n-DPDK, especially when distributed in shared object form. Every effort should\n-be made to preserve the ABI whenever possible. The ABI should only be changed\n-for significant reasons, such as performance enhancements. ABI breakage due to\n-changes such as reorganizing public structure fields for aesthetic or\n-readability purposes should be avoided.\n-\n-.. note::\n-\n- Updates to the minimum hardware requirements, which drop support for hardware\n- which was previously supported, should be treated as an ABI change, and\n- follow the relevant deprecation policy procedures as above: 3 acks and\n- announcement at least one release in advance.\n-\n-Examples of Deprecation Notices\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-The following are some examples of ABI deprecation notices which would be\n-added to the Release Notes:\n-\n-* The Macro ``#RTE_FOO`` is deprecated and will be removed with version 2.0,\n- to be replaced with the inline function ``rte_foo()``.\n-\n-* The function ``rte_mbuf_grok()`` has been updated to include a new parameter\n- in version 2.0. Backwards compatibility will be maintained for this function\n- until the release of version 2.1\n-\n-* The members of ``struct rte_foo`` have been reorganized in release 2.0 for\n- performance reasons. Existing binary applications will have backwards\n- compatibility in release 2.0, while newly built binaries will need to\n- reference the new structure variant ``struct rte_foo2``. Compatibility will\n- be removed in release 2.2, and all applications will require updating and\n- rebuilding to the new structure at that time, which will be renamed to the\n- original ``struct rte_foo``.\n-\n-* Significant ABI changes are planned for the ``librte_dostuff`` library. The\n- upcoming release 2.0 will not contain these changes, but release 2.1 will,\n- and no backwards compatibility is planned due to the extensive nature of\n- these changes. Binaries using this library built prior to version 2.1 will\n- require updating and recompilation.\n-\n-New API replacing previous one\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-If a new API proposed functionally replaces an existing one, when the new API\n-becomes non-experimental then the old one is marked with ``__rte_deprecated``.\n-Deprecated APIs are removed completely just after the next LTS.\n-\n-Reminder that old API should follow deprecation process to be removed.\n-\n-\n-Experimental APIs\n------------------\n-\n-APIs marked as ``experimental`` are not considered part of the ABI and may\n-change without warning at any time. Since changes to APIs are most likely\n-immediately after their introduction, as users begin to take advantage of\n-those new APIs and start finding issues with them, new DPDK APIs will be\n-automatically marked as ``experimental`` to allow for a period of stabilization\n-before they become part of a tracked ABI.\n-\n-Note that marking an API as experimental is a multi step process.\n-To mark an API as experimental, the symbols which are desired to be exported\n-must be placed in an EXPERIMENTAL version block in the corresponding libraries'\n-version map script.\n-Secondly, the corresponding prototypes of those exported functions (in the\n-development header files), must be marked with the ``__rte_experimental`` tag\n-(see ``rte_compat.h``).\n-The DPDK build makefiles perform a check to ensure that the map file and the\n-C code reflect the same list of symbols.\n-This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``\n-during compilation in the corresponding library Makefile.\n-\n-In addition to tagging the code with ``__rte_experimental``,\n-the doxygen markup must also contain the EXPERIMENTAL string,\n-and the MAINTAINERS file should note the EXPERIMENTAL libraries.\n-\n-For removing the experimental tag associated with an API, deprecation notice\n-is not required. Though, an API should remain in experimental state for at least\n-one release. Thereafter, normal process of posting patch for review to mailing\n-list can be followed.\n-\n-\n-Library versioning\n-------------------\n-\n-Downstreams might want to provide different DPDK releases at the same time to\n-support multiple consumers of DPDK linked against older and newer sonames.\n-\n-Also due to the interdependencies that DPDK libraries can have applications\n-might end up with an executable space in which multiple versions of a library\n-are mapped by ld.so.\n-\n-Think of LibA that got an ABI bump and LibB that did not get an ABI bump but is\n-depending on LibA.\n-\n-.. note::\n-\n- Application\n- \\-> LibA.old\n- \\-> LibB.new -> LibA.new\n-\n-That is a conflict which can be avoided by setting ``CONFIG_RTE_MAJOR_ABI``.\n-If set, the value of ``CONFIG_RTE_MAJOR_ABI`` overwrites all - otherwise per\n-library - versions defined in the libraries ``LIBABIVER``.\n-An example might be ``CONFIG_RTE_MAJOR_ABI=16.11`` which will make all libraries\n-``librte<?>.so.16.11`` instead of ``librte<?>.so.<LIBABIVER>``.\n-\n-\n-ABI versioning\n---------------\n-\n-Versioning Macros\n-~~~~~~~~~~~~~~~~~\n-\n-When a symbol is exported from a library to provide an API, it also provides a\n-calling convention (ABI) that is embodied in its name, return type and\n-arguments. Occasionally that function may need to change to accommodate new\n-functionality or behavior. When that occurs, it is desirable to allow for\n-backward compatibility for a time with older binaries that are dynamically\n-linked to the DPDK.\n-\n-To support backward compatibility the ``rte_function_versioning.h``\n-header file provides macros to use when updating exported functions. These\n-macros are used in conjunction with the ``rte_<library>_version.map`` file for\n-a given library to allow multiple versions of a symbol to exist in a shared\n-library so that older binaries need not be immediately recompiled.\n-\n-The macros exported are:\n-\n-* ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry binding\n- versioned symbol ``b@DPDK_n`` to the internal function ``be``.\n-\n-* ``BIND_DEFAULT_SYMBOL(b, e, n)``: Creates a symbol version entry instructing\n- the linker to bind references to symbol ``b`` to the internal symbol\n- ``be``.\n-\n-* ``MAP_STATIC_SYMBOL(f, p)``: Declare the prototype ``f``, and map it to the\n- fully qualified function ``p``, so that if a symbol becomes versioned, it\n- can still be mapped back to the public symbol name.\n-\n-* ``__vsym``: Annotation to be used in a declaration of the internal symbol\n- ``be`` to signal that it is being used as an implementation of a particular\n- version of symbol ``b``.\n-\n-Examples of ABI Macro use\n-^^^^^^^^^^^^^^^^^^^^^^^^^\n-\n-Updating a public API\n-_____________________\n-\n-Assume we have a function as follows\n-\n-.. code-block:: c\n-\n- /*\n- * Create an acl context object for apps to\n- * manipulate\n- */\n- struct rte_acl_ctx *\n- rte_acl_create(const struct rte_acl_param *param)\n- {\n- ...\n- }\n-\n-\n-Assume that struct rte_acl_ctx is a private structure, and that a developer\n-wishes to enhance the acl api so that a debugging flag can be enabled on a\n-per-context basis. This requires an addition to the structure (which, being\n-private, is safe), but it also requires modifying the code as follows\n-\n-.. code-block:: c\n-\n- /*\n- * Create an acl context object for apps to\n- * manipulate\n- */\n- struct rte_acl_ctx *\n- rte_acl_create(const struct rte_acl_param *param, int debug)\n- {\n- ...\n- }\n-\n-\n-Note also that, being a public function, the header file prototype must also be\n-changed, as must all the call sites, to reflect the new ABI footprint. We will\n-maintain previous ABI versions that are accessible only to previously compiled\n-binaries\n-\n-The addition of a parameter to the function is ABI breaking as the function is\n-public, and existing application may use it in its current form. However, the\n-compatibility macros in DPDK allow a developer to use symbol versioning so that\n-multiple functions can be mapped to the same public symbol based on when an\n-application was linked to it. To see how this is done, we start with the\n-requisite libraries version map file. Initially the version map file for the\n-acl library looks like this\n-\n-.. code-block:: none\n-\n- DPDK_2.0 {\n- global:\n-\n- rte_acl_add_rules;\n- rte_acl_build;\n- rte_acl_classify;\n- rte_acl_classify_alg;\n- rte_acl_classify_scalar;\n- rte_acl_create;\n- rte_acl_dump;\n- rte_acl_find_existing;\n- rte_acl_free;\n- rte_acl_ipv4vlan_add_rules;\n- rte_acl_ipv4vlan_build;\n- rte_acl_list_dump;\n- rte_acl_reset;\n- rte_acl_reset_rules;\n- rte_acl_set_ctx_classify;\n-\n- local: *;\n- };\n-\n-This file needs to be modified as follows\n-\n-.. code-block:: none\n-\n- DPDK_2.0 {\n- global:\n-\n- rte_acl_add_rules;\n- rte_acl_build;\n- rte_acl_classify;\n- rte_acl_classify_alg;\n- rte_acl_classify_scalar;\n- rte_acl_create;\n- rte_acl_dump;\n- rte_acl_find_existing;\n- rte_acl_free;\n- rte_acl_ipv4vlan_add_rules;\n- rte_acl_ipv4vlan_build;\n- rte_acl_list_dump;\n- rte_acl_reset;\n- rte_acl_reset_rules;\n- rte_acl_set_ctx_classify;\n-\n- local: *;\n- };\n-\n- DPDK_2.1 {\n- global:\n- rte_acl_create;\n-\n- } DPDK_2.0;\n-\n-The addition of the new block tells the linker that a new version node is\n-available (DPDK_2.1), which contains the symbol rte_acl_create, and inherits the\n-symbols from the DPDK_2.0 node. This list is directly translated into a list of\n-exported symbols when DPDK is compiled as a shared library\n-\n-Next, we need to specify in the code which function map to the rte_acl_create\n-symbol at which versions. First, at the site of the initial symbol definition,\n-we need to update the function so that it is uniquely named, and not in conflict\n-with the public symbol name\n-\n-.. code-block:: c\n-\n- -struct rte_acl_ctx *\n- -rte_acl_create(const struct rte_acl_param *param)\n- +struct rte_acl_ctx * __vsym\n- +rte_acl_create_v20(const struct rte_acl_param *param)\n- {\n- size_t sz;\n- struct rte_acl_ctx *ctx;\n- ...\n-\n-Note that the base name of the symbol was kept intact, as this is conducive to\n-the macros used for versioning symbols and we have annotated the function as an\n-implementation of versioned symbol. That is our next step, mapping this new\n-symbol name to the initial symbol name at version node 2.0. Immediately after\n-the function, we add this line of code\n-\n-.. code-block:: c\n-\n- VERSION_SYMBOL(rte_acl_create, _v20, 2.0);\n-\n-Remembering to also add the rte_function_versioning.h header to the requisite c file where\n-these changes are being made. The above macro instructs the linker to create a\n-new symbol ``rte_acl_create@DPDK_2.0``, which matches the symbol created in older\n-builds, but now points to the above newly named function. We have now mapped\n-the original rte_acl_create symbol to the original function (but with a new\n-name)\n-\n-Next, we need to create the 2.1 version of the symbol. We create a new function\n-name, with a different suffix, and implement it appropriately\n-\n-.. code-block:: c\n-\n- struct rte_acl_ctx * __vsym\n- rte_acl_create_v21(const struct rte_acl_param *param, int debug);\n- {\n- struct rte_acl_ctx *ctx = rte_acl_create_v20(param);\n-\n- ctx->debug = debug;\n-\n- return ctx;\n- }\n-\n-This code serves as our new API call. Its the same as our old call, but adds\n-the new parameter in place. Next we need to map this function to the symbol\n-``rte_acl_create@DPDK_2.1``. To do this, we modify the public prototype of the call\n-in the header file, adding the macro there to inform all including applications,\n-that on re-link, the default rte_acl_create symbol should point to this\n-function. Note that we could do this by simply naming the function above\n-rte_acl_create, and the linker would chose the most recent version tag to apply\n-in the version script, but we can also do this in the header file\n-\n-.. code-block:: c\n-\n- struct rte_acl_ctx *\n- -rte_acl_create(const struct rte_acl_param *param);\n- +rte_acl_create(const struct rte_acl_param *param, int debug);\n- +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1);\n-\n-The BIND_DEFAULT_SYMBOL macro explicitly tells applications that include this\n-header, to link to the rte_acl_create_v21 function and apply the DPDK_2.1\n-version node to it. This method is more explicit and flexible than just\n-re-implementing the exact symbol name, and allows for other features (such as\n-linking to the old symbol version by default, when the new ABI is to be opt-in\n-for a period.\n-\n-One last thing we need to do. Note that we've taken what was a public symbol,\n-and duplicated it into two uniquely and differently named symbols. We've then\n-mapped each of those back to the public symbol ``rte_acl_create`` with different\n-version tags. This only applies to dynamic linking, as static linking has no\n-notion of versioning. That leaves this code in a position of no longer having a\n-symbol simply named ``rte_acl_create`` and a static build will fail on that\n-missing symbol.\n-\n-To correct this, we can simply map a function of our choosing back to the public\n-symbol in the static build with the ``MAP_STATIC_SYMBOL`` macro. Generally the\n-assumption is that the most recent version of the symbol is the one you want to\n-map. So, back in the C file where, immediately after ``rte_acl_create_v21`` is\n-defined, we add this\n-\n-.. code-block:: c\n-\n- struct rte_acl_ctx * __vsym\n- rte_acl_create_v21(const struct rte_acl_param *param, int debug)\n- {\n- ...\n- }\n- MAP_STATIC_SYMBOL(struct rte_acl_ctx *rte_acl_create(const struct rte_acl_param *param, int debug), rte_acl_create_v21);\n-\n-That tells the compiler that, when building a static library, any calls to the\n-symbol ``rte_acl_create`` should be linked to ``rte_acl_create_v21``\n-\n-That's it, on the next shared library rebuild, there will be two versions of\n-rte_acl_create, an old DPDK_2.0 version, used by previously built applications,\n-and a new DPDK_2.1 version, used by future built applications.\n-\n-\n-Deprecating part of a public API\n-________________________________\n-\n-Lets assume that you've done the above update, and after a few releases have\n-passed you decide you would like to retire the old version of the function.\n-After having gone through the ABI deprecation announcement process, removal is\n-easy. Start by removing the symbol from the requisite version map file:\n-\n-.. code-block:: none\n-\n- DPDK_2.0 {\n- global:\n-\n- rte_acl_add_rules;\n- rte_acl_build;\n- rte_acl_classify;\n- rte_acl_classify_alg;\n- rte_acl_classify_scalar;\n- rte_acl_dump;\n- - rte_acl_create\n- rte_acl_find_existing;\n- rte_acl_free;\n- rte_acl_ipv4vlan_add_rules;\n- rte_acl_ipv4vlan_build;\n- rte_acl_list_dump;\n- rte_acl_reset;\n- rte_acl_reset_rules;\n- rte_acl_set_ctx_classify;\n-\n- local: *;\n- };\n-\n- DPDK_2.1 {\n- global:\n- rte_acl_create;\n- } DPDK_2.0;\n-\n-\n-Next remove the corresponding versioned export.\n-\n-.. code-block:: c\n-\n- -VERSION_SYMBOL(rte_acl_create, _v20, 2.0);\n-\n-\n-Note that the internal function definition could also be removed, but its used\n-in our example by the newer version _v21, so we leave it in place. This is a\n-coding style choice.\n-\n-Lastly, we need to bump the LIBABIVER number for this library in the Makefile to\n-indicate to applications doing dynamic linking that this is a later, and\n-possibly incompatible library version:\n-\n-.. code-block:: c\n-\n- -LIBABIVER := 1\n- +LIBABIVER := 2\n-\n-Deprecating an entire ABI version\n-_________________________________\n-\n-While removing a symbol from and ABI may be useful, it is often more practical\n-to remove an entire version node at once. If a version node completely\n-specifies an API, then removing part of it, typically makes it incomplete. In\n-those cases it is better to remove the entire node\n-\n-To do this, start by modifying the version map file, such that all symbols from\n-the node to be removed are merged into the next node in the map\n-\n-In the case of our map above, it would transform to look as follows\n-\n-.. code-block:: none\n-\n- DPDK_2.1 {\n- global:\n-\n- rte_acl_add_rules;\n- rte_acl_build;\n- rte_acl_classify;\n- rte_acl_classify_alg;\n- rte_acl_classify_scalar;\n- rte_acl_dump;\n- rte_acl_create\n- rte_acl_find_existing;\n- rte_acl_free;\n- rte_acl_ipv4vlan_add_rules;\n- rte_acl_ipv4vlan_build;\n- rte_acl_list_dump;\n- rte_acl_reset;\n- rte_acl_reset_rules;\n- rte_acl_set_ctx_classify;\n-\n- local: *;\n- };\n-\n-Then any uses of BIND_DEFAULT_SYMBOL that pointed to the old node should be\n-updated to point to the new version node in any header files for all affected\n-symbols.\n-\n-.. code-block:: c\n-\n- -BIND_DEFAULT_SYMBOL(rte_acl_create, _v20, 2.0);\n- +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1);\n-\n-Lastly, any VERSION_SYMBOL macros that point to the old version node should be\n-removed, taking care to keep, where need old code in place to support newer\n-versions of the symbol.\n-\n-\n-Running the ABI Validator\n--------------------------\n-\n-The ``devtools`` directory in the DPDK source tree contains a utility program,\n-``validate-abi.sh``, for validating the DPDK ABI based on the Linux `ABI\n-Compliance Checker\n-<http://ispras.linuxbase.org/index.php/ABI_compliance_checker>`_.\n-\n-This has a dependency on the ``abi-compliance-checker`` and ``and abi-dumper``\n-utilities which can be installed via a package manager. For example::\n-\n- sudo yum install abi-compliance-checker\n- sudo yum install abi-dumper\n-\n-The syntax of the ``validate-abi.sh`` utility is::\n-\n- ./devtools/validate-abi.sh <REV1> <REV2>\n-\n-Where ``REV1`` and ``REV2`` are valid gitrevisions(7)\n-https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html\n-on the local repo.\n-\n-For example::\n-\n- # Check between the previous and latest commit:\n- ./devtools/validate-abi.sh HEAD~1 HEAD\n-\n- # Check on a specific compilation target:\n- ./devtools/validate-abi.sh -t x86_64-native-linux-gcc HEAD~1 HEAD\n-\n- # Check between two tags:\n- ./devtools/validate-abi.sh v2.0.0 v2.1.0\n-\n- # Check between git master and local topic-branch \"vhost-hacking\":\n- ./devtools/validate-abi.sh master vhost-hacking\n-\n-After the validation script completes (it can take a while since it need to\n-compile both tags) it will create compatibility reports in the\n-``./abi-check/compat_report`` directory. Listed incompatibilities can be found\n-as follows::\n-\n- grep -lr Incompatible abi-check/compat_reports/\ndiff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst\nindex fad208b..3de702a 100644\n--- a/doc/guides/rel_notes/deprecation.rst\n+++ b/doc/guides/rel_notes/deprecation.rst\n@@ -4,7 +4,7 @@\n ABI and API Deprecation\n =======================\n \n-See the :doc:`guidelines document for details of the ABI policy </contributing/versioning>`.\n+See the :doc:`guidelines document for details of the ABI policy </contributing/abi_versioning>`.\n API and ABI deprecation notices are to be posted here.\n \n \n", "prefixes": [ "v11", "1/3" ] }