[dpdk-stable] patch 'lib: remind experimental status in headers' has been queued to stable release 19.11.4
luca.boccassi at gmail.com
luca.boccassi at gmail.com
Fri Jul 24 13:58:37 CEST 2020
Hi,
FYI, your patch has been queued to stable release 19.11.4
Note it hasn't been pushed to http://dpdk.org/browse/dpdk-stable yet.
It will be pushed if I get no objections before 07/26/20. So please
shout if anyone has objections.
Also note that after the patch there's a diff of the upstream commit vs the
patch applied to the branch. This will indicate if there was any rebasing
needed to apply to the stable branch. If there were code changes for rebasing
(ie: not only metadata diffs), please double check that the rebase was
correctly done.
Thanks.
Luca Boccassi
---
>From e2acbb7f711e0080871bf935b36c28d481411c7d Mon Sep 17 00:00:00 2001
From: David Marchand <david.marchand at redhat.com>
Date: Fri, 26 Jun 2020 10:16:38 +0200
Subject: [PATCH] lib: remind experimental status in headers
[ upstream commit 74f4d6424da1297bd6e83dcb7bd84444ca8c59dd ]
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).
Signed-off-by: David Marchand <david.marchand at redhat.com>
Acked-by: Bruce Richardson <bruce.richardson at intel.com>
---
doc/guides/contributing/abi_policy.rst | 12 +++++-------
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 | 7 ++++++-
13 files changed, 71 insertions(+), 17 deletions(-)
diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 2198519d9..87942c8ac 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -27,8 +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.
- Experimental libraries have the major ABI version ``0``.
+ 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.
@@ -289,7 +289,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
@@ -320,7 +320,5 @@ 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.
+All functions in such libraries may be changed or removed without prior notice.
diff --git a/lib/librte_bbdev/rte_bbdev.h b/lib/librte_bbdev/rte_bbdev.h
index 1f58a0762..6fcf44826 100644
--- a/lib/librte_bbdev/rte_bbdev.h
+++ b/lib/librte_bbdev/rte_bbdev.h
@@ -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)
diff --git a/lib/librte_bpf/rte_bpf.h b/lib/librte_bpf/rte_bpf.h
index cbf1cddac..e2d419b4e 100644
--- a/lib/librte_bpf/rte_bpf.h
+++ b/lib/librte_bpf/rte_bpf.h
@@ -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
diff --git a/lib/librte_compressdev/rte_compressdev.h b/lib/librte_compressdev/rte_compressdev.h
index 8052efe67..2840c27c6 100644
--- a/lib/librte_compressdev/rte_compressdev.h
+++ b/lib/librte_compressdev/rte_compressdev.h
@@ -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.
*/
diff --git a/lib/librte_fib/rte_fib.h b/lib/librte_fib/rte_fib.h
index af3bbf07e..84ee774d2 100644
--- a/lib/librte_fib/rte_fib.h
+++ b/lib/librte_fib/rte_fib.h
@@ -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
*/
diff --git a/lib/librte_fib/rte_fib6.h b/lib/librte_fib/rte_fib6.h
index 66c71c84c..bbfcf23a8 100644
--- a/lib/librte_fib/rte_fib6.h
+++ b/lib/librte_fib/rte_fib6.h
@@ -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
*/
diff --git a/lib/librte_flow_classify/rte_flow_classify.h b/lib/librte_flow_classify/rte_flow_classify.h
index 74d1ecaf5..82ea92b6a 100644
--- a/lib/librte_flow_classify/rte_flow_classify.h
+++ b/lib/librte_flow_classify/rte_flow_classify.h
@@ -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.
*
diff --git a/lib/librte_ipsec/rte_ipsec.h b/lib/librte_ipsec/rte_ipsec.h
index f3b1f936b..f2da7ace9 100644
--- a/lib/librte_ipsec/rte_ipsec.h
+++ b/lib/librte_ipsec/rte_ipsec.h
@@ -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).
*/
diff --git a/lib/librte_rcu/rte_rcu_qsbr.h b/lib/librte_rcu/rte_rcu_qsbr.h
index 0b5585925..078de261f 100644
--- a/lib/librte_rcu/rte_rcu_qsbr.h
+++ b/lib/librte_rcu/rte_rcu_qsbr.h
@@ -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
diff --git a/lib/librte_rib/rte_rib.h b/lib/librte_rib/rte_rib.h
index 6b70de980..da558c417 100644
--- a/lib/librte_rib/rte_rib.h
+++ b/lib/librte_rib/rte_rib.h
@@ -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
*/
diff --git a/lib/librte_rib/rte_rib6.h b/lib/librte_rib/rte_rib6.h
index 871457138..4b284c913 100644
--- a/lib/librte_rib/rte_rib6.h
+++ b/lib/librte_rib/rte_rib6.h
@@ -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
*/
diff --git a/lib/librte_stack/rte_stack.h b/lib/librte_stack/rte_stack.h
index 27ddb199e..abf642076 100644
--- a/lib/librte_stack/rte_stack.h
+++ b/lib/librte_stack/rte_stack.h
@@ -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,
diff --git a/lib/librte_telemetry/rte_telemetry.h b/lib/librte_telemetry/rte_telemetry.h
index aedb31859..f1376ea35 100644
--- a/lib/librte_telemetry/rte_telemetry.h
+++ b/lib/librte_telemetry/rte_telemetry.h
@@ -9,7 +9,12 @@
/**
* @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 JSON encoded message over a socket. DPDK will send
--
2.20.1
---
Diff of the applied patch vs upstream commit (please double-check if non-empty:
---
--- - 2020-07-24 12:53:51.608482723 +0100
+++ 0079-lib-remind-experimental-status-in-headers.patch 2020-07-24 12:53:48.307006832 +0100
@@ -1,8 +1,10 @@
-From 74f4d6424da1297bd6e83dcb7bd84444ca8c59dd Mon Sep 17 00:00:00 2001
+From e2acbb7f711e0080871bf935b36c28d481411c7d Mon Sep 17 00:00:00 2001
From: David Marchand <david.marchand at redhat.com>
Date: Fri, 26 Jun 2020 10:16:38 +0200
Subject: [PATCH] lib: remind experimental status in headers
+[ upstream commit 74f4d6424da1297bd6e83dcb7bd84444ca8c59dd ]
+
The following libraries are experimental, all of their functions can
be changed or removed:
@@ -23,45 +25,40 @@
Remind this status in their headers in a common fashion (aligned to ABI
docs).
-Cc: stable at dpdk.org
-
Signed-off-by: David Marchand <david.marchand at redhat.com>
Acked-by: Bruce Richardson <bruce.richardson at intel.com>
---
- doc/guides/contributing/abi_policy.rst | 8 +++++---
+ doc/guides/contributing/abi_policy.rst | 12 +++++-------
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(-)
+ lib/librte_telemetry/rte_telemetry.h | 7 ++++++-
+ 13 files changed, 71 insertions(+), 17 deletions(-)
diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
-index 1b2fa2786..d0affa9e6 100644
+index 2198519d9..87942c8ac 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
-@@ -27,7 +27,8 @@ General Guidelines
+@@ -27,8 +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.
+- Experimental libraries have the major ABI version ``0``.
+ 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
+@@ -289,7 +289,7 @@ APIs
~~~~
APIs marked as ``experimental`` are not considered part of an ABI version and
@@ -70,15 +67,18 @@
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
+@@ -320,7 +320,5 @@ Libraries
~~~~~~~~~
Libraries marked as ``experimental`` are entirely not considered part of an ABI
--version, and may change without warning at any time.
+-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.
+All functions in such libraries may be changed or removed without prior notice.
diff --git a/lib/librte_bbdev/rte_bbdev.h b/lib/librte_bbdev/rte_bbdev.h
-index ecd95a823..57291373f 100644
+index 1f58a0762..6fcf44826 100644
--- a/lib/librte_bbdev/rte_bbdev.h
+++ b/lib/librte_bbdev/rte_bbdev.h
@@ -11,7 +11,8 @@
@@ -181,36 +181,8 @@
*
* This library provides flow record information with some measured properties.
*
-diff --git a/lib/librte_graph/rte_graph.h b/lib/librte_graph/rte_graph.h
-index 9a26ffc18..b32c4bc21 100644
---- a/lib/librte_graph/rte_graph.h
-+++ b/lib/librte_graph/rte_graph.h
-@@ -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
-diff --git a/lib/librte_graph/rte_graph_worker.h b/lib/librte_graph/rte_graph_worker.h
-index 4c3ddcbde..eef77f732 100644
---- a/lib/librte_graph/rte_graph_worker.h
-+++ b/lib/librte_graph/rte_graph_worker.h
-@@ -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.
diff --git a/lib/librte_ipsec/rte_ipsec.h b/lib/librte_ipsec/rte_ipsec.h
-index 6666cf761..de05f4e93 100644
+index f3b1f936b..f2da7ace9 100644
--- a/lib/librte_ipsec/rte_ipsec.h
+++ b/lib/librte_ipsec/rte_ipsec.h
@@ -7,9 +7,13 @@
@@ -228,36 +200,8 @@
* librte_ipsec provides a framework for data-path IPsec protocol
* processing (ESP/AH).
*/
-diff --git a/lib/librte_node/rte_node_eth_api.h b/lib/librte_node/rte_node_eth_api.h
-index e9a53afe5..4e28f86d7 100644
---- a/lib/librte_node/rte_node_eth_api.h
-+++ b/lib/librte_node/rte_node_eth_api.h
-@@ -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.
-diff --git a/lib/librte_node/rte_node_ip4_api.h b/lib/librte_node/rte_node_ip4_api.h
-index 31a752b00..eb9ebd5f8 100644
---- a/lib/librte_node/rte_node_ip4_api.h
-+++ b/lib/librte_node/rte_node_ip4_api.h
-@@ -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.
diff --git a/lib/librte_rcu/rte_rcu_qsbr.h b/lib/librte_rcu/rte_rcu_qsbr.h
-index fd4eb52b7..a98e8f0f8 100644
+index 0b5585925..078de261f 100644
--- a/lib/librte_rcu/rte_rcu_qsbr.h
+++ b/lib/librte_rcu/rte_rcu_qsbr.h
@@ -7,7 +7,12 @@
@@ -330,16 +274,12 @@
* 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,
diff --git a/lib/librte_telemetry/rte_telemetry.h b/lib/librte_telemetry/rte_telemetry.h
-index eb7f2c917..d13010b8f 100644
+index aedb31859..f1376ea35 100644
--- a/lib/librte_telemetry/rte_telemetry.h
+++ b/lib/librte_telemetry/rte_telemetry.h
-@@ -20,11 +20,13 @@
- #define RTE_TEL_MAX_ARRAY_ENTRIES 512
+@@ -9,7 +9,12 @@
/**
-- * @warning
-- * @b EXPERIMENTAL: all functions in this file may change without prior notice
-- *
* @file
- * RTE Telemetry
+ *
@@ -350,7 +290,7 @@
+ * 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
+ * DPDK by sending a JSON encoded message over a socket. DPDK will send
--
2.20.1
More information about the stable
mailing list