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? 2. Even if they are supported across releases, there is no guarantee that they 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 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? > +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?
