Hemant, Patch 1/4 - doc: separate versioning.rst into version and policy.
So it essentially re-organizes the existing policy into two separate documents, one dealing with the policy and the other dealing with the mechanics of abi versioning Patch 2/4 - doc: changes to abi policy introducing major abi versions Actually details the changes to the policy. Other comments inline below. Ray K On 01/10/2019 13:50, Hemant Agrawal wrote: > Hi Ray, > >> +DPDK ABI/API policy >> +=================== >> + >> +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? > 1. Why dropping HW PMD is a ABI change? So this is part of the original policy and you are correct, it isn't strictly abi - I think the original policy's author, wanted it treated the same way so that a given ABI version would not drop support for hardware. > 2. Even if they are supported across releases, there is no guarantee that > they are not broken. True > >> + >> +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 application >> 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 available >> 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? Already done, see Patch 2/4 >> +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 of >> + 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? Detailed in Patch 2/4. it says ... At the declaration of the next major ABI version, those ABI changes then become a formal part of the new ABI and the requirement to preserve ABI compatibility with the last major ABI version is then dropped ... Thanks, Ray K
