[dpdk-stable] patch 'distributor: fix API documentation' has been queued to stable release 19.11.6

[luca.boccassi at gmail.com]

Hi,

FYI, your patch has been queued to stable release 19.11.6

Note it hasn't been pushed to http://dpdk.org/browse/dpdk-stable yet.
It will be pushed if I get no objections before 10/30/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 7c3f944d2fec17fad74d96e36fa93dcd6d0aad84 Mon Sep 17 00:00:00 2001
From: Lukasz Wojciechowski <l.wojciechow at partner.samsung.com>
Date: Sat, 17 Oct 2020 05:06:54 +0200
Subject: [PATCH] distributor: fix API documentation

[ upstream commit ed4be82d9e645c86ccd16938bdb200cdecaa2906 ]

After introducing burst API there were some artefacts in the
API documentation from legacy single API.
Also the rte_distributor_poll_pkt() function return values
mismatched the implementation.

Fixes: c0de0eb82e40 ("distributor: switch over to new API")

Signed-off-by: Lukasz Wojciechowski <l.wojciechow at partner.samsung.com>
Acked-by: David Hunt <david.hunt at intel.com>
---
 lib/librte_distributor/rte_distributor.h | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/lib/librte_distributor/rte_distributor.h b/lib/librte_distributor/rte_distributor.h
index 327c0c4ab2..a073e64612 100644
--- a/lib/librte_distributor/rte_distributor.h
+++ b/lib/librte_distributor/rte_distributor.h
@@ -155,7 +155,7 @@ rte_distributor_clear_returns(struct rte_distributor *d);
  * @param pkts
  *   The mbufs pointer array to be filled in (up to 8 packets)
  * @param oldpkt
- *   The previous packet, if any, being processed by the worker
+ *   The previous packets, if any, being processed by the worker
  * @param retcount
  *   The number of packets being returned
  *
@@ -187,15 +187,15 @@ rte_distributor_return_pkt(struct rte_distributor *d,
 
 /**
  * API called by a worker to request a new packet to process.
- * Any previous packet given to the worker is assumed to have completed
+ * Any previous packets given to the worker are assumed to have completed
  * processing, and may be optionally returned to the distributor via
  * the oldpkt parameter.
- * Unlike rte_distributor_get_pkt_burst(), this function does not wait for a
- * new packet to be provided by the distributor.
+ * Unlike rte_distributor_get_pkt(), this function does not wait for
+ * new packets to be provided by the distributor.
  *
- * NOTE: after calling this function, rte_distributor_poll_pkt_burst() should
- * be used to poll for the packet requested. The rte_distributor_get_pkt_burst()
- * API should *not* be used to try and retrieve the new packet.
+ * NOTE: after calling this function, rte_distributor_poll_pkt() should
+ * be used to poll for the packets requested. The rte_distributor_get_pkt()
+ * API should *not* be used to try and retrieve the new packets.
  *
  * @param d
  *   The distributor instance to be used
@@ -213,9 +213,9 @@ rte_distributor_request_pkt(struct rte_distributor *d,
 		unsigned int count);
 
 /**
- * API called by a worker to check for a new packet that was previously
+ * API called by a worker to check for new packets that were previously
  * requested by a call to rte_distributor_request_pkt(). It does not wait
- * for the new packet to be available, but returns NULL if the request has
+ * for the new packets to be available, but returns if the request has
  * not yet been fulfilled by the distributor.
  *
  * @param d
@@ -227,8 +227,9 @@ rte_distributor_request_pkt(struct rte_distributor *d,
  *   The array of mbufs being given to the worker
  *
  * @return
- *   The number of packets being given to the worker thread, zero if no
- *   packet is yet available.
+ *   The number of packets being given to the worker thread,
+ *   -1 if no packets are yet available (burst API - RTE_DIST_ALG_BURST)
+ *   0 if no packets are yet available (legacy single API - RTE_DIST_ALG_SINGLE)
  */
 int
 rte_distributor_poll_pkt(struct rte_distributor *d,
-- 
2.20.1

---
  Diff of the applied patch vs upstream commit (please double-check if non-empty:
---
--- -	2020-10-28 10:35:17.626301998 +0000
+++ 0191-distributor-fix-API-documentation.patch	2020-10-28 10:35:11.800834381 +0000
@@ -1,15 +1,16 @@
-From ed4be82d9e645c86ccd16938bdb200cdecaa2906 Mon Sep 17 00:00:00 2001
+From 7c3f944d2fec17fad74d96e36fa93dcd6d0aad84 Mon Sep 17 00:00:00 2001
 From: Lukasz Wojciechowski <l.wojciechow at partner.samsung.com>
 Date: Sat, 17 Oct 2020 05:06:54 +0200
 Subject: [PATCH] distributor: fix API documentation
 
+[ upstream commit ed4be82d9e645c86ccd16938bdb200cdecaa2906 ]
+
 After introducing burst API there were some artefacts in the
 API documentation from legacy single API.
 Also the rte_distributor_poll_pkt() function return values
 mismatched the implementation.
 
 Fixes: c0de0eb82e40 ("distributor: switch over to new API")
-Cc: stable at dpdk.org
 
 Signed-off-by: Lukasz Wojciechowski <l.wojciechow at partner.samsung.com>
 Acked-by: David Hunt <david.hunt at intel.com>