X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fversioning.rst;h=fcd2d50f180d3fd3a0104f874f3919c35582af27;hb=9a2f44c762070295645575c274dce7f94961933f;hp=74c73c2320a40e76a101ff3bf92e89be2f07d28d;hpb=e17e6d31ca66d977a6a212b1c612c9b8f2cc166b;p=dpdk.git diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst index 74c73c2320..fcd2d50f18 100644 --- a/doc/guides/contributing/versioning.rst +++ b/doc/guides/contributing/versioning.rst @@ -125,6 +125,15 @@ added to the Release Notes: these changes. Binaries using this library built prior to version 2.1 will require updating and recompilation. +New API replacing previous one +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a new API proposed functionally replaces an existing one, when the new API +becomes non-experimental then the old one is marked with ``__rte_deprecated``. +Deprecated APIs are removed completely just after the next LTS. + +Reminder that old API should follow deprecation process to be removed. + Experimental APIs ----------------- @@ -140,9 +149,9 @@ Note that marking an API as experimental is a multi step process. To mark an API as experimental, the symbols which are desired to be exported must be placed in an EXPERIMENTAL version block in the corresponding libraries' version map script. -Secondly, the corresponding definitions of those exported functions, and -their forward declarations (in the development header files), must be marked -with the ``__rte_experimental`` tag (see ``rte_compat.h``). +Secondly, the corresponding prototypes of those exported functions (in the +development header files), must be marked with the ``__rte_experimental`` tag +(see ``rte_compat.h``). The DPDK build makefiles perform a check to ensure that the map file and the C code reflect the same list of symbols. This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API`` @@ -197,7 +206,7 @@ functionality or behavior. When that occurs, it is desirable to allow for backward compatibility for a time with older binaries that are dynamically linked to the DPDK. -To support backward compatibility the ``rte_compat.h`` +To support backward compatibility the ``rte_function_versioning.h`` header file provides macros to use when updating exported functions. These macros are used in conjunction with the ``rte__version.map`` file for a given library to allow multiple versions of a symbol to exist in a shared @@ -206,16 +215,20 @@ library so that older binaries need not be immediately recompiled. The macros exported are: * ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry binding - versioned symbol ``b@DPDK_n`` to the internal function ``b_e``. + versioned symbol ``b@DPDK_n`` to the internal function ``be``. * ``BIND_DEFAULT_SYMBOL(b, e, n)``: Creates a symbol version entry instructing the linker to bind references to symbol ``b`` to the internal symbol - ``b_e``. + ``be``. * ``MAP_STATIC_SYMBOL(f, p)``: Declare the prototype ``f``, and map it to the fully qualified function ``p``, so that if a symbol becomes versioned, it can still be mapped back to the public symbol name. +* ``__vsym``: Annotation to be used in a declaration of the internal symbol + ``be`` to signal that it is being used as an implementation of a particular + version of symbol ``b``. + Examples of ABI Macro use ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -336,8 +349,9 @@ with the public symbol name .. code-block:: c - struct rte_acl_ctx * + -struct rte_acl_ctx * -rte_acl_create(const struct rte_acl_param *param) + +struct rte_acl_ctx * __vsym +rte_acl_create_v20(const struct rte_acl_param *param) { size_t sz; @@ -345,7 +359,8 @@ with the public symbol name ... Note that the base name of the symbol was kept intact, as this is conducive to -the macros used for versioning symbols. That is our next step, mapping this new +the macros used for versioning symbols and we have annotated the function as an +implementation of versioned symbol. That is our next step, mapping this new symbol name to the initial symbol name at version node 2.0. Immediately after the function, we add this line of code @@ -353,7 +368,7 @@ the function, we add this line of code VERSION_SYMBOL(rte_acl_create, _v20, 2.0); -Remembering to also add the rte_compat.h header to the requisite c file where +Remembering to also add the rte_function_versioning.h header to the requisite c file where these changes are being made. The above macro instructs the linker to create a new symbol ``rte_acl_create@DPDK_2.0``, which matches the symbol created in older builds, but now points to the above newly named function. We have now mapped @@ -365,7 +380,7 @@ name, with a different suffix, and implement it appropriately .. code-block:: c - struct rte_acl_ctx * + struct rte_acl_ctx * __vsym rte_acl_create_v21(const struct rte_acl_param *param, int debug); { struct rte_acl_ctx *ctx = rte_acl_create_v20(param); @@ -414,7 +429,7 @@ defined, we add this .. code-block:: c - struct rte_acl_ctx * + struct rte_acl_ctx * __vsym rte_acl_create_v21(const struct rte_acl_param *param, int debug) { ... @@ -554,26 +569,29 @@ utilities which can be installed via a package manager. For example:: The syntax of the ``validate-abi.sh`` utility is:: - ./devtools/validate-abi.sh + ./devtools/validate-abi.sh Where ``REV1`` and ``REV2`` are valid gitrevisions(7) https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html -on the local repo and target is the usual DPDK compilation target. +on the local repo. For example:: # Check between the previous and latest commit: - ./devtools/validate-abi.sh HEAD~1 HEAD x86_64-native-linux-gcc + ./devtools/validate-abi.sh HEAD~1 HEAD + + # Check on a specific compilation target: + ./devtools/validate-abi.sh -t x86_64-native-linux-gcc HEAD~1 HEAD # Check between two tags: - ./devtools/validate-abi.sh v2.0.0 v2.1.0 x86_64-native-linux-gcc + ./devtools/validate-abi.sh v2.0.0 v2.1.0 # Check between git master and local topic-branch "vhost-hacking": - ./devtools/validate-abi.sh master vhost-hacking x86_64-native-linux-gcc + ./devtools/validate-abi.sh master vhost-hacking After the validation script completes (it can take a while since it need to compile both tags) it will create compatibility reports in the -``./compat_report`` directory. Listed incompatibilities can be found as -follows:: +``./abi-check/compat_report`` directory. Listed incompatibilities can be found +as follows:: - grep -lr Incompatible compat_reports/ + grep -lr Incompatible abi-check/compat_reports/