[dpdk-dev] [PATCH v6 1/4] doc: separate versioning.rst into version and policy
Ray Kinsella
mdr at ashroe.eu
Tue Oct 1 15:19:09 CEST 2019
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
More information about the dev
mailing list