Skip to contentSkip to conversation

Experimental/internal libraries cleanup

PATCH Superseded David Marchand 7 participants 25 messages May 22, 2020 – Jul 7, 2020

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index d5f8291beb..79703b6f93 100644
@@ -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
index 43ab113106..35975f1030 100644
@@ -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
index dd9120e69e..e17fedbd9f 100755
@@ -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
index becbf842a5..02b290b08f 100644
@@ -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
index cfb6a833c9..4e5713bb27 100644
@@ -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
index d190d84eff..13b330396c 100644
@@ -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
index 682b590dba..229ae16814 100644
@@ -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
#2 lore raw

PATCH 2/3 drivers: drop workaround for internal libraries

In reply to David Marchand

Now 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
index 46d42f7d64..491c507119 100644
@@ -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
index 69e7dc6ad9..0a9947a454 100644
@@ -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
index 49c775c072..ee1ca6801c 100644
@@ -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
index d26bd71172..9a9969613b 100644
@@ -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
index 3d863aff4d..1352f576e5 100644
@@ -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
index 023e120516..731ea593ad 100644
@@ -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
index 89d7cf4957..142547ee38 100644
@@ -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
index 8691efdfd8..e6887ceb8f 100644
@@ -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
index b633fdc2a8..c3a457d2b9 100644
@@ -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
#3 lore raw

PATCH 3/3 lib: remind experimental status in library headers

In reply to David Marchand

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_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
index ecd95a823d..ab4e1bd6f4 100644
@@ -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
index cbf1cddaca..ceb3e26b03 100644
@@ -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
index 8052efe675..9c873b347d 100644
@@ -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
index af3bbf07ee..b52d058406 100644
@@ -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
index 66c71c84c9..e6e8892ecb 100644
@@ -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
index 74d1ecaf50..ac5b08aa6d 100644
@@ -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
index 6666cf7619..50f109553c 100644
@@ -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
index fd4eb52b7f..891f64725e 100644
@@ -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
index 6b70de980a..729177870f 100644
@@ -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
index 871457138d..cbdb3fe5c2 100644
@@ -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
index 27ddb199e5..7ac0b49eb6 100644
@@ -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
index 2c3c96cf73..f42457911f 100644
@@ -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
#4 lore raw

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_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 index renamed from lib/librte_bbdev/rte_bbdev.h +0 -0

ecd95a823d..ab4e1bd6f4 100644

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.h b/lib/librte_bpf/rte_bpf.h index cbf1cddaca..ceb3e26b03 100644

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 diff --git

a/lib/librte_compressdev/rte_compressdev.h
b/lib/librte_compressdev/rte_compressdev.h
index 8052efe675..9c873b347d 100644

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 index renamed from lib/librte_fib/rte_fib.h +0 -0

af3bbf07ee..b52d058406 100644

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 index renamed from lib/librte_fib/rte_fib6.h +0 -0

66c71c84c9..e6e8892ecb 100644

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
index 74d1ecaf50..ac5b08aa6d 100644
@@ -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..50f109553c 100644

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 index renamed from lib/librte_rcu/rte_rcu_qsbr.h +0 -0

fd4eb52b7f..891f64725e 100644

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 diff --git

a/lib/librte_rib/rte_rib.h b/lib/librte_rib/rte_rib.h index 6b70de980a..729177870f 100644

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 index renamed from lib/librte_rib/rte_rib6.h +0 -0

871457138d..cbdb3fe5c2 100644

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 index renamed from lib/librte_stack/rte_stack.h +0 -0

27ddb199e5..7ac0b49eb6 100644

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 +0 -2
index 2c3c96cf73..f42457911f 100644
@@ -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

#5 lore raw

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
#6 lore raw

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

#7 lore raw

Re: [dpdk-dev] [PATCH 3/3] lib: remind experimental status in library headers

In reply to David Marchand
Quoted 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 headers

The 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

#8 lore raw

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
#9 lore raw

v2 cover Experimental/internal libraries cleanup

In reply to 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 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
#10 lore raw

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
index d5f8291beb..79703b6f93 100644
@@ -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
index 351e268c1f..d6d3f5271d 100644
@@ -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
index dd9120e69e..e17fedbd9f 100755
@@ -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
index becbf842a5..97899b926e 100644
@@ -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
index ee17ccb200..1b2fa27865 100644
@@ -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
index e96fde340f..31a9205572 100644
@@ -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
index cfb6a833c9..d1b59a4bac 100644
@@ -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
index d190d84eff..d646f33e07 100644
@@ -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
index 682b590dba..229ae16814 100644
@@ -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
#11 lore raw

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 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).

I have missed the new experimental libraries from 20.05. Expect a v3 later today.

Signature · 1 line
David Marchand
#12 lore raw

PATCH v2 2/3 drivers: drop workaround for internal libraries

In reply to David Marchand

Now 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
index 46d42f7d64..491c507119 100644
@@ -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
index 69e7dc6ad9..0a9947a454 100644
@@ -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
index 49c775c072..ee1ca6801c 100644
@@ -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
index d26bd71172..9a9969613b 100644
@@ -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
index 3d863aff4d..1352f576e5 100644
@@ -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
index 023e120516..731ea593ad 100644
@@ -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
index 89d7cf4957..142547ee38 100644
@@ -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
index 8691efdfd8..e6887ceb8f 100644
@@ -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
index b633fdc2a8..c3a457d2b9 100644
@@ -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
#13 lore raw

PATCH v2 3/3 lib: remind experimental status in library headers

In reply to David Marchand

The 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
index 1b2fa27865..d0affa9e60 100644
@@ -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
index ecd95a823d..57291373fa 100644
@@ -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
index cbf1cddaca..e2d419b4ef 100644
@@ -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
index 8052efe675..2840c27c6c 100644
@@ -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
index af3bbf07ee..84ee774d2d 100644
@@ -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
index 66c71c84c9..bbfcf23a85 100644
@@ -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
index 74d1ecaf50..82ea92b6a6 100644
@@ -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
index 6666cf7619..de05f4e932 100644
@@ -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
index fd4eb52b7f..a98e8f0f82 100644
@@ -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
index 6b70de980a..da558c417e 100644
@@ -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
index 871457138d..4b284c913c 100644
@@ -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
index 27ddb199e5..abf6420766 100644
@@ -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
index eb7f2c917c..d13010b8fb 100644
@@ -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
#14 lore raw

v3 cover Experimental/internal libraries cleanup

In reply to 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 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
#15 lore raw

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
index d5f8291beb..79703b6f93 100644
@@ -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
index 351e268c1f..d6d3f5271d 100644
@@ -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
index dd9120e69e..e17fedbd9f 100755
@@ -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
index becbf842a5..0133f757d0 100644
@@ -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
index ee17ccb200..1b2fa27865 100644
@@ -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
index e96fde340f..31a9205572 100644
@@ -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
index cfb6a833c9..d1b59a4bac 100644
@@ -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
index d190d84eff..d646f33e07 100644
@@ -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
index 682b590dba..229ae16814 100644
@@ -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
Acked-by on v3 1/3
#16 lore raw

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 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
index d5f8291beb..79703b6f93 100644
@@ -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
index 351e268c1f..d6d3f5271d 100644
@@ -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
index dd9120e69e..e17fedbd9f 100755
@@ -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
index becbf842a5..0133f757d0 100644
@@ -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
index ee17ccb200..1b2fa27865 100644
@@ -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
index e96fde340f..31a9205572 100644

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 -0
 Minor ABI versions
 ~~~~~~~~~~~~~~~~~~
drivers/meson.build +1 -16
index cfb6a833c9..d1b59a4bac 100644
@@ -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
index d190d84eff..d646f33e07 100644
@@ -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
index 682b590dba..229ae16814 100644
@@ -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))
#17 lore raw

PATCH v3 2/3 drivers: drop workaround for internal libraries

In reply to David Marchand

Now 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
index 46d42f7d64..491c507119 100644
@@ -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
index 69e7dc6ad9..0a9947a454 100644
@@ -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
index 49c775c072..ee1ca6801c 100644
@@ -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
index d26bd71172..9a9969613b 100644
@@ -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
index 3d863aff4d..1352f576e5 100644
@@ -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
index 023e120516..731ea593ad 100644
@@ -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
index 89d7cf4957..142547ee38 100644
@@ -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
index 8691efdfd8..e6887ceb8f 100644
@@ -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
index b633fdc2a8..c3a457d2b9 100644
@@ -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
#18 lore raw

PATCH v3 3/3 lib: remind experimental status in library headers

In reply to David Marchand

The 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
index 1b2fa27865..d0affa9e60 100644
@@ -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
index ecd95a823d..57291373fa 100644
@@ -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
index cbf1cddaca..e2d419b4ef 100644
@@ -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
index 8052efe675..2840c27c6c 100644
@@ -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
index af3bbf07ee..84ee774d2d 100644
@@ -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
index 66c71c84c9..bbfcf23a85 100644
@@ -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
index 74d1ecaf50..82ea92b6a6 100644
@@ -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
index 9a26ffc185..b32c4bc217 100644
@@ -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
index 4c3ddcbdeb..eef77f732a 100644
@@ -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
index 6666cf7619..de05f4e932 100644
@@ -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
index e9a53afe5d..4e28f86d77 100644
@@ -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
index 31a752b00b..eb9ebd5f89 100644
@@ -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
index fd4eb52b7f..a98e8f0f82 100644
@@ -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
index 6b70de980a..da558c417e 100644
@@ -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
index 871457138d..4b284c913c 100644
@@ -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
index 27ddb199e5..abf6420766 100644
@@ -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
index eb7f2c917c..d13010b8fb 100644
@@ -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
#19 lore raw
In reply to David Marchand
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 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.

Quoted 18 lines

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 · 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.

#20 lore raw

26/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.

Applied, thanks

#21 lore raw
In reply to David Marchand

+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_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.

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?

#22 lore raw
Quoted 23 lines · Thomas Monjalon

+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_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.

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?

#23 lore raw

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_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_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.

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.

#24 lore raw
In reply to Thomas Monjalon
Quoted 8 lines · Thomas Monjalon

+Cc maintainers of the problematic libraries:
- librte_fib
- librte_rib
- librte_gro
- librte_member
- librte_rawdev

26/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_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.

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