patch 'ethdev: clarify null location case in xstats get' has been queued to stable release 19.11.13

[christian.ehrhardt at canonical.com]

Hi,

FYI, your patch has been queued to stable release 19.11.13

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/09/22. 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.

Queued patches are on a temporary branch at:
https://github.com/cpaelzer/dpdk-stable-queue

This queued commit can be viewed at:
https://github.com/cpaelzer/dpdk-stable-queue/commit/530d754e63a4d9c5a5f9d55e8df57fca0c1e6d45

Thanks.

Christian Ehrhardt <christian.ehrhardt at canonical.com>

---
>From 530d754e63a4d9c5a5f9d55e8df57fca0c1e6d45 Mon Sep 17 00:00:00 2001
From: Chengwen Feng <fengchengwen at huawei.com>
Date: Fri, 13 May 2022 10:53:49 +0800
Subject: [PATCH] ethdev: clarify null location case in xstats get
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

[ upstream commit 485df8847a2c0ecf947a514f634b8180b725b827 ]

When xstats location is null in rte_eth_xstats_get() the return value
is not clearly specified.  Some PMDs (eg. hns3/ipn3ke/mvpp2/axgbe) return
zero while others return the required number of elements.

In this patch, special parameter combinations are restricted:
 1. highlight that xstats location may be null if and only if n is 0.
 2. amend n parameter description to specify that if n is lower than
    the required number of elements, the function returns the required
    number of elements.
 3. specify that if n is zero, the xstats must be NULL, the function
    returns the required number of elements (a duplicate which should
    help to not very attentive readers).

Add sanity check for null xstats and non-zero n case on API level to
make it unnecessary to care about it in drivers.

Fixes: ce757f5c9a4d ("ethdev: new method to retrieve extended statistics")

Signed-off-by: Chengwen Feng <fengchengwen at huawei.com>
Acked-by: Morten Brørup <mb at smartsharesystems.com>
Reviewed-by: Andrew Rybchenko <andrew.rybchenko at oktetlabs.ru>
---
 lib/librte_ethdev/rte_ethdev.c | 5 +++--
 lib/librte_ethdev/rte_ethdev.h | 6 +++++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/lib/librte_ethdev/rte_ethdev.c b/lib/librte_ethdev/rte_ethdev.c
index abcc31c19e..76699cc10f 100644
--- a/lib/librte_ethdev/rte_ethdev.c
+++ b/lib/librte_ethdev/rte_ethdev.c
@@ -2862,7 +2862,8 @@ rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
 	int ret;
 
 	RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -EINVAL);
-
+	if (xstats == NULL && n > 0)
+		return -EINVAL;
 	dev = &rte_eth_devices[port_id];
 
 	nb_rxqs = RTE_MIN(dev->data->nb_rx_queues, RTE_ETHDEV_QUEUE_STAT_CNTRS);
@@ -2878,7 +2879,7 @@ rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
 		 * xstats struct.
 		 */
 		xcount = (*dev->dev_ops->xstats_get)(dev,
-				     xstats ? xstats + count : NULL,
+				     (n > count) ? xstats + count : NULL,
 				     (n > count) ? n - count : 0);
 
 		if (xcount < 0)
diff --git a/lib/librte_ethdev/rte_ethdev.h b/lib/librte_ethdev/rte_ethdev.h
index 9cc12ef97e..826339009b 100644
--- a/lib/librte_ethdev/rte_ethdev.h
+++ b/lib/librte_ethdev/rte_ethdev.h
@@ -2363,9 +2363,13 @@ int rte_eth_xstats_get_names(uint16_t port_id,
  * @param xstats
  *   A pointer to a table of structure of type *rte_eth_xstat*
  *   to be filled with device statistics ids and values.
- *   This parameter can be set to NULL if n is 0.
+ *   This parameter can be set to NULL if and only if n is 0.
  * @param n
  *   The size of the xstats array (number of elements).
+ *   If lower than the required number of elements, the function returns
+ *   the required number of elements.
+ *   If equal to zero, the xstats must be NULL, the function returns the
+ *   required number of elements.
  * @return
  *   - A positive value lower or equal to n: success. The return value
  *     is the number of entries filled in the stats table.
-- 
2.37.0

---
  Diff of the applied patch vs upstream commit (please double-check if non-empty:
---
--- -	2022-07-07 09:54:12.654871176 +0200
+++ 0034-ethdev-clarify-null-location-case-in-xstats-get.patch	2022-07-07 09:54:10.873824049 +0200
@@ -1 +1 @@
-From 485df8847a2c0ecf947a514f634b8180b725b827 Mon Sep 17 00:00:00 2001
+From 530d754e63a4d9c5a5f9d55e8df57fca0c1e6d45 Mon Sep 17 00:00:00 2001
@@ -8,0 +9,2 @@
+[ upstream commit 485df8847a2c0ecf947a514f634b8180b725b827 ]
+
@@ -26 +27,0 @@
-Cc: stable at dpdk.org
@@ -32,9 +33,9 @@
- lib/ethdev/rte_ethdev.c | 4 +++-
- lib/ethdev/rte_ethdev.h | 6 +++++-
- 2 files changed, 8 insertions(+), 2 deletions(-)
-
-diff --git a/lib/ethdev/rte_ethdev.c b/lib/ethdev/rte_ethdev.c
-index 8520aec561..af55edb6b9 100644
---- a/lib/ethdev/rte_ethdev.c
-+++ b/lib/ethdev/rte_ethdev.c
-@@ -2973,6 +2973,8 @@ rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
+ lib/librte_ethdev/rte_ethdev.c | 5 +++--
+ lib/librte_ethdev/rte_ethdev.h | 6 +++++-
+ 2 files changed, 8 insertions(+), 3 deletions(-)
+
+diff --git a/lib/librte_ethdev/rte_ethdev.c b/lib/librte_ethdev/rte_ethdev.c
+index abcc31c19e..76699cc10f 100644
+--- a/lib/librte_ethdev/rte_ethdev.c
++++ b/lib/librte_ethdev/rte_ethdev.c
+@@ -2862,7 +2862,8 @@ rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
@@ -43 +44,2 @@
- 	RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV);
+ 	RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -EINVAL);
+-
@@ -49 +51 @@
-@@ -2989,7 +2991,7 @@ rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
+@@ -2878,7 +2879,7 @@ rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
@@ -58,5 +60,5 @@
-diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
-index 04cff8ee10..04225bba4d 100644
---- a/lib/ethdev/rte_ethdev.h
-+++ b/lib/ethdev/rte_ethdev.h
-@@ -3174,9 +3174,13 @@ int rte_eth_xstats_get_names(uint16_t port_id,
+diff --git a/lib/librte_ethdev/rte_ethdev.h b/lib/librte_ethdev/rte_ethdev.h
+index 9cc12ef97e..826339009b 100644
+--- a/lib/librte_ethdev/rte_ethdev.h
++++ b/lib/librte_ethdev/rte_ethdev.h
+@@ -2363,9 +2363,13 @@ int rte_eth_xstats_get_names(uint16_t port_id,