[dpdk-stable] patch 'ethdev: fix xstats by ID API documentation' has been queued to stable release 20.11.4

[Xueming Li]

Hi,

FYI, your patch has been queued to stable release 20.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 11/12/21. 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/steevenlee/dpdk

This queued commit can be viewed at:
https://github.com/steevenlee/dpdk/commit/8f825b3b132ba3f0f0a30ff8e6c135af3495320a

Thanks.

Xueming Li <xuemingl at nvidia.com>

---
>From 8f825b3b132ba3f0f0a30ff8e6c135af3495320a Mon Sep 17 00:00:00 2001
From: Ivan Ilchenko <ivan.ilchenko at oktetlabs.ru>
Date: Fri, 1 Oct 2021 12:07:19 +0300
Subject: [PATCH] ethdev: fix xstats by ID API documentation
Cc: Xueming Li <xuemingl at nvidia.com>

[ upstream commit bc5112ca599c1e565c0f2d3dc3de0f73381a8c05 ]

Document valid combinations of input arguments in accordance with
current implementation in ethdev.

Fixes: 79c913a42f0e ("ethdev: retrieve xstats by ID")

Signed-off-by: Ivan Ilchenko <ivan.ilchenko at oktetlabs.ru>
Signed-off-by: Andrew Rybchenko <andrew.rybchenko at oktetlabs.ru>
Reviewed-by: Andy Moreton <amoreton at xilinx.com>
Reviewed-by: Ferruh Yigit <ferruh.yigit at intel.com>
---
 lib/librte_ethdev/rte_ethdev.h | 35 ++++++++++++++++++----------------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/lib/librte_ethdev/rte_ethdev.h b/lib/librte_ethdev/rte_ethdev.h
index de577ca075..57a2edf363 100644
--- a/lib/librte_ethdev/rte_ethdev.h
+++ b/lib/librte_ethdev/rte_ethdev.h
@@ -2835,21 +2835,23 @@ int rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
  * @param port_id
  *   The port identifier of the Ethernet device.
  * @param xstats_names
- *   An rte_eth_xstat_name array of at least *size* elements to
- *   be filled. If set to NULL, the function returns the required number
- *   of elements.
- * @param ids
- *   IDs array given by app to retrieve specific statistics
+ *   Array to be filled in with names of requested device statistics.
+ *   Must not be NULL if @p ids are specified (not NULL).
  * @param size
- *   The size of the xstats_names array (number of elements).
+ *   Number of elements in @p xstats_names array (if not NULL) and in
+ *   @p ids array (if not NULL). Must be 0 if both array pointers are NULL.
+ * @param ids
+ *   IDs array given by app to retrieve specific statistics. May be NULL to
+ *   retrieve names of all available statistics or, if @p xstats_names is
+ *   NULL as well, just the number of available statistics.
  * @return
  *   - A positive value lower or equal to size: success. The return value
  *     is the number of entries filled in the stats table.
- *   - A positive value higher than size: error, the given statistics table
+ *   - A positive value higher than size: success. The given statistics table
  *     is too small. The return value corresponds to the size that should
  *     be given to succeed. The entries in the table are not valid and
  *     shall not be used by the caller.
- *   - A negative value on error (invalid port id).
+ *   - A negative value on error.
  */
 int
 rte_eth_xstats_get_names_by_id(uint16_t port_id,
@@ -2862,22 +2864,23 @@ rte_eth_xstats_get_names_by_id(uint16_t port_id,
  * @param port_id
  *   The port identifier of the Ethernet device.
  * @param ids
- *   A pointer to an ids array passed by application. This tells which
- *   statistics values function should retrieve. This parameter
- *   can be set to NULL if size is 0. In this case function will retrieve
- *   all available statistics.
+ *   IDs array given by app to retrieve specific statistics. May be NULL to
+ *   retrieve all available statistics or, if @p values is NULL as well,
+ *   just the number of available statistics.
  * @param values
- *   A pointer to a table to be filled with device statistics values.
+ *   Array to be filled in with requested device statistics.
+ *   Must not be NULL if ids are specified (not NULL).
  * @param size
- *   The size of the ids array (number of elements).
+ *   Number of elements in @p values array (if not NULL) and in @p ids
+ *   array (if not NULL). Must be 0 if both array pointers are NULL.
  * @return
  *   - A positive value lower or equal to size: success. The return value
  *     is the number of entries filled in the stats table.
- *   - A positive value higher than size: error, the given statistics table
+ *   - A positive value higher than size: success: The given statistics table
  *     is too small. The return value corresponds to the size that should
  *     be given to succeed. The entries in the table are not valid and
  *     shall not be used by the caller.
- *   - A negative value on error (invalid port id).
+ *   - A negative value on error.
  */
 int rte_eth_xstats_get_by_id(uint16_t port_id, const uint64_t *ids,
 			     uint64_t *values, unsigned int size);
-- 
2.33.0

---
  Diff of the applied patch vs upstream commit (please double-check if non-empty:
---
--- -	2021-11-10 14:17:06.696319804 +0800
+++ 0106-ethdev-fix-xstats-by-ID-API-documentation.patch	2021-11-10 14:17:01.867412785 +0800
@@ -1 +1 @@
-From bc5112ca599c1e565c0f2d3dc3de0f73381a8c05 Mon Sep 17 00:00:00 2001
+From 8f825b3b132ba3f0f0a30ff8e6c135af3495320a Mon Sep 17 00:00:00 2001
@@ -4,0 +5,3 @@
+Cc: Xueming Li <xuemingl at nvidia.com>
+
+[ upstream commit bc5112ca599c1e565c0f2d3dc3de0f73381a8c05 ]
@@ -10 +12,0 @@
-Cc: stable at dpdk.org
@@ -17 +19 @@
- lib/ethdev/rte_ethdev.h | 35 +++++++++++++++++++----------------
+ lib/librte_ethdev/rte_ethdev.h | 35 ++++++++++++++++++----------------
@@ -20,5 +22,5 @@
-diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
-index afdc53b674..2ad2bf2019 100644
---- a/lib/ethdev/rte_ethdev.h
-+++ b/lib/ethdev/rte_ethdev.h
-@@ -2896,21 +2896,23 @@ int rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
+diff --git a/lib/librte_ethdev/rte_ethdev.h b/lib/librte_ethdev/rte_ethdev.h
+index de577ca075..57a2edf363 100644
+--- a/lib/librte_ethdev/rte_ethdev.h
++++ b/lib/librte_ethdev/rte_ethdev.h
+@@ -2835,21 +2835,23 @@ int rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
@@ -56 +58 @@
-@@ -2923,22 +2925,23 @@ rte_eth_xstats_get_names_by_id(uint16_t port_id,
+@@ -2862,22 +2864,23 @@ rte_eth_xstats_get_names_by_id(uint16_t port_id,