Experimental/internal libraries cleanup
Subsystems (4)
cover Experimental/internal libraries cleanup
Following discussions on the mailing list and the last TB meeting, here is a series that drops the special versioning for non stable libraries.
Two notes:
- RIB/FIB library is not referenced in the API doxygen index, is this intentional?
- I inspected MAINTAINERS: librte_gro, librte_member and librte_rawdev are announced as experimental while their functions are part of the 20 stable ABI (in .map files + no __rte_experimental marking). I won't touch this for 20.05 but their fate will have to be discussed.
Signature · 39 lines
David Marchand David Marchand (3): build: remove special versioning for non stable libraries drivers: drop workaround for internal libraries lib: remind experimental status in library headers buildtools/meson.build | 3 --- config/meson.build | 16 +++++------- devtools/check-abi.sh | 5 ---- devtools/libabigail.abignore | 26 +++++++++++++++++-- drivers/bus/dpaa/rte_bus_dpaa_version.map | 6 ++--- drivers/bus/fslmc/rte_bus_fslmc_version.map | 6 ++--- .../common/dpaax/rte_common_dpaax_version.map | 6 ++--- .../rte_common_octeontx2_version.map | 6 ++--- .../dpaa2_sec/rte_pmd_dpaa2_sec_version.map | 6 ++--- .../dpaa_sec/rte_pmd_dpaa_sec_version.map | 6 ++--- .../mempool/dpaa/rte_mempool_dpaa_version.map | 6 ++--- .../rte_mempool_octeontx2_version.map | 6 ++--- drivers/meson.build | 13 +--------- drivers/net/dpaa2/rte_pmd_dpaa2_version.map | 6 ++--- lib/librte_bbdev/rte_bbdev.h | 3 ++- lib/librte_bpf/rte_bpf.h | 6 ++++- lib/librte_compressdev/rte_compressdev.h | 6 ++++- lib/librte_fib/rte_fib.h | 7 +++++ lib/librte_fib/rte_fib6.h | 7 +++++ lib/librte_flow_classify/rte_flow_classify.h | 6 +++-- lib/librte_ipsec/rte_ipsec.h | 6 ++++- lib/librte_rcu/rte_rcu_qsbr.h | 7 ++++- lib/librte_rib/rte_rib.h | 7 +++++ lib/librte_rib/rte_rib6.h | 7 +++++ lib/librte_stack/rte_stack.h | 7 +++-- lib/librte_telemetry/rte_telemetry.h | 10 ++++--- lib/meson.build | 13 +--------- mk/rte.lib.mk | 5 ---- 28 files changed, 116 insertions(+), 98 deletions(-) -- 2.23.0
PATCH 1/3 build: remove special versioning for non stable libraries
Having a special versioning for experimental/internal libraries put a additional maintenance cost while this status is already announced in MAINTAINERS and the library headers/documentation. Following discussions and vote at 05/20 TB meeting [1], use a single versioning for all libraries in DPDK.
Note: for the ABI check, an exception [2] had been added when tweaking this special versioning [3].
Prefer explicit libabigail rules (which will be dropped in 20.11).
1: https://mails.dpdk.org/archives/dev/2020-May/168450.html
2: https://git.dpdk.org/dpdk/commit/?id=23d7ad5db41c
3: https://git.dpdk.org/dpdk/commit/?id=ec2b8cd7ed69
--- buildtools/meson.build | 3 --- config/meson.build | 16 ++++++---------- devtools/check-abi.sh | 5 ----- devtools/libabigail.abignore | 26 ++++++++++++++++++++++++-- drivers/meson.build | 13 +------------ lib/meson.build | 13 +------------ mk/rte.lib.mk | 5 ----- 7 files changed, 32 insertions(+), 49 deletions(-)
buildtools/meson.build +0 -3
@@ -18,6 +18,3 @@ else endif map_to_def_cmd = py3 + files('map_to_def.py') sphinx_wrapper = py3 + files('call-sphinx-build.py') - -# stable ABI always starts with "DPDK_" -is_stable_cmd = [find_program('grep', 'findstr'), '^DPDK_']
config/meson.build +6 -10
@@ -25,18 +25,14 @@ major_version = '@0@.@1@'.format(pver.get(0), pver.get(1)) abi_version = run_command(find_program('cat', 'more'), abi_version_file).stdout().strip() -# Regular libraries have the abi_version as the filename extension +# Libraries have the abi_version as the filename extension # and have the soname be all but the final part of the abi_version. -# Experimental libraries have soname with '0.major' -# and the filename suffix as 0.majorminor versions, -# e.g. v20.1 => librte_stable.so.20.1, librte_experimental.so.0.201 -# sonames => librte_stable.so.20, librte_experimental.so.0.20 -# e.g. v20.0.1 => librte_stable.so.20.0.1, librte_experimental.so.0.2001 -# sonames => librte_stable.so.20.0, librte_experimental.so.0.200 +# e.g. v20.1 => librte_foo.so.20.1 +# sonames => librte_foo.so.20 +# e.g. v20.0.1 => librte_foo.so.20.0.1 +# sonames => librte_foo.so.20.0 abi_va = abi_version.split('.') -stable_so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1] -experimental_abi_version = '0.' + abi_va[0] + abi_va[1] + '.' + abi_va[2] -experimental_so_version = experimental_abi_version +so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1] # extract all version information into the build configuration dpdk_conf.set('RTE_VER_YEAR', pver.get(0).to_int())
devtools/check-abi.sh +0 -5
@@ -44,11 +44,6 @@ for dump in $(find $refdir -name "*.dump"); do echo "Skipped glue library $name." continue fi - # skip experimental libraries, with a sover starting with 0. - if grep -qE "\<soname='[^']*\.so\.0\.[^']*'" $dump; then - echo "Skipped experimental library $name." - continue - fi dump2=$(find $newdir -name $name) if [ -z "$dump2" ] || [ ! -e "$dump2" ]; then echo "Error: can't find $name in $newdir"
devtools/libabigail.abignore +24 -2
@@ -50,9 +50,10 @@ name = rte_crypto_aead_algorithm_strings ;;;;;;;;;;;;;;;;;;;;;; -; Temporary exceptions for new __rte_internal marking till DPDK 20.11 +; Temporary exceptions for new __rte_internal marking and experimental +; libraries soname changes till DPDK 20.11 ;;;;;;;;;;;;;;;;;;;;;; -; Ignore moving OCTEONTX2 stable functions to INTERNAL tag +; Ignore moving OCTEONTX2 stable functions to INTERNAL [suppress_file] file_name_regexp = ^librte_common_octeontx2\. [suppress_file]
@@ -77,3 +78,24 @@ name = rte_dpaa2_mbuf_alloc_bulk [suppress_function] name_regexp = ^dpaa2?_.*tach$ +; Ignore soname changes for experimental libraries +[suppress_file] + file_name_regexp = ^librte_bbdev\. +[suppress_file] + file_name_regexp = ^librte_bpf\. +[suppress_file] + file_name_regexp = ^librte_compressdev\. +[suppress_file] + file_name_regexp = ^librte_fib\. +[suppress_file] + file_name_regexp = ^librte_flow_classify\. +[suppress_file] + file_name_regexp = ^librte_ipsec\. +[suppress_file] + file_name_regexp = ^librte_rcu\. +[suppress_file] + file_name_regexp = ^librte_rib\. +[suppress_file] + file_name_regexp = ^librte_telemetry\. +[suppress_file] + file_name_regexp = ^librte_stack\.
drivers/meson.build +1 -12
@@ -128,17 +128,6 @@ foreach class:dpdk_driver_classes meson.current_source_dir(), drv_path, lib_name) - is_stable = run_command(is_stable_cmd, - files(version_map)).returncode() == 0 - - if is_stable - lib_version = abi_version - so_version = stable_so_version - else - lib_version = experimental_abi_version - so_version = experimental_so_version - endif - # now build the static driver static_lib = static_library(lib_name, sources,
@@ -183,7 +172,7 @@ foreach class:dpdk_driver_classes c_args: cflags, link_args: lk_args, link_depends: lk_deps, - version: lib_version, + version: abi_version, soversion: so_version, install: true, install_dir: driver_install_path)
lib/meson.build +1 -12
@@ -110,17 +110,6 @@ foreach l:libraries version_map = '@0@/@1@/rte_@2@_version.map'.format( meson.current_source_dir(), dir_name, name) - is_stable = run_command(is_stable_cmd, - files(version_map)).returncode() == 0 - - if is_stable - lib_version = abi_version - so_version = stable_so_version - else - lib_version = experimental_abi_version - so_version = experimental_so_version - endif - # first build static lib static_lib = static_library(libname, sources,
@@ -179,7 +168,7 @@ foreach l:libraries include_directories: includes, link_args: lk_args, link_depends: lk_deps, - version: lib_version, + version: abi_version, soversion: so_version, install: true) shared_dep = declare_dependency(link_with: shared_lib,
mk/rte.lib.mk +0 -5
@@ -13,11 +13,6 @@ VPATH += $(SRCDIR) LIBABIVER ?= $(shell cat $(RTE_SRCDIR)/ABI_VERSION) SOVER := $(basename $(LIBABIVER)) -ifeq ($(shell grep -s "^DPDK_" $(SRCDIR)/$(EXPORT_MAP)),) -# EXPERIMENTAL ABI is versioned as 0.major+minor, e.g. 0.201 for 20.1 ABI -LIBABIVER := 0.$(shell echo $(LIBABIVER) | awk 'BEGIN { FS="." }; { print $$1$$2"."$$3 }') -SOVER := $(LIBABIVER) -endif ifeq ($(CONFIG_RTE_BUILD_SHARED_LIB),y) SONAME := $(patsubst %.a,%.so.$(SOVER),$(LIB))
Signature · 1 line
2.23.0
PATCH 2/3 drivers: drop workaround for internal libraries
In reply to David MarchandNow that all libraries have a single version, we can drop the empty stable blocks that had been added when moving symbols from stable to internal ABI.
--- drivers/bus/dpaa/rte_bus_dpaa_version.map | 6 ++---- drivers/bus/fslmc/rte_bus_fslmc_version.map | 6 ++---- drivers/common/dpaax/rte_common_dpaax_version.map | 6 ++---- drivers/common/octeontx2/rte_common_octeontx2_version.map | 6 ++---- drivers/crypto/dpaa2_sec/rte_pmd_dpaa2_sec_version.map | 6 ++---- drivers/crypto/dpaa_sec/rte_pmd_dpaa_sec_version.map | 6 ++---- drivers/mempool/dpaa/rte_mempool_dpaa_version.map | 6 ++---- drivers/mempool/octeontx2/rte_mempool_octeontx2_version.map | 6 ++---- drivers/net/dpaa2/rte_pmd_dpaa2_version.map | 6 ++---- 9 files changed, 18 insertions(+), 36 deletions(-)
drivers/bus/dpaa/rte_bus_dpaa_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -90,4 +86,6 @@ INTERNAL { rte_dpaa_portal_fq_close; rte_dpaa_portal_fq_init; rte_dpaa_portal_init; + + local: *; };
drivers/bus/fslmc/rte_bus_fslmc_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - EXPERIMENTAL { global:
@@ -111,4 +107,6 @@ INTERNAL { rte_fslmc_get_device_count; rte_fslmc_object_register; rte_global_active_dqs_list; + + local: *; };
drivers/common/dpaax/rte_common_dpaax_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -23,4 +19,6 @@ INTERNAL { of_n_addr_cells; of_translate_address; rta_sec_era; + + local: *; };
drivers/common/octeontx2/rte_common_octeontx2_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -42,4 +38,6 @@ INTERNAL { otx2_sso_pf_func_get; otx2_sso_pf_func_set; otx2_unregister_irq; + + local: *; };
drivers/crypto/dpaa2_sec/rte_pmd_dpaa2_sec_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: dpaa2_sec_eventq_attach; dpaa2_sec_eventq_detach; + + local: *; };
drivers/crypto/dpaa_sec/rte_pmd_dpaa_sec_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: dpaa_sec_eventq_attach; dpaa_sec_eventq_detach; + + local: *; };
drivers/mempool/dpaa/rte_mempool_dpaa_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: rte_dpaa_bpid_info; rte_dpaa_memsegs; + + local: *; };
drivers/mempool/octeontx2/rte_mempool_octeontx2_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: otx2_npa_lf_fini; otx2_npa_lf_init; + + local: *; };
drivers/net/dpaa2/rte_pmd_dpaa2_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - EXPERIMENTAL { global:
@@ -15,4 +11,6 @@ INTERNAL { dpaa2_eth_eventq_attach; dpaa2_eth_eventq_detach; + + local: *; };
Signature · 1 line
2.23.0
PATCH 3/3 lib: remind experimental status in library headers
In reply to David MarchandThe following libraries are experimental, all of their functions can change or disappear:
- librte_bbdev
- librte_bpf
- librte_compressdev
- librte_fib
- librte_flow_classify
- librte_ipsec
- librte_rcu
- librte_rib
- librte_stack
- librte_telemetry
Their status is properly announced in MAINTAINERS. Remind this status in their headers in a common fashion.
--- lib/librte_bbdev/rte_bbdev.h | 3 ++- lib/librte_bpf/rte_bpf.h | 6 +++++- lib/librte_compressdev/rte_compressdev.h | 6 +++++- lib/librte_fib/rte_fib.h | 7 +++++++ lib/librte_fib/rte_fib6.h | 7 +++++++ lib/librte_flow_classify/rte_flow_classify.h | 6 ++++-- lib/librte_ipsec/rte_ipsec.h | 6 +++++- lib/librte_rcu/rte_rcu_qsbr.h | 7 ++++++- lib/librte_rib/rte_rib.h | 7 +++++++ lib/librte_rib/rte_rib6.h | 7 +++++++ lib/librte_stack/rte_stack.h | 7 +++++-- lib/librte_telemetry/rte_telemetry.h | 10 ++++++---- 12 files changed, 66 insertions(+), 13 deletions(-)
lib/librte_bbdev/rte_bbdev.h +2 -1
@@ -11,7 +11,8 @@* Wireless base band device abstraction APIs. * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * This API allows an application to discover, configure and use a device to * process operations. An asynchronous API (enqueue, followed by later dequeue)
lib/librte_bpf/rte_bpf.h +5 -1
@@ -7,9 +7,13 @@/** * @file rte_bpf.h -* @b EXPERIMENTAL: this API may change without prior notice * * RTE BPF support. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * librte_bpf provides a framework to load and execute eBPF bytecode * inside user-space dpdk based applications. * It supports basic set of features from eBPF spec
lib/librte_compressdev/rte_compressdev.h +5 -1
@@ -8,7 +8,11 @@/** * @file rte_compressdev.h * -* RTE Compression Device APIs +* RTE Compression Device APIs. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * Defines comp device APIs for the provisioning of compression operations. */
lib/librte_fib/rte_fib.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE FIB library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * FIB (Forwarding information base) implementation * for IPv4 Longest Prefix Match */
lib/librte_fib/rte_fib6.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE FIB6 library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * FIB (Forwarding information base) implementation * for IPv6 Longest Prefix Match */
lib/librte_flow_classify/rte_flow_classify.h +4 -2
@@ -8,9 +8,11 @@/** * @file * -* RTE Flow Classify Library +* RTE Flow Classify Library. * -* @b EXPERIMENTAL: this API may change without prior notice +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * This library provides flow record information with some measured properties. *
lib/librte_ipsec/rte_ipsec.h +5 -1
@@ -7,9 +7,13 @@/** * @file rte_ipsec.h -* @b EXPERIMENTAL: this API may change without prior notice * * RTE IPsec support. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * librte_ipsec provides a framework for data-path IPsec protocol * processing (ESP/AH). */
lib/librte_rcu/rte_rcu_qsbr.h +6 -1
@@ -7,7 +7,12 @@/** * @file -* RTE Quiescent State Based Reclamation (QSBR) +* +* RTE Quiescent State Based Reclamation (QSBR). +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * Quiescent State (QS) is any point in the thread execution * where the thread does not hold a reference to a data structure
lib/librte_rib/rte_rib.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE RIB library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * Level compressed tree implementation for IPv4 Longest Prefix Match */
lib/librte_rib/rte_rib6.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE rib6 library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * Level compressed tree implementation for IPv6 Longest Prefix Match */
lib/librte_stack/rte_stack.h +5 -2
@@ -4,9 +4,12 @@/** * @file rte_stack.h -* @b EXPERIMENTAL: this API may change without prior notice * -* RTE Stack +* RTE Stack. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * librte_stack provides an API for configuration and use of a bounded stack of * pointers. Push and pop operations are MT-safe, allowing concurrent access,
lib/librte_telemetry/rte_telemetry.h +6 -4
@@ -20,11 +20,13 @@#define RTE_TEL_MAX_ARRAY_ENTRIES 512/** -* @warning -* @b EXPERIMENTAL: all functions in this file may change without prior notice -* * @file -* RTE Telemetry +* +* RTE Telemetry. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * The telemetry library provides a method to retrieve statistics from * DPDK by sending a request message over a socket. DPDK will send
Signature · 1 line
2.23.0
Re: [dpdk-dev] [PATCH 3/3] lib: remind experimental status in library headers
<snip>
Quoted 42 lines
Subject: [PATCH 3/3] lib: remind experimental status in library headers
The following libraries are experimental, all of their functions can change or disappear:
-
librte_bbdev
-librte_bpf
-librte_compressdev
-librte_fib
-librte_flow_classify
-librte_ipsec
-librte_rcu
-librte_rib
-librte_stack
-librte_telemetryTheir status is properly announced in
MAINTAINERS. Remind this status in their headers in a common fashion.Signed-off-by David Marchand <[email protected]>--- lib/librte_bbdev/rte_bbdev.h | 3 ++- lib/librte_bpf/rte_bpf.h | 6 +++++- lib/librte_compressdev/rte_compressdev.h | 6 +++++- lib/librte_fib/rte_fib.h | 7 +++++++ lib/librte_fib/rte_fib6.h | 7 +++++++ lib/librte_flow_classify/rte_flow_classify.h | 6 ++++-- lib/librte_ipsec/rte_ipsec.h | 6 +++++- lib/librte_rcu/rte_rcu_qsbr.h | 7 ++++++- lib/librte_rib/rte_rib.h | 7 +++++++ lib/librte_rib/rte_rib6.h | 7 +++++++ lib/librte_stack/rte_stack.h | 7 +++++-- lib/librte_telemetry/rte_telemetry.h | 10 ++++++---- 12 files changed, 66 insertions(+), 13 deletions(-)lib/librte_bbdev/rte_bbdev.h index renamed from lib/librte_bbdev/rte_bbdev.h +0
-0
ecd95a823d..ab4e1bd6f4100644
lib/librte_bbdev/rte_bbdev.h line 15
Quoted 6 lines
lib/librte_bbdev/rte_bbdev.h +2
-1@@ -11,7 +11,8 @@* Wireless base band device abstraction APIs. * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice.
nit, is 'removed' a better choice instead of 'disappear'? May be something like:
All functions in this file may be changed or removed without prior notice.
Quoted 215 lines
lib/librte_bbdev/rte_bbdev.h +0
-0* * This API allows an application to discover, configure and use a device to * process operations. An asynchronous API (enqueue, followed by later dequeue) diff --git
a/lib/librte_bpf/rte_bpf.hb/lib/librte_bpf/rte_bpf.hindexcbf1cddaca..ceb3e26b03100644lib/librte_bpf/rte_bpf.h +5
-1@@ -7,9 +7,13 @@/** * @file rte_bpf.h -* @b EXPERIMENTAL: this API may change without prior notice * * RTE BPF support. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * librte_bpf provides a framework to load and execute eBPF bytecode * inside user-space dpdk based applications. * It supports basic set of features from eBPF spec diff --git
a/lib/librte_compressdev/rte_compressdev.hb/lib/librte_compressdev/rte_compressdev.h
index8052efe675..9c873b347d100644lib/librte_compressdev/rte_compressdev.h +5
-1@@ -8,7 +8,11 @@/** * @file rte_compressdev.h * -* RTE Compression Device APIs +* RTE Compression Device APIs. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * Defines comp device APIs for the provisioning of compression operations. */ lib/librte_fib/rte_fib.h index renamed from lib/librte_fib/rte_fib.h +0
-0
af3bbf07ee..b52d058406100644lib/librte_fib/rte_fib.h +7
-0@@ -8,6 +8,13 @@/** * @file +* +* RTE FIB library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * FIB (Forwarding information base) implementation * for IPv4 Longest Prefix Match */ lib/librte_fib/rte_fib6.h index renamed from lib/librte_fib/rte_fib6.h +0
-0
66c71c84c9..e6e8892ecb100644lib/librte_fib/rte_fib6.h +7
-0@@ -8,6 +8,13 @@/** * @file +* +* RTE FIB6 library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * FIB (Forwarding information base) implementation * for IPv6 Longest Prefix Match */ lib/librte_flow_classify/rte_flow_classify.h +4
-2@@ -8,9 +8,11 @@/** * @file * -* RTE Flow Classify Library +* RTE Flow Classify Library. * -* @b EXPERIMENTAL: this API may change without prior notice +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * This library provides flow record information with some measured properties.
*lib/librte_ipsec/rte_ipsec.h index renamed from lib/librte_ipsec/rte_ipsec.h +0
-0
6666cf7619..50f109553c100644lib/librte_ipsec/rte_ipsec.h +5
-1@@ -7,9 +7,13 @@/** * @file rte_ipsec.h -* @b EXPERIMENTAL: this API may change without prior notice * * RTE IPsec support. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * librte_ipsec provides a framework for data-path IPsec protocol * processing (ESP/AH). */ lib/librte_rcu/rte_rcu_qsbr.h index renamed from lib/librte_rcu/rte_rcu_qsbr.h +0
-0
fd4eb52b7f..891f64725e100644lib/librte_rcu/rte_rcu_qsbr.h +6
-1@@ -7,7 +7,12 @@/** * @file -* RTE Quiescent State Based Reclamation (QSBR) +* +* RTE Quiescent State Based Reclamation (QSBR). +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * Quiescent State (QS) is any point in the thread execution * where the thread does not hold a reference to a data structure diff --git
a/lib/librte_rib/rte_rib.hb/lib/librte_rib/rte_rib.hindex6b70de980a..729177870f100644lib/librte_rib/rte_rib.h +7
-0@@ -8,6 +8,13 @@/** * @file +* +* RTE RIB library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * Level compressed tree implementation for IPv4 Longest Prefix Match */ lib/librte_rib/rte_rib6.h index renamed from lib/librte_rib/rte_rib6.h +0
-0
871457138d..cbdb3fe5c2100644lib/librte_rib/rte_rib6.h +7
-0@@ -8,6 +8,13 @@/** * @file +* +* RTE rib6 library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. +* * Level compressed tree implementation for IPv6 Longest Prefix Match */ lib/librte_stack/rte_stack.h index renamed from lib/librte_stack/rte_stack.h +0
-0
27ddb199e5..7ac0b49eb6100644lib/librte_stack/rte_stack.h +5
-2@@ -4,9 +4,12 @@/** * @file rte_stack.h -* @b EXPERIMENTAL: this API may change without prior notice * -* RTE Stack +* RTE Stack. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. * * librte_stack provides an API for configuration and use of a bounded stack of
* pointers. Push and pop operations are MT-safe, allowing concurrent access,lib/librte_telemetry/rte_telemetry.h +0
-2@@ -20,11 +20,13 @@#define RTE_TEL_MAX_ARRAY_ENTRIES 512/** -* @warning -* @b EXPERIMENTAL: all functions in this file may change without prior notice
- *
* @file
- * RTE Telemetry
+ *
+ * RTE Telemetry.
+ *
+ * @warning
+ * @b EXPERIMENTAL:
+ * All functions in this file may change or disappear without prior notice. *
* The telemetry library provides a method to retrieve statistics from
* DPDK by sending a request message over a socket. DPDK will send
--
2.23.0
Re: [dpdk-dev] [PATCH 3/3] lib: remind experimental status in library headers
Hello Honnappa,
Quoted 9 lines · Honnappa Nagarahalli
lib/librte_bbdev/rte_bbdev.h line 15
Quoted 7 lines
lib/librte_bbdev/rte_bbdev.h +2
-1@@ -11,7 +11,8 @@* Wireless base band device abstraction APIs. * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. nit, is 'removed' a better choice instead of 'disappear'? May be something like:
All functions in this file may be changed or removed without prior notice.
I used the same form than in the abi policy (that I wanted but forgot to update in patch 1 afterwards... will be fixed in v2).
#. Libraries or APIs marked as :ref:experimental <experimental_apis> may
change without constraint, as they are not considered part of an ABI version. Experimental libraries have the major ABI version ``0``.
No strong opinion, but I prefer keeping a single phrasing. If we go with your suggestion, I will update the abi policy.
Signature · 1 line
David Marchand
Re: [dpdk-dev] [PATCH 3/3] lib: remind experimental status in library headers
<snip>
Quoted 19 lines
Hello Honnappa,
Quoted 8 lines · Honnappa Nagarahalli
lib/librte_bbdev/rte_bbdev.h line 15
Quoted 7 lines
lib/librte_bbdev/rte_bbdev.h +2
-1@@ -11,7 +11,8 @@* Wireless base band device abstraction APIs. * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may change or disappear without prior notice. nit, is 'removed' a better choice instead of 'disappear'? May be something
like:
Quoted 1 line
All functions in this file may be changed or removed without prior notice.
I used the same form than in the abi policy (that I wanted but forgot to update in patch 1 afterwards... will be fixed in v2).
Quoted 6 lines
#. Libraries or APIs marked as :ref:
experimental <experimental_apis>may
change without constraint, as they are not considered part of an ABI version. Experimental libraries have the major ABI version ``0``.No strong opinion, but I prefer keeping a single phrasing. If we go with your suggestion, I will update the abi policy.
Agree on using the same wording.
IMO, we should capture the 'removed/disappear' wording in the ABI policy.
Quoted 4 lines
--
David Marchand
Re: [dpdk-dev] [PATCH 3/3] lib: remind experimental status in library headers
In reply to David MarchandQuoted 19 lines
-----Original Message-----
From: David Marchand <[email protected]>
Sent: Friday, May 22, 2020 1:59 AM
To: [email protected]
Cc: [email protected]; [email protected]; [email protected]; Chautru, Nicolas <[email protected]>; Ananyev, Konstantin <[email protected]>; Trahe, Fiona <[email protected]>; Ashish Gupta <[email protected]>; Medvedkin, Vladimir <[email protected]>; Iremonger, Bernard <[email protected]>; Honnappa Nagarahalli <[email protected]>; Eads, Gage <[email protected]>; Olivier Matz <[email protected]>; Laatz, Kevin <[email protected]>
Subject: [PATCH 3/3] lib: remind experimental status in library headersThe following libraries are experimental, all of their functions can change or disappear:
Quoted 9 lines
-
librte_bbdev
-librte_bpf
-librte_compressdev
-librte_fib
-librte_flow_classify
-librte_ipsec
-librte_rcu
-librte_rib
-librte_stack
Thanks David. The stack library was added a year ago and its interfaces have been stable since then, so I think it better to drop its experimental tag altogether.
If there's no opposition to that, I can submit that patch separately.
Thanks,
Gage
Re: [dpdk-dev] [PATCH 3/3] lib: remind experimental status in library headers
Hello Gage,
Quoted 13 lines · Gage
Quoted 12 lines
The following libraries are experimental, all of their functions can change or disappear:
-
librte_bbdev
-librte_bpf
-librte_compressdev
-librte_fib
-librte_flow_classify
-librte_ipsec
-librte_rcu
-librte_rib
-librte_stack
Quoted 3 lines
Thanks David. The stack library was added a year ago and its interfaces have been stable since then, so I think it better to drop its experimental tag altogether.
If there's no opposition to that, I can submit that patch separately.
Just saw your patch.
As long as Olivier and you are comfortable this API is mature enough, I am fine with anything :-).
Signature · 1 line
David Marchand
v2 cover Experimental/internal libraries cleanup
In reply to David MarchandFollowing discussions on the mailing list and the 05/20 TB meeting, here is a series that drops the special versioning for non stable libraries.
Two notes:
- RIB/FIB library is not referenced in the API doxygen index, is this intentional?
- I inspected MAINTAINERS: librte_gro, librte_member and librte_rawdev are announced as experimental while their functions are part of the 20 stable ABI (in .map files + no __rte_experimental marking). Their fate must be discussed.
Changes since v1:
- rebased on master,
- removed mention of 0 version in abi docs,
- updated wording in experimental banner and abi docs following Honnappa comment,
Signature · 41 lines
David Marchand David Marchand (3): build: remove special versioning for non stable libraries drivers: drop workaround for internal libraries lib: remind experimental status in library headers buildtools/meson.build | 3 --- config/meson.build | 16 +++++------- devtools/check-abi.sh | 5 ---- devtools/libabigail.abignore | 25 +++++++++++++++++-- doc/guides/contributing/abi_policy.rst | 12 ++++----- doc/guides/contributing/abi_versioning.rst | 3 +-- drivers/bus/dpaa/rte_bus_dpaa_version.map | 6 ++--- drivers/bus/fslmc/rte_bus_fslmc_version.map | 6 ++--- .../common/dpaax/rte_common_dpaax_version.map | 6 ++--- .../rte_common_octeontx2_version.map | 6 ++--- .../dpaa2_sec/rte_pmd_dpaa2_sec_version.map | 6 ++--- .../dpaa_sec/rte_pmd_dpaa_sec_version.map | 6 ++--- .../mempool/dpaa/rte_mempool_dpaa_version.map | 6 ++--- .../rte_mempool_octeontx2_version.map | 6 ++--- drivers/meson.build | 17 +------------ drivers/net/dpaa2/rte_pmd_dpaa2_version.map | 6 ++--- lib/librte_bbdev/rte_bbdev.h | 3 ++- lib/librte_bpf/rte_bpf.h | 6 ++++- lib/librte_compressdev/rte_compressdev.h | 6 ++++- lib/librte_fib/rte_fib.h | 7 ++++++ lib/librte_fib/rte_fib6.h | 7 ++++++ lib/librte_flow_classify/rte_flow_classify.h | 6 +++-- lib/librte_ipsec/rte_ipsec.h | 6 ++++- lib/librte_rcu/rte_rcu_qsbr.h | 7 +++++- lib/librte_rib/rte_rib.h | 7 ++++++ lib/librte_rib/rte_rib6.h | 7 ++++++ lib/librte_stack/rte_stack.h | 7 ++++-- lib/librte_telemetry/rte_telemetry.h | 10 +++++--- lib/meson.build | 16 +----------- mk/rte.lib.mk | 5 ---- 30 files changed, 121 insertions(+), 114 deletions(-) -- 2.23.0
PATCH v2 1/3 build: remove special versioning for non stable libraries
Having a special versioning for experimental/internal libraries put a additional maintenance cost while this status is already announced in MAINTAINERS and the library headers/documentation. Following discussions and vote at 05/20 TB meeting [1], use a single versioning for all libraries in DPDK.
Note: for the ABI check, an exception [2] had been added when tweaking this special versioning [3].
Prefer explicit libabigail rules (which will be dropped in 20.11).
1: https://mails.dpdk.org/archives/dev/2020-May/168450.html
2: https://git.dpdk.org/dpdk/commit/?id=23d7ad5db41c
3: https://git.dpdk.org/dpdk/commit/?id=ec2b8cd7ed69
---
Changes since v1:
- removed mention of special handling in ABI docs,
--- buildtools/meson.build | 3 --- config/meson.build | 16 ++++++-------- devtools/check-abi.sh | 5 ----- devtools/libabigail.abignore | 25 ++++++++++++++++++++-- doc/guides/contributing/abi_policy.rst | 6 +----- doc/guides/contributing/abi_versioning.rst | 3 +-- drivers/meson.build | 17 +-------------- lib/meson.build | 16 +------------- mk/rte.lib.mk | 5 ----- 9 files changed, 33 insertions(+), 63 deletions(-)
buildtools/meson.build +0 -3
@@ -18,6 +18,3 @@ else endif map_to_def_cmd = py3 + files('map_to_def.py') sphinx_wrapper = py3 + files('call-sphinx-build.py') - -# stable ABI always starts with "DPDK_" -is_stable_cmd = [find_program('grep', 'findstr'), '^DPDK_']
config/meson.build +6 -10
@@ -25,18 +25,14 @@ major_version = '@0@.@1@'.format(pver.get(0), pver.get(1)) abi_version = run_command(find_program('cat', 'more'), abi_version_file).stdout().strip() -# Regular libraries have the abi_version as the filename extension +# Libraries have the abi_version as the filename extension # and have the soname be all but the final part of the abi_version. -# Experimental libraries have soname with '0.major' -# and the filename suffix as 0.majorminor versions, -# e.g. v20.1 => librte_stable.so.20.1, librte_experimental.so.0.201 -# sonames => librte_stable.so.20, librte_experimental.so.0.20 -# e.g. v20.0.1 => librte_stable.so.20.0.1, librte_experimental.so.0.2001 -# sonames => librte_stable.so.20.0, librte_experimental.so.0.200 +# e.g. v20.1 => librte_foo.so.20.1 +# sonames => librte_foo.so.20 +# e.g. v20.0.1 => librte_foo.so.20.0.1 +# sonames => librte_foo.so.20.0 abi_va = abi_version.split('.') -stable_so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1] -experimental_abi_version = '0.' + abi_va[0] + abi_va[1] + '.' + abi_va[2] -experimental_so_version = experimental_abi_version +so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1] # extract all version information into the build configuration dpdk_conf.set('RTE_VER_YEAR', pver.get(0).to_int())
devtools/check-abi.sh +0 -5
@@ -44,11 +44,6 @@ for dump in $(find $refdir -name "*.dump"); do echo "Skipped glue library $name." continue fi - # skip experimental libraries, with a sover starting with 0. - if grep -qE "\<soname='[^']*\.so\.0\.[^']*'" $dump; then - echo "Skipped experimental library $name." - continue - fi dump2=$(find $newdir -name $name) if [ -z "$dump2" ] || [ ! -e "$dump2" ]; then echo "Error: can't find $name in $newdir"
devtools/libabigail.abignore +23 -2
@@ -50,9 +50,9 @@ name = rte_crypto_aead_algorithm_strings ;;;;;;;;;;;;;;;;;;;;;; -; Temporary exceptions for new __rte_internal marking till DPDK 20.11 +; Temporary exceptions till DPDK 20.11 ;;;;;;;;;;;;;;;;;;;;;; -; Ignore moving OCTEONTX2 stable functions to INTERNAL tag +; Ignore moving OCTEONTX2 stable functions to INTERNAL [suppress_file] file_name_regexp = ^librte_common_octeontx2\. [suppress_file]
@@ -77,3 +77,24 @@ name = rte_dpaa2_mbuf_alloc_bulk [suppress_function] name_regexp = ^dpaa2?_.*tach$ +; Ignore soname changes for experimental libraries +[suppress_file] + file_name_regexp = ^librte_bbdev\. +[suppress_file] + file_name_regexp = ^librte_bpf\. +[suppress_file] + file_name_regexp = ^librte_compressdev\. +[suppress_file] + file_name_regexp = ^librte_fib\. +[suppress_file] + file_name_regexp = ^librte_flow_classify\. +[suppress_file] + file_name_regexp = ^librte_ipsec\. +[suppress_file] + file_name_regexp = ^librte_rcu\. +[suppress_file] + file_name_regexp = ^librte_rib\. +[suppress_file] + file_name_regexp = ^librte_telemetry\. +[suppress_file] + file_name_regexp = ^librte_stack\.
doc/guides/contributing/abi_policy.rst +1 -5
@@ -28,7 +28,6 @@ General Guidelines once approved these will form part of the next ABI version. #. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may change without constraint, as they are not considered part of an ABI version. - Experimental libraries have the major ABI version ``0``. #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop support for hardware which was previously supported, should be treated as an ABI change.
@@ -331,7 +330,4 @@ Libraries ~~~~~~~~~ Libraries marked as ``experimental`` are entirely not considered part of an ABI -version, and may change without warning at any time. Experimental libraries -always have a major ABI version of ``0`` to indicate they exist outside of -:ref:`abi_versioning` , with the minor version incremented with each ABI change -to library. +version, and may change without warning at any time.
doc/guides/contributing/abi_versioning.rst +1 -2
@@ -112,8 +112,7 @@ how this may be done. At the same time, the major ABI version is changed atomically across all libraries by incrementing the major version in the ABI_VERSION file. This is -done globally for all libraries that declare a stable ABI. For libraries marked -as EXPERIMENTAL, their major ABI version is always set to 0. +done globally for all libraries. Minor ABI versions ~~~~~~~~~~~~~~~~~~
drivers/meson.build +1 -16
@@ -124,21 +124,6 @@ foreach class:dpdk_driver_classes output: out_filename, depends: [pmdinfogen, tmp_lib]) - version_map = '@0@/@1@/@2@_version.map'.format( - meson.current_source_dir(), - drv_path, lib_name) - - is_stable = run_command(is_stable_cmd, - files(version_map)).returncode() == 0 - - if is_stable - lib_version = abi_version - so_version = stable_so_version - else - lib_version = experimental_abi_version - so_version = experimental_so_version - endif - # now build the static driver static_lib = static_library(lib_name, sources,
@@ -183,7 +168,7 @@ foreach class:dpdk_driver_classes c_args: cflags, link_args: lk_args, link_depends: lk_deps, - version: lib_version, + version: abi_version, soversion: so_version, install: true, install_dir: driver_install_path)
lib/meson.build +1 -15
@@ -107,20 +107,6 @@ foreach l:libraries cflags += '-DRTE_USE_FUNCTION_VERSIONING' endif - version_map = '@0@/@1@/rte_@2@_version.map'.format( - meson.current_source_dir(), dir_name, name) - - is_stable = run_command(is_stable_cmd, - files(version_map)).returncode() == 0 - - if is_stable - lib_version = abi_version - so_version = stable_so_version - else - lib_version = experimental_abi_version - so_version = experimental_so_version - endif - # first build static lib static_lib = static_library(libname, sources,
@@ -179,7 +165,7 @@ foreach l:libraries include_directories: includes, link_args: lk_args, link_depends: lk_deps, - version: lib_version, + version: abi_version, soversion: so_version, install: true) shared_dep = declare_dependency(link_with: shared_lib,
mk/rte.lib.mk +0 -5
@@ -13,11 +13,6 @@ VPATH += $(SRCDIR) LIBABIVER ?= $(shell cat $(RTE_SRCDIR)/ABI_VERSION) SOVER := $(basename $(LIBABIVER)) -ifeq ($(shell grep -s "^DPDK_" $(SRCDIR)/$(EXPORT_MAP)),) -# EXPERIMENTAL ABI is versioned as 0.major+minor, e.g. 0.201 for 20.1 ABI -LIBABIVER := 0.$(shell echo $(LIBABIVER) | awk 'BEGIN { FS="." }; { print $$1$$2"."$$3 }') -SOVER := $(LIBABIVER) -endif ifeq ($(CONFIG_RTE_BUILD_SHARED_LIB),y) SONAME := $(patsubst %.a,%.so.$(SOVER),$(LIB))
Signature · 1 line
2.23.0
Re: [dpdk-dev] [PATCH v2 1/3] build: remove special versioning for non stable libraries
Quoted 10 lines · David Marchand
Having a special versioning for experimental/internal libraries put a additional maintenance cost while this status is already announced in
MAINTAINERSand the library headers/documentation. Following discussions and vote at 05/20 TB meeting [1], use a single versioning for all libraries in DPDK.Note: for the ABI check, an exception [2] had been added when tweaking this special versioning [3].
Prefer explicit libabigail rules (which will be dropped in 20.11).
I have missed the new experimental libraries from 20.05. Expect a v3 later today.
Signature · 1 line
David Marchand
PATCH v2 2/3 drivers: drop workaround for internal libraries
In reply to David MarchandNow that all libraries have a single version, we can drop the empty stable blocks that had been added when moving symbols from stable to internal ABI.
--- drivers/bus/dpaa/rte_bus_dpaa_version.map | 6 ++---- drivers/bus/fslmc/rte_bus_fslmc_version.map | 6 ++---- drivers/common/dpaax/rte_common_dpaax_version.map | 6 ++---- drivers/common/octeontx2/rte_common_octeontx2_version.map | 6 ++---- drivers/crypto/dpaa2_sec/rte_pmd_dpaa2_sec_version.map | 6 ++---- drivers/crypto/dpaa_sec/rte_pmd_dpaa_sec_version.map | 6 ++---- drivers/mempool/dpaa/rte_mempool_dpaa_version.map | 6 ++---- drivers/mempool/octeontx2/rte_mempool_octeontx2_version.map | 6 ++---- drivers/net/dpaa2/rte_pmd_dpaa2_version.map | 6 ++---- 9 files changed, 18 insertions(+), 36 deletions(-)
drivers/bus/dpaa/rte_bus_dpaa_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -90,4 +86,6 @@ INTERNAL { rte_dpaa_portal_fq_close; rte_dpaa_portal_fq_init; rte_dpaa_portal_init; + + local: *; };
drivers/bus/fslmc/rte_bus_fslmc_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - EXPERIMENTAL { global:
@@ -111,4 +107,6 @@ INTERNAL { rte_fslmc_get_device_count; rte_fslmc_object_register; rte_global_active_dqs_list; + + local: *; };
drivers/common/dpaax/rte_common_dpaax_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -23,4 +19,6 @@ INTERNAL { of_n_addr_cells; of_translate_address; rta_sec_era; + + local: *; };
drivers/common/octeontx2/rte_common_octeontx2_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -42,4 +38,6 @@ INTERNAL { otx2_sso_pf_func_get; otx2_sso_pf_func_set; otx2_unregister_irq; + + local: *; };
drivers/crypto/dpaa2_sec/rte_pmd_dpaa2_sec_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: dpaa2_sec_eventq_attach; dpaa2_sec_eventq_detach; + + local: *; };
drivers/crypto/dpaa_sec/rte_pmd_dpaa_sec_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: dpaa_sec_eventq_attach; dpaa_sec_eventq_detach; + + local: *; };
drivers/mempool/dpaa/rte_mempool_dpaa_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: rte_dpaa_bpid_info; rte_dpaa_memsegs; + + local: *; };
drivers/mempool/octeontx2/rte_mempool_octeontx2_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: otx2_npa_lf_fini; otx2_npa_lf_init; + + local: *; };
drivers/net/dpaa2/rte_pmd_dpaa2_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - EXPERIMENTAL { global:
@@ -15,4 +11,6 @@ INTERNAL { dpaa2_eth_eventq_attach; dpaa2_eth_eventq_detach; + + local: *; };
Signature · 1 line
2.23.0
PATCH v2 3/3 lib: remind experimental status in library headers
In reply to David MarchandThe following libraries are experimental, all of their functions can be changed or removed:
- librte_bbdev
- librte_bpf
- librte_compressdev
- librte_fib
- librte_flow_classify
- librte_ipsec
- librte_rcu
- librte_rib
- librte_stack
- librte_telemetry
Their status is properly announced in MAINTAINERS.
Remind this status in their headers in a common fashion (aligned to ABI docs).
---
Changes since v1:
- updated wording following Honnappa comment
--- doc/guides/contributing/abi_policy.rst | 8 +++++--- lib/librte_bbdev/rte_bbdev.h | 3 ++- lib/librte_bpf/rte_bpf.h | 6 +++++- lib/librte_compressdev/rte_compressdev.h | 6 +++++- lib/librte_fib/rte_fib.h | 7 +++++++ lib/librte_fib/rte_fib6.h | 7 +++++++ lib/librte_flow_classify/rte_flow_classify.h | 6 ++++-- lib/librte_ipsec/rte_ipsec.h | 6 +++++- lib/librte_rcu/rte_rcu_qsbr.h | 7 ++++++- lib/librte_rib/rte_rib.h | 7 +++++++ lib/librte_rib/rte_rib6.h | 7 +++++++ lib/librte_stack/rte_stack.h | 7 +++++-- lib/librte_telemetry/rte_telemetry.h | 10 ++++++---- 13 files changed, 71 insertions(+), 16 deletions(-)
doc/guides/contributing/abi_policy.rst +5 -3
@@ -27,7 +27,8 @@ General Guidelines #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`, once approved these will form part of the next ABI version. #. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may - change without constraint, as they are not considered part of an ABI version. + be changed or removed without prior notice, as they are not considered part + of an ABI version. #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop support for hardware which was previously supported, should be treated as an ABI change.
@@ -294,7 +295,7 @@ APIs ~~~~ APIs marked as ``experimental`` are not considered part of an ABI version and -may change without warning at any time. Since changes to APIs are most likely +may be changed or removed without prior notice. Since changes to APIs are most likely immediately after their introduction, as users begin to take advantage of those new APIs and start finding issues with them, new DPDK APIs will be automatically marked as ``experimental`` to allow for a period of stabilization before they
@@ -330,4 +331,5 @@ Libraries ~~~~~~~~~ Libraries marked as ``experimental`` are entirely not considered part of an ABI -version, and may change without warning at any time. +version. +All functions in such libraries may be changed or removed without prior notice.
lib/librte_bbdev/rte_bbdev.h +2 -1
@@ -11,7 +11,8 @@* Wireless base band device abstraction APIs. * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * This API allows an application to discover, configure and use a device to * process operations. An asynchronous API (enqueue, followed by later dequeue)
lib/librte_bpf/rte_bpf.h +5 -1
@@ -7,9 +7,13 @@/** * @file rte_bpf.h -* @b EXPERIMENTAL: this API may change without prior notice * * RTE BPF support. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * librte_bpf provides a framework to load and execute eBPF bytecode * inside user-space dpdk based applications. * It supports basic set of features from eBPF spec
lib/librte_compressdev/rte_compressdev.h +5 -1
@@ -8,7 +8,11 @@/** * @file rte_compressdev.h * -* RTE Compression Device APIs +* RTE Compression Device APIs. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * Defines comp device APIs for the provisioning of compression operations. */
lib/librte_fib/rte_fib.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE FIB library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * FIB (Forwarding information base) implementation * for IPv4 Longest Prefix Match */
lib/librte_fib/rte_fib6.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE FIB6 library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * FIB (Forwarding information base) implementation * for IPv6 Longest Prefix Match */
lib/librte_flow_classify/rte_flow_classify.h +4 -2
@@ -8,9 +8,11 @@/** * @file * -* RTE Flow Classify Library +* RTE Flow Classify Library. * -* @b EXPERIMENTAL: this API may change without prior notice +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * This library provides flow record information with some measured properties. *
lib/librte_ipsec/rte_ipsec.h +5 -1
@@ -7,9 +7,13 @@/** * @file rte_ipsec.h -* @b EXPERIMENTAL: this API may change without prior notice * * RTE IPsec support. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * librte_ipsec provides a framework for data-path IPsec protocol * processing (ESP/AH). */
lib/librte_rcu/rte_rcu_qsbr.h +6 -1
@@ -7,7 +7,12 @@/** * @file -* RTE Quiescent State Based Reclamation (QSBR) +* +* RTE Quiescent State Based Reclamation (QSBR). +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * Quiescent State (QS) is any point in the thread execution * where the thread does not hold a reference to a data structure
lib/librte_rib/rte_rib.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE RIB library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * Level compressed tree implementation for IPv4 Longest Prefix Match */
lib/librte_rib/rte_rib6.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE rib6 library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * Level compressed tree implementation for IPv6 Longest Prefix Match */
lib/librte_stack/rte_stack.h +5 -2
@@ -4,9 +4,12 @@/** * @file rte_stack.h -* @b EXPERIMENTAL: this API may change without prior notice * -* RTE Stack +* RTE Stack. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * librte_stack provides an API for configuration and use of a bounded stack of * pointers. Push and pop operations are MT-safe, allowing concurrent access,
lib/librte_telemetry/rte_telemetry.h +6 -4
@@ -20,11 +20,13 @@#define RTE_TEL_MAX_ARRAY_ENTRIES 512/** -* @warning -* @b EXPERIMENTAL: all functions in this file may change without prior notice -* * @file -* RTE Telemetry +* +* RTE Telemetry. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * The telemetry library provides a method to retrieve statistics from * DPDK by sending a request message over a socket. DPDK will send
Signature · 1 line
2.23.0
v3 cover Experimental/internal libraries cleanup
In reply to David MarchandFollowing discussions on the mailing list and the 05/20 TB meeting, here is a series that drops the special versioning for non stable libraries.
Two notes:
- RIB/FIB library is not referenced in the API doxygen index, is this intentional?
- I inspected MAINTAINERS: librte_gro, librte_member and librte_rawdev are announced as experimental while their functions are part of the 20 stable ABI (in .map files + no __rte_experimental marking). Their fate must be discussed.
Changes since v2:
- added librte_graph and librte_node missed when rebasing to 20.05,
Changes since v1:
- rebased on master,
- removed mention of 0 version in abi docs,
- updated wording in experimental banner and abi docs following Honnappa comment,
Signature · 45 lines
David Marchand David Marchand (3): build: remove special versioning for non stable libraries drivers: drop workaround for internal libraries lib: remind experimental status in library headers buildtools/meson.build | 3 -- config/meson.build | 16 ++++------ devtools/check-abi.sh | 5 ---- devtools/libabigail.abignore | 29 +++++++++++++++++-- doc/guides/contributing/abi_policy.rst | 12 ++++---- doc/guides/contributing/abi_versioning.rst | 3 +- drivers/bus/dpaa/rte_bus_dpaa_version.map | 6 ++-- drivers/bus/fslmc/rte_bus_fslmc_version.map | 6 ++-- .../common/dpaax/rte_common_dpaax_version.map | 6 ++-- .../rte_common_octeontx2_version.map | 6 ++-- .../dpaa2_sec/rte_pmd_dpaa2_sec_version.map | 6 ++-- .../dpaa_sec/rte_pmd_dpaa_sec_version.map | 6 ++-- .../mempool/dpaa/rte_mempool_dpaa_version.map | 6 ++-- .../rte_mempool_octeontx2_version.map | 6 ++-- drivers/meson.build | 17 +---------- drivers/net/dpaa2/rte_pmd_dpaa2_version.map | 6 ++-- lib/librte_bbdev/rte_bbdev.h | 3 +- lib/librte_bpf/rte_bpf.h | 6 +++- lib/librte_compressdev/rte_compressdev.h | 6 +++- lib/librte_fib/rte_fib.h | 7 +++++ lib/librte_fib/rte_fib6.h | 7 +++++ lib/librte_flow_classify/rte_flow_classify.h | 6 ++-- lib/librte_graph/rte_graph.h | 3 +- lib/librte_graph/rte_graph_worker.h | 3 +- lib/librte_ipsec/rte_ipsec.h | 6 +++- lib/librte_node/rte_node_eth_api.h | 3 +- lib/librte_node/rte_node_ip4_api.h | 3 +- lib/librte_rcu/rte_rcu_qsbr.h | 7 ++++- lib/librte_rib/rte_rib.h | 7 +++++ lib/librte_rib/rte_rib6.h | 7 +++++ lib/librte_stack/rte_stack.h | 7 +++-- lib/librte_telemetry/rte_telemetry.h | 10 ++++--- lib/meson.build | 16 +--------- mk/rte.lib.mk | 5 ---- 34 files changed, 133 insertions(+), 118 deletions(-) -- 2.23.0
PATCH v3 1/3 build: remove special versioning for non stable libraries
Having a special versioning for experimental/internal libraries put a additional maintenance cost while this status is already announced in MAINTAINERS and the library headers/documentation. Following discussions and vote at 05/20 TB meeting [1], use a single versioning for all libraries in DPDK.
Note: for the ABI check, an exception [2] had been added when tweaking this special versioning [3].
Prefer explicit libabigail rules (which will be dropped in 20.11).
1: https://mails.dpdk.org/archives/dev/2020-May/168450.html
2: https://git.dpdk.org/dpdk/commit/?id=23d7ad5db41c
3: https://git.dpdk.org/dpdk/commit/?id=ec2b8cd7ed69
---
Changes since v2:
- added exceptions for librte_graph and librte_node missed post 20.05,
Changes since v1:
- removed mention of special handling in ABI docs,
--- buildtools/meson.build | 3 --- config/meson.build | 16 +++++------- devtools/check-abi.sh | 5 ---- devtools/libabigail.abignore | 29 ++++++++++++++++++++-- doc/guides/contributing/abi_policy.rst | 6 +---- doc/guides/contributing/abi_versioning.rst | 3 +-- drivers/meson.build | 17 +------------ lib/meson.build | 16 +----------- mk/rte.lib.mk | 5 ---- 9 files changed, 37 insertions(+), 63 deletions(-)
buildtools/meson.build +0 -3
@@ -18,6 +18,3 @@ else endif map_to_def_cmd = py3 + files('map_to_def.py') sphinx_wrapper = py3 + files('call-sphinx-build.py') - -# stable ABI always starts with "DPDK_" -is_stable_cmd = [find_program('grep', 'findstr'), '^DPDK_']
config/meson.build +6 -10
@@ -25,18 +25,14 @@ major_version = '@0@.@1@'.format(pver.get(0), pver.get(1)) abi_version = run_command(find_program('cat', 'more'), abi_version_file).stdout().strip() -# Regular libraries have the abi_version as the filename extension +# Libraries have the abi_version as the filename extension # and have the soname be all but the final part of the abi_version. -# Experimental libraries have soname with '0.major' -# and the filename suffix as 0.majorminor versions, -# e.g. v20.1 => librte_stable.so.20.1, librte_experimental.so.0.201 -# sonames => librte_stable.so.20, librte_experimental.so.0.20 -# e.g. v20.0.1 => librte_stable.so.20.0.1, librte_experimental.so.0.2001 -# sonames => librte_stable.so.20.0, librte_experimental.so.0.200 +# e.g. v20.1 => librte_foo.so.20.1 +# sonames => librte_foo.so.20 +# e.g. v20.0.1 => librte_foo.so.20.0.1 +# sonames => librte_foo.so.20.0 abi_va = abi_version.split('.') -stable_so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1] -experimental_abi_version = '0.' + abi_va[0] + abi_va[1] + '.' + abi_va[2] -experimental_so_version = experimental_abi_version +so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1] # extract all version information into the build configuration dpdk_conf.set('RTE_VER_YEAR', pver.get(0).to_int())
devtools/check-abi.sh +0 -5
@@ -44,11 +44,6 @@ for dump in $(find $refdir -name "*.dump"); do echo "Skipped glue library $name." continue fi - # skip experimental libraries, with a sover starting with 0. - if grep -qE "\<soname='[^']*\.so\.0\.[^']*'" $dump; then - echo "Skipped experimental library $name." - continue - fi dump2=$(find $newdir -name $name) if [ -z "$dump2" ] || [ ! -e "$dump2" ]; then echo "Error: can't find $name in $newdir"
devtools/libabigail.abignore +27 -2
@@ -50,9 +50,9 @@ name = rte_crypto_aead_algorithm_strings ;;;;;;;;;;;;;;;;;;;;;; -; Temporary exceptions for new __rte_internal marking till DPDK 20.11 +; Temporary exceptions till DPDK 20.11 ;;;;;;;;;;;;;;;;;;;;;; -; Ignore moving OCTEONTX2 stable functions to INTERNAL tag +; Ignore moving OCTEONTX2 stable functions to INTERNAL [suppress_file] file_name_regexp = ^librte_common_octeontx2\. [suppress_file]
@@ -77,3 +77,28 @@ name = rte_dpaa2_mbuf_alloc_bulk [suppress_function] name_regexp = ^dpaa2?_.*tach$ +; Ignore soname changes for experimental libraries +[suppress_file] + file_name_regexp = ^librte_bbdev\. +[suppress_file] + file_name_regexp = ^librte_bpf\. +[suppress_file] + file_name_regexp = ^librte_compressdev\. +[suppress_file] + file_name_regexp = ^librte_fib\. +[suppress_file] + file_name_regexp = ^librte_flow_classify\. +[suppress_file] + file_name_regexp = ^librte_graph\. +[suppress_file] + file_name_regexp = ^librte_ipsec\. +[suppress_file] + file_name_regexp = ^librte_node\. +[suppress_file] + file_name_regexp = ^librte_rcu\. +[suppress_file] + file_name_regexp = ^librte_rib\. +[suppress_file] + file_name_regexp = ^librte_telemetry\. +[suppress_file] + file_name_regexp = ^librte_stack\.
doc/guides/contributing/abi_policy.rst +1 -5
@@ -28,7 +28,6 @@ General Guidelines once approved these will form part of the next ABI version. #. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may change without constraint, as they are not considered part of an ABI version. - Experimental libraries have the major ABI version ``0``. #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop support for hardware which was previously supported, should be treated as an ABI change.
@@ -331,7 +330,4 @@ Libraries ~~~~~~~~~ Libraries marked as ``experimental`` are entirely not considered part of an ABI -version, and may change without warning at any time. Experimental libraries -always have a major ABI version of ``0`` to indicate they exist outside of -:ref:`abi_versioning` , with the minor version incremented with each ABI change -to library. +version, and may change without warning at any time.
doc/guides/contributing/abi_versioning.rst +1 -2
@@ -112,8 +112,7 @@ how this may be done. At the same time, the major ABI version is changed atomically across all libraries by incrementing the major version in the ABI_VERSION file. This is -done globally for all libraries that declare a stable ABI. For libraries marked -as EXPERIMENTAL, their major ABI version is always set to 0. +done globally for all libraries. Minor ABI versions ~~~~~~~~~~~~~~~~~~
drivers/meson.build +1 -16
@@ -124,21 +124,6 @@ foreach class:dpdk_driver_classes output: out_filename, depends: [pmdinfogen, tmp_lib]) - version_map = '@0@/@1@/@2@_version.map'.format( - meson.current_source_dir(), - drv_path, lib_name) - - is_stable = run_command(is_stable_cmd, - files(version_map)).returncode() == 0 - - if is_stable - lib_version = abi_version - so_version = stable_so_version - else - lib_version = experimental_abi_version - so_version = experimental_so_version - endif - # now build the static driver static_lib = static_library(lib_name, sources,
@@ -183,7 +168,7 @@ foreach class:dpdk_driver_classes c_args: cflags, link_args: lk_args, link_depends: lk_deps, - version: lib_version, + version: abi_version, soversion: so_version, install: true, install_dir: driver_install_path)
lib/meson.build +1 -15
@@ -107,20 +107,6 @@ foreach l:libraries cflags += '-DRTE_USE_FUNCTION_VERSIONING' endif - version_map = '@0@/@1@/rte_@2@_version.map'.format( - meson.current_source_dir(), dir_name, name) - - is_stable = run_command(is_stable_cmd, - files(version_map)).returncode() == 0 - - if is_stable - lib_version = abi_version - so_version = stable_so_version - else - lib_version = experimental_abi_version - so_version = experimental_so_version - endif - # first build static lib static_lib = static_library(libname, sources,
@@ -179,7 +165,7 @@ foreach l:libraries include_directories: includes, link_args: lk_args, link_depends: lk_deps, - version: lib_version, + version: abi_version, soversion: so_version, install: true) shared_dep = declare_dependency(link_with: shared_lib,
mk/rte.lib.mk +0 -5
@@ -13,11 +13,6 @@ VPATH += $(SRCDIR) LIBABIVER ?= $(shell cat $(RTE_SRCDIR)/ABI_VERSION) SOVER := $(basename $(LIBABIVER)) -ifeq ($(shell grep -s "^DPDK_" $(SRCDIR)/$(EXPORT_MAP)),) -# EXPERIMENTAL ABI is versioned as 0.major+minor, e.g. 0.201 for 20.1 ABI -LIBABIVER := 0.$(shell echo $(LIBABIVER) | awk 'BEGIN { FS="." }; { print $$1$$2"."$$3 }') -SOVER := $(LIBABIVER) -endif ifeq ($(CONFIG_RTE_BUILD_SHARED_LIB),y) SONAME := $(patsubst %.a,%.so.$(SOVER),$(LIB))
Signature · 1 line
2.23.0
Re: [dpdk-dev] [PATCH v3 1/3] build: remove special versioning for non stable libraries
Quoted 125 lines · David Marchand
Having a special versioning for experimental/internal libraries put a additional maintenance cost while this status is already announced in
MAINTAINERSand the library headers/documentation. Following discussions and vote at 05/20 TB meeting [1], use a single versioning for all libraries in DPDK.Note: for the ABI check, an exception [2] had been added when tweaking this special versioning [3].
Prefer explicit libabigail rules (which will be dropped in 20.11).1: https://mails.dpdk.org/archives/dev/2020-May/168450.html
2: https://git.dpdk.org/dpdk/commit/?id=23d7ad5db41c
3: https://git.dpdk.org/dpdk/commit/?id=ec2b8cd7ed69Signed-off-by David Marchand <[email protected]>---
Changes since v2:
- added exceptions forlibrte_graphandlibrte_nodemissed post 20.05,Changes since v1:
- removed mention of special handling in ABI docs,--- buildtools/meson.build | 3 --- config/meson.build | 16 +++++------- devtools/check-abi.sh | 5 ---- devtools/libabigail.abignore | 29 ++++++++++++++++++++-- doc/guides/contributing/abi_policy.rst | 6 +---- doc/guides/contributing/abi_versioning.rst | 3 +-- drivers/meson.build | 17 +------------ lib/meson.build | 16 +----------- mk/rte.lib.mk | 5 ---- 9 files changed, 37 insertions(+), 63 deletions(-)buildtools/meson.build +0
-3@@ -18,6 +18,3 @@ else endif map_to_def_cmd = py3 + files('map_to_def.py') sphinx_wrapper = py3 + files('call-sphinx-build.py') - -# stable ABI always starts with "DPDK_" -is_stable_cmd = [find_program('grep', 'findstr'), '^DPDK_']config/meson.build +6
-10@@ -25,18 +25,14 @@ major_version = '@0@.@1@'.format(pver.get(0), pver.get(1)) abi_version = run_command(find_program('cat', 'more'), abi_version_file).stdout().strip() -# Regular libraries have the abi_version as the filename extension +# Libraries have the abi_version as the filename extension # and have the soname be all but the final part of the abi_version. -# Experimental libraries have soname with '0.major' -# and the filename suffix as 0.majorminor versions, -# e.g. v20.1 => librte_stable.so.20.1, librte_experimental.so.0.201 -# sonames => librte_stable.so.20, librte_experimental.so.0.20 -# e.g. v20.0.1 => librte_stable.so.20.0.1, librte_experimental.so.0.2001 -# sonames => librte_stable.so.20.0, librte_experimental.so.0.200 +# e.g. v20.1 => librte_foo.so.20.1 +# sonames => librte_foo.so.20 +# e.g. v20.0.1 => librte_foo.so.20.0.1 +# sonames => librte_foo.so.20.0 abi_va = abi_version.split('.') -stable_so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1] -experimental_abi_version = '0.' + abi_va[0] + abi_va[1] + '.' + abi_va[2] -experimental_so_version = experimental_abi_version +so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1] # extract all version information into the build configuration dpdk_conf.set('RTE_VER_YEAR', pver.get(0).to_int())devtools/check-abi.sh +0
-5@@ -44,11 +44,6 @@ for dump in $(find $refdir -name "*.dump"); do echo "Skipped glue library $name." continue fi - # skip experimental libraries, with a sover starting with 0. - if grep -qE "\<soname='[^']*\.so\.0\.[^']*'" $dump; then - echo "Skipped experimental library $name." - continue - fi dump2=$(find $newdir -name $name) if [ -z "$dump2" ] || [ ! -e "$dump2" ]; then echo "Error: can't find $name in $newdir"devtools/libabigail.abignore +17
-2@@ -50,9 +50,9 @@ name = rte_crypto_aead_algorithm_strings ;;;;;;;;;;;;;;;;;;;;;; -; Temporary exceptions for new __rte_internal marking till DPDK 20.11 +; Temporary exceptions till DPDK 20.11 ;;;;;;;;;;;;;;;;;;;;;; -; Ignore moving OCTEONTX2 stable functions to INTERNAL tag +; Ignore moving OCTEONTX2 stable functions to INTERNAL [suppress_file] file_name_regexp = ^librte_common_octeontx2\. [suppress_file]@@ -77,3 +77,28 @@ name = rte_dpaa2_mbuf_alloc_bulk [suppress_function] name_regexp = ^dpaa2?_.*tach$ +; Ignore soname changes for experimental libraries +[suppress_file] + file_name_regexp = ^librte_bbdev\. +[suppress_file] + file_name_regexp = ^librte_bpf\. +[suppress_file] + file_name_regexp = ^librte_compressdev\. +[suppress_file] + file_name_regexp = ^librte_fib\. +[suppress_file] + file_name_regexp = ^librte_flow_classify\. +[suppress_file] + file_name_regexp = ^librte_graph\. +[suppress_file] + file_name_regexp = ^librte_ipsec\.
devtools/libabigail.abignore line 104
Quoted 10 lines
devtools/libabigail.abignore +10
-0+[suppress_file] + file_name_regexp = ^librte_node\. +[suppress_file] + file_name_regexp = ^librte_rcu\. +[suppress_file] + file_name_regexp = ^librte_rib\. +[suppress_file] + file_name_regexp = ^librte_telemetry\. +[suppress_file] + file_name_regexp = ^librte_stack\.
Can't help feeling on this, that are swapping one headache for another. We are adding the cost of maintaining a bloated libabigail.abignore.
I still maintain, that if we marked libraries as "experimental" in the filename.
It serve both as obvious reminder, and simpifies this maintenance - no bloated libabigail.abiignore.
I agree that there is no need for special versioning.
Quoted 26 lines
doc/guides/contributing/abi_policy.rst +1
-5@@ -28,7 +28,6 @@ General Guidelines once approved these will form part of the next ABI version. #. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may change without constraint, as they are not considered part of an ABI version. - Experimental libraries have the major ABI version ``0``. #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop support for hardware which was previously supported, should be treated as an ABI change.@@ -331,7 +330,4 @@ Libraries ~~~~~~~~~ Libraries marked as ``experimental`` are entirely not considered part of an ABI -version, and may change without warning at any time. Experimental libraries -always have a major ABI version of ``0`` to indicate they exist outside of -:ref:`abi_versioning` , with the minor version incremented with each ABI change -to library. +version, and may change without warning at any time.doc/guides/contributing/abi_versioning.rst +0
-0
doc/guides/contributing/abi_versioning.rst how this may be done. · line 115
Quoted 6 lines
doc/guides/contributing/abi_versioning.rst +1
-2@@ -112,8 +112,7 @@ how this may be done. At the same time, the major ABI version is changed atomically across all libraries by incrementing the major version in the ABI_VERSION file. This is -done globally for all libraries that declare a stable ABI. For libraries marked -as EXPERIMENTAL, their major ABI version is always set to 0. +done globally for all libraries.
Documentation changes are 100% OK.
Quoted 88 lines
doc/guides/contributing/abi_versioning.rst +0
-0Minor ABI versions ~~~~~~~~~~~~~~~~~~drivers/meson.build +1
-16@@ -124,21 +124,6 @@ foreach class:dpdk_driver_classes output: out_filename, depends: [pmdinfogen, tmp_lib]) - version_map = '@0@/@1@/@2@_version.map'.format( - meson.current_source_dir(), - drv_path, lib_name) - - is_stable = run_command(is_stable_cmd, - files(version_map)).returncode() == 0 - - if is_stable - lib_version = abi_version - so_version = stable_so_version - else - lib_version = experimental_abi_version - so_version = experimental_so_version - endif - # now build the static driver static_lib = static_library(lib_name, sources,@@ -183,7 +168,7 @@ foreach class:dpdk_driver_classes c_args: cflags, link_args: lk_args, link_depends: lk_deps, - version: lib_version, + version: abi_version, soversion: so_version, install: true, install_dir: driver_install_path)lib/meson.build +1
-15@@ -107,20 +107,6 @@ foreach l:libraries cflags += '-DRTE_USE_FUNCTION_VERSIONING' endif - version_map = '@0@/@1@/rte_@2@_version.map'.format( - meson.current_source_dir(), dir_name, name) - - is_stable = run_command(is_stable_cmd, - files(version_map)).returncode() == 0 - - if is_stable - lib_version = abi_version - so_version = stable_so_version - else - lib_version = experimental_abi_version - so_version = experimental_so_version - endif - # first build static lib static_lib = static_library(libname, sources,@@ -179,7 +165,7 @@ foreach l:libraries include_directories: includes, link_args: lk_args, link_depends: lk_deps, - version: lib_version, + version: abi_version, soversion: so_version, install: true) shared_dep = declare_dependency(link_with: shared_lib,mk/rte.lib.mk +0
-5@@ -13,11 +13,6 @@ VPATH += $(SRCDIR) LIBABIVER ?= $(shell cat $(RTE_SRCDIR)/ABI_VERSION) SOVER := $(basename $(LIBABIVER)) -ifeq ($(shell grep -s "^DPDK_" $(SRCDIR)/$(EXPORT_MAP)),) -# EXPERIMENTAL ABI is versioned as 0.major+minor, e.g. 0.201 for 20.1 ABI -LIBABIVER := 0.$(shell echo $(LIBABIVER) | awk 'BEGIN { FS="." }; { print $$1$$2"."$$3 }') -SOVER := $(LIBABIVER) -endif ifeq ($(CONFIG_RTE_BUILD_SHARED_LIB),y) SONAME := $(patsubst %.a,%.so.$(SOVER),$(LIB))
PATCH v3 2/3 drivers: drop workaround for internal libraries
In reply to David MarchandNow that all libraries have a single version, we can drop the empty stable blocks that had been added when moving symbols from stable to internal ABI.
--- drivers/bus/dpaa/rte_bus_dpaa_version.map | 6 ++---- drivers/bus/fslmc/rte_bus_fslmc_version.map | 6 ++---- drivers/common/dpaax/rte_common_dpaax_version.map | 6 ++---- drivers/common/octeontx2/rte_common_octeontx2_version.map | 6 ++---- drivers/crypto/dpaa2_sec/rte_pmd_dpaa2_sec_version.map | 6 ++---- drivers/crypto/dpaa_sec/rte_pmd_dpaa_sec_version.map | 6 ++---- drivers/mempool/dpaa/rte_mempool_dpaa_version.map | 6 ++---- drivers/mempool/octeontx2/rte_mempool_octeontx2_version.map | 6 ++---- drivers/net/dpaa2/rte_pmd_dpaa2_version.map | 6 ++---- 9 files changed, 18 insertions(+), 36 deletions(-)
drivers/bus/dpaa/rte_bus_dpaa_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -90,4 +86,6 @@ INTERNAL { rte_dpaa_portal_fq_close; rte_dpaa_portal_fq_init; rte_dpaa_portal_init; + + local: *; };
drivers/bus/fslmc/rte_bus_fslmc_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - EXPERIMENTAL { global:
@@ -111,4 +107,6 @@ INTERNAL { rte_fslmc_get_device_count; rte_fslmc_object_register; rte_global_active_dqs_list; + + local: *; };
drivers/common/dpaax/rte_common_dpaax_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -23,4 +19,6 @@ INTERNAL { of_n_addr_cells; of_translate_address; rta_sec_era; + + local: *; };
drivers/common/octeontx2/rte_common_octeontx2_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global:
@@ -42,4 +38,6 @@ INTERNAL { otx2_sso_pf_func_get; otx2_sso_pf_func_set; otx2_unregister_irq; + + local: *; };
drivers/crypto/dpaa2_sec/rte_pmd_dpaa2_sec_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: dpaa2_sec_eventq_attach; dpaa2_sec_eventq_detach; + + local: *; };
drivers/crypto/dpaa_sec/rte_pmd_dpaa_sec_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: dpaa_sec_eventq_attach; dpaa_sec_eventq_detach; + + local: *; };
drivers/mempool/dpaa/rte_mempool_dpaa_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: rte_dpaa_bpid_info; rte_dpaa_memsegs; + + local: *; };
drivers/mempool/octeontx2/rte_mempool_octeontx2_version.map +2 -4
@@ -1,10 +1,8 @@ -DPDK_20.0 { - local: *; -}; - INTERNAL { global: otx2_npa_lf_fini; otx2_npa_lf_init; + + local: *; };
drivers/net/dpaa2/rte_pmd_dpaa2_version.map +2 -4
@@ -1,7 +1,3 @@ -DPDK_20.0 { - local: *; -}; - EXPERIMENTAL { global:
@@ -15,4 +11,6 @@ INTERNAL { dpaa2_eth_eventq_attach; dpaa2_eth_eventq_detach; + + local: *; };
Signature · 1 line
2.23.0
PATCH v3 3/3 lib: remind experimental status in library headers
In reply to David MarchandThe following libraries are experimental, all of their functions can be changed or removed:
- librte_bbdev
- librte_bpf
- librte_compressdev
- librte_fib
- librte_flow_classify
- librte_graph
- librte_ipsec
- librte_node
- librte_rcu
- librte_rib
- librte_stack
- librte_telemetry
Their status is properly announced in MAINTAINERS.
Remind this status in their headers in a common fashion (aligned to ABI docs).
---
Changes since v2:
- updated librte_graph and librte_node
Changes since v1:
- updated wording following Honnappa comment
--- doc/guides/contributing/abi_policy.rst | 8 +++++--- lib/librte_bbdev/rte_bbdev.h | 3 ++- lib/librte_bpf/rte_bpf.h | 6 +++++- lib/librte_compressdev/rte_compressdev.h | 6 +++++- lib/librte_fib/rte_fib.h | 7 +++++++ lib/librte_fib/rte_fib6.h | 7 +++++++ lib/librte_flow_classify/rte_flow_classify.h | 6 ++++-- lib/librte_graph/rte_graph.h | 3 ++- lib/librte_graph/rte_graph_worker.h | 3 ++- lib/librte_ipsec/rte_ipsec.h | 6 +++++- lib/librte_node/rte_node_eth_api.h | 3 ++- lib/librte_node/rte_node_ip4_api.h | 3 ++- lib/librte_rcu/rte_rcu_qsbr.h | 7 ++++++- lib/librte_rib/rte_rib.h | 7 +++++++ lib/librte_rib/rte_rib6.h | 7 +++++++ lib/librte_stack/rte_stack.h | 7 +++++-- lib/librte_telemetry/rte_telemetry.h | 10 ++++++---- 17 files changed, 79 insertions(+), 20 deletions(-)
doc/guides/contributing/abi_policy.rst +5 -3
@@ -27,7 +27,8 @@ General Guidelines #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`, once approved these will form part of the next ABI version. #. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may - change without constraint, as they are not considered part of an ABI version. + be changed or removed without prior notice, as they are not considered part + of an ABI version. #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop support for hardware which was previously supported, should be treated as an ABI change.
@@ -294,7 +295,7 @@ APIs ~~~~ APIs marked as ``experimental`` are not considered part of an ABI version and -may change without warning at any time. Since changes to APIs are most likely +may be changed or removed without prior notice. Since changes to APIs are most likely immediately after their introduction, as users begin to take advantage of those new APIs and start finding issues with them, new DPDK APIs will be automatically marked as ``experimental`` to allow for a period of stabilization before they
@@ -330,4 +331,5 @@ Libraries ~~~~~~~~~ Libraries marked as ``experimental`` are entirely not considered part of an ABI -version, and may change without warning at any time. +version. +All functions in such libraries may be changed or removed without prior notice.
lib/librte_bbdev/rte_bbdev.h +2 -1
@@ -11,7 +11,8 @@* Wireless base band device abstraction APIs. * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * This API allows an application to discover, configure and use a device to * process operations. An asynchronous API (enqueue, followed by later dequeue)
lib/librte_bpf/rte_bpf.h +5 -1
@@ -7,9 +7,13 @@/** * @file rte_bpf.h -* @b EXPERIMENTAL: this API may change without prior notice * * RTE BPF support. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * librte_bpf provides a framework to load and execute eBPF bytecode * inside user-space dpdk based applications. * It supports basic set of features from eBPF spec
lib/librte_compressdev/rte_compressdev.h +5 -1
@@ -8,7 +8,11 @@/** * @file rte_compressdev.h * -* RTE Compression Device APIs +* RTE Compression Device APIs. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * Defines comp device APIs for the provisioning of compression operations. */
lib/librte_fib/rte_fib.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE FIB library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * FIB (Forwarding information base) implementation * for IPv4 Longest Prefix Match */
lib/librte_fib/rte_fib6.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE FIB6 library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * FIB (Forwarding information base) implementation * for IPv6 Longest Prefix Match */
lib/librte_flow_classify/rte_flow_classify.h +4 -2
@@ -8,9 +8,11 @@/** * @file * -* RTE Flow Classify Library +* RTE Flow Classify Library. * -* @b EXPERIMENTAL: this API may change without prior notice +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * This library provides flow record information with some measured properties. *
lib/librte_graph/rte_graph.h +2 -1
@@ -9,7 +9,8 @@* @file rte_graph.h * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * Graph architecture abstracts the data processing functions as * "node" and "link" them together to create a complex "graph" to enable
lib/librte_graph/rte_graph_worker.h +2 -1
@@ -9,7 +9,8 @@* @file rte_graph_worker.h * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * This API allows a worker thread to walk over a graph and nodes to create, * process, enqueue and move streams of objects to the next nodes.
lib/librte_ipsec/rte_ipsec.h +5 -1
@@ -7,9 +7,13 @@/** * @file rte_ipsec.h -* @b EXPERIMENTAL: this API may change without prior notice * * RTE IPsec support. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * librte_ipsec provides a framework for data-path IPsec protocol * processing (ESP/AH). */
lib/librte_node/rte_node_eth_api.h +2 -1
@@ -9,7 +9,8 @@* @file rte_node_eth_api.h * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * This API allows to setup ethdev_rx and ethdev_tx nodes * and its queue associations.
lib/librte_node/rte_node_ip4_api.h +2 -1
@@ -9,7 +9,8 @@* @file rte_node_ip4_api.h * * @warning -* @b EXPERIMENTAL: this API may change without prior notice +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * This API allows to do control path functions of ip4_* nodes * like ip4_lookup, ip4_rewrite.
lib/librte_rcu/rte_rcu_qsbr.h +6 -1
@@ -7,7 +7,12 @@/** * @file -* RTE Quiescent State Based Reclamation (QSBR) +* +* RTE Quiescent State Based Reclamation (QSBR). +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * Quiescent State (QS) is any point in the thread execution * where the thread does not hold a reference to a data structure
lib/librte_rib/rte_rib.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE RIB library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * Level compressed tree implementation for IPv4 Longest Prefix Match */
lib/librte_rib/rte_rib6.h +7 -0
@@ -8,6 +8,13 @@/** * @file +* +* RTE rib6 library. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. +* * Level compressed tree implementation for IPv6 Longest Prefix Match */
lib/librte_stack/rte_stack.h +5 -2
@@ -4,9 +4,12 @@/** * @file rte_stack.h -* @b EXPERIMENTAL: this API may change without prior notice * -* RTE Stack +* RTE Stack. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * librte_stack provides an API for configuration and use of a bounded stack of * pointers. Push and pop operations are MT-safe, allowing concurrent access,
lib/librte_telemetry/rte_telemetry.h +6 -4
@@ -20,11 +20,13 @@#define RTE_TEL_MAX_ARRAY_ENTRIES 512/** -* @warning -* @b EXPERIMENTAL: all functions in this file may change without prior notice -* * @file -* RTE Telemetry +* +* RTE Telemetry. +* +* @warning +* @b EXPERIMENTAL: +* All functions in this file may be changed or removed without prior notice. * * The telemetry library provides a method to retrieve statistics from * DPDK by sending a request message over a socket. DPDK will send
Signature · 1 line
2.23.0
Quoted 12 lines · David Marchand
Following discussions on the mailing list and the 05/20 TB meeting, here is a series that drops the special versioning for non stable libraries.
Two notes:
- RIB/FIB library is not referenced in the API doxygen index, is this intentional?
- I inspectedMAINTAINERS:librte_gro,librte_memberandlibrte_rawdevare announced as experimental while their functions are part of the 20 stable ABI (in .map files + no__rte_experimentalmarking). Their fate must be discussed.
Quoted 18 lines
Changes since v2:
- addedlibrte_graphandlibrte_nodemissed when rebasing to 20.05,Changes since v1:
- rebased on master,
- removed mention of 0 version in abi docs,
- updated wording in experimental banner and abi docs following Honnappa comment,Signature · 6 lines
David Marchand David Marchand (3): build: remove special versioning for non stable libraries drivers: drop workaround for internal libraries lib: remind experimental status in library headers
The build changes, and patchset as a whole, look ok to me and good to see the code simplified by this.
Thomas Monjalon
Applied26/06/2020 11:25, Bruce Richardson:
Quoted 4 lines · David Marchand
Quoted 3 lines
Following discussions on the mailing list and the 05/20 TB meeting, here is a series that drops the special versioning for non stable libraries.
[...]
Quoted 4 lines
The build changes, and patchset as a whole, look ok to me and good to see the code simplified by this.
Series-acked-by Bruce Richardson <[email protected]>
Applied, thanks
+Cc maintainers of the problematic libraries:
- librte_fib
- librte_rib
- librte_gro
- librte_member
- librte_rawdev
26/06/2020 10:16, David Marchand:
Quoted 7 lines
Following discussions on the mailing list and the 05/20 TB meeting, here is a series that drops the special versioning for non stable libraries.
Two notes:
- RIB/FIB library is not referenced in the API doxygen index, is this intentional?
Vladimir please, could you fix the miss in the doxygen index?
Quoted 4 lines
- I inspected
MAINTAINERS:librte_gro,librte_memberandlibrte_rawdevare announced as experimental while their functions are part of the 20 stable ABI (in .map files + no__rte_experimentalmarking). Their fate must be discussed.
I would suggest removing EXPERIMENTAL flag for gro, member and rawdev. They are probably already considered stable for a lot of users. Maintainers, are you OK to follow the ABI compatibility rules for these libraries? Do you feel these libraries are mature enough?
Quoted 23 lines · Thomas Monjalon
+Cc maintainers of the problematic libraries:
-librte_fib
-librte_rib
-librte_gro
-librte_member
-librte_rawdev26/06/2020 10:16, David Marchand:
Quoted 7 lines
Following discussions on the mailing list and the 05/20 TB meeting, here is a series that drops the special versioning for non stable libraries.
Two notes:
- RIB/FIB library is not referenced in the API doxygen index, is this intentional?
Vladimir please, could you fix the miss in the doxygen index?
Quoted 4 lines
- I inspected
MAINTAINERS:librte_gro,librte_memberandlibrte_rawdevare announced as experimental while their functions are part of the 20 stable ABI (in .map files + no__rte_experimentalmarking). Their fate must be discussed.
Quoted 5 lines
I would suggest removing EXPERIMENTAL flag for gro, member and rawdev. They are probably already considered stable for a lot of users. Maintainers, are you OK to follow the ABI compatibility rules for these libraries? Do you feel these libraries are mature enough?
I think things being added to the official ABI is good. For these, I wonder if waiting till the 20.11 release is the best time to officially mark them as stable, rather than doing so now?
06/07/2020 10:02, Bruce Richardson:
Quoted 30 lines · Thomas Monjalon
Quoted 23 lines
+Cc maintainers of the problematic libraries:
-librte_fib
-librte_rib
-librte_gro
-librte_member
-librte_rawdev26/06/2020 10:16, David Marchand:
Quoted 7 lines
Following discussions on the mailing list and the 05/20 TB meeting, here is a series that drops the special versioning for non stable libraries.
Two notes:
- RIB/FIB library is not referenced in the API doxygen index, is this intentional?
Vladimir please, could you fix the miss in the doxygen index?
Quoted 4 lines
- I inspected
MAINTAINERS:librte_gro,librte_memberandlibrte_rawdevare announced as experimental while their functions are part of the 20 stable ABI (in .map files + no__rte_experimentalmarking). Their fate must be discussed.Quoted 5 lines
I would suggest removing EXPERIMENTAL flag for gro, member and rawdev. They are probably already considered stable for a lot of users. Maintainers, are you OK to follow the ABI compatibility rules for these libraries? Do you feel these libraries are mature enough?
Quoted 3 lines
I think things being added to the official ABI is good. For these, I wonder if waiting till the 20.11 release is the best time to officially mark them as stable, rather than doing so now?
They are already not marked as experimental symbols... I think we should remove confusion in the MAINTAINERS file.
Quoted 8 lines · Thomas Monjalon
+Cc maintainers of the problematic libraries:
-librte_fib
-librte_rib
-librte_gro
-librte_member
-librte_rawdev26/06/2020 10:16, David Marchand:
Quoted 8 lines
Quoted 7 lines
Following discussions on the mailing list and the 05/20 TB meeting, here is a series that drops the special versioning for non stable libraries.
Two notes:
- RIB/FIB library is not referenced in the API doxygen index, is this intentional?
Vladimir please, could you fix the miss in the doxygen index?
Sure, I'll send a patch.
Quoted 12 lines
Quoted 5 lines
- I inspected
MAINTAINERS:librte_gro,librte_memberandlibrte_rawdevare announced as experimental while their functions are part of the 20 stable ABI (in .map files + no__rte_experimentalmarking). Their fate must be discussed.I would suggest removing EXPERIMENTAL flag for gro, member and rawdev. They are probably already considered stable for a lot of users. Maintainers, are you OK to follow the ABI compatibility rules for these libraries? Do you feel these libraries are mature enough?
Signature · 2 lines
Regards, Vladimir