From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from dpdk.org (dpdk.org [92.243.14.124])
	by inbox.dpdk.org (Postfix) with ESMTP id DAD3AA04BC;
	Thu,  8 Oct 2020 07:27:40 +0200 (CEST)
Received: from [92.243.14.124] (localhost [127.0.0.1])
	by dpdk.org (Postfix) with ESMTP id 01C881BAF5;
	Thu,  8 Oct 2020 07:24:05 +0200 (CEST)
Received: from mailout2.w1.samsung.com (mailout2.w1.samsung.com
 [210.118.77.12]) by dpdk.org (Postfix) with ESMTP id 52E291B6F6
 for <dev@dpdk.org>; Thu,  8 Oct 2020 07:23:45 +0200 (CEST)
Received: from eucas1p2.samsung.com (unknown [182.198.249.207])
 by mailout2.w1.samsung.com (KnoxPortal) with ESMTP id
 20201008052345euoutp02c5c867e0c6275f3f4a984211020380fe~77PP_VZth0628306283euoutp02I
 for <dev@dpdk.org>; Thu,  8 Oct 2020 05:23:45 +0000 (GMT)
DKIM-Filter: OpenDKIM Filter v2.11.0 mailout2.w1.samsung.com
 20201008052345euoutp02c5c867e0c6275f3f4a984211020380fe~77PP_VZth0628306283euoutp02I
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=samsung.com;
 s=mail20170921; t=1602134625;
 bh=dU7rWktTPIfjQZ7fCAIykFYYMgwWcdJlLIM6bxgVZkM=;
 h=From:To:Cc:Subject:Date:In-Reply-To:References:From;
 b=JtoXj9v+Ei9hWUNKUWZnKke7DBqRVUx49m0NTRzOs47R/dfstEW/8E2WNF+KnJC7k
 rHj+JfW0n9KbfEFO81xUxHrD0Zol/CLt8zvdexkK1Ib/hHhxLZv1OfWTLoqBQ09Skq
 BqLfOUZPRuTcg4mhdP54C0Y8wpFY9ST5iTpMS48U=
Received: from eusmges3new.samsung.com (unknown [203.254.199.245]) by
 eucas1p1.samsung.com (KnoxPortal) with ESMTP id
 20201008052345eucas1p1a31fc4d671e0ce725b75cfe5a29168b3~77PP2DVDq0288802888eucas1p1x;
 Thu,  8 Oct 2020 05:23:45 +0000 (GMT)
Received: from eucas1p1.samsung.com ( [182.198.249.206]) by
 eusmges3new.samsung.com (EUCPMTA) with SMTP id F0.AD.06318.062AE7F5; Thu,  8
 Oct 2020 06:23:44 +0100 (BST)
Received: from eusmtrp1.samsung.com (unknown [182.198.249.138]) by
 eucas1p2.samsung.com (KnoxPortal) with ESMTPA id
 20201008052344eucas1p270b04ad2c4346e6beb5f5ef844827085~77PPNEA4X2933529335eucas1p2g;
 Thu,  8 Oct 2020 05:23:44 +0000 (GMT)
Received: from eusmgms2.samsung.com (unknown [182.198.249.180]) by
 eusmtrp1.samsung.com (KnoxPortal) with ESMTP id
 20201008052344eusmtrp18065f384e12ff8762c85305bfaa22cb5~77PPMgvt42941529415eusmtrp1Z;
 Thu,  8 Oct 2020 05:23:44 +0000 (GMT)
X-AuditID: cbfec7f5-371ff700000018ae-b4-5f7ea26008ed
Received: from eusmtip1.samsung.com ( [203.254.199.221]) by
 eusmgms2.samsung.com (EUCPMTA) with SMTP id 8D.F0.06017.062AE7F5; Thu,  8
 Oct 2020 06:23:44 +0100 (BST)
Received: from Padamandas.fritz.box (unknown [106.210.88.70]) by
 eusmtip1.samsung.com (KnoxPortal) with ESMTPA id
 20201008052343eusmtip11f9068f3fb3c564113b4d817649b348b~77POlXP4h2784127841eusmtip19;
 Thu,  8 Oct 2020 05:23:43 +0000 (GMT)
From: Lukasz Wojciechowski <l.wojciechow@partner.samsung.com>
To: David Hunt <david.hunt@intel.com>, Bruce Richardson
 <bruce.richardson@intel.com>
Cc: dev@dpdk.org, l.wojciechow@partner.samsung.com, stable@dpdk.org
Date: Thu,  8 Oct 2020 07:23:18 +0200
Message-Id: <20201008052323.11547-11-l.wojciechow@partner.samsung.com>
X-Mailer: git-send-email 2.17.1
In-Reply-To: <20201008052323.11547-1-l.wojciechow@partner.samsung.com>
X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFnrKIsWRmVeSWpSXmKPExsWy7djPc7oJi+riDY58s7a4screom/SRyaL
 d5+2M1k861nHaPGv4w+7A6vHrwVLWT0W73nJ5HHw3R6mAOYoLpuU1JzMstQifbsEroyLx36z
 FhyWqnjz6zxTA+M20S5GTg4JAROJhvsLGLsYuTiEBFYwSrw+eIkFwvnCKHHr0UJWCOczo0TP
 rh+sMC0/lkPYQgLLGSW+3TCBsD8xSrw4HgViswnYShyZ+RWsRkQgTKK5eS/QVA4OZgFniSdf
 2UBMYQEPiUmLuEAqWARUJSY+2scOYvMKuElc/PwfapO8xOoNB5hBbE6g+Nn/d8HOkRC4zibx
 +vUVqCIXiUkbd0HZwhKvjm9hh7BlJE5P7mGBaNjGKHH1909GCGc/o8T13hVQVdYSh//9ZoM4
 TlNi/S59iLCjxLLPt5lAwhICfBI33gqChJmBzEnbpjNDhHklOtqEIKr1JJ72TGWEWftn7RMW
 CNtD4vXbPdAgvAp0QvNk5gmM8rMQli1gZFzFKJ5aWpybnlpsnJdarlecmFtcmpeul5yfu4kR
 GPmn/x3/uoNx35+kQ4wCHIxKPLwGR2vjhVgTy4orcw8xSnAwK4nwOp09HSfEm5JYWZValB9f
 VJqTWnyIUZqDRUmc13jRy1ghgfTEktTs1NSC1CKYLBMHp1QDo5VqcKSLFcOtULWfj/ZdkpOp
 fG6xM6Gh5cm9dBdTgXVaDt/Tz2uuWrhr9XxDCe1TUgddD+pf//nS0rm7aMLkx1YLbUwWcj2f
 M81+1oQlz2f1eOkxrD+7fvXO3x756U/m6F5nPns7id/tFZOELIfVtib3nVditZ9YFgfZtgvz
 fr4sdMJt00mnx0osxRmJhlrMRcWJADW9h1v4AgAA
X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFjrOLMWRmVeSWpSXmKPExsVy+t/xu7oJi+riDV6uFLC4screom/SRyaL
 d5+2M1k861nHaPGv4w+7A6vHrwVLWT0W73nJ5HHw3R6mAOYoPZui/NKSVIWM/OISW6VoQwsj
 PUNLCz0jE0s9Q2PzWCsjUyV9O5uU1JzMstQifbsEvYyLx36zFhyWqnjz6zxTA+M20S5GTg4J
 AROJH8t/sHYxcnEICSxllNj+ex1bFyMHUEJG4sMlAYgaYYk/17rYIGo+MEocmL+OCSTBJmAr
 cWTmV1aQehGBMIkTK/1BwswC7hJbFk9lBgkLC3hITFrEBRJmEVCVmPhoHzuIzSvgJnHx839W
 iPHyEqs3HGAGsTmB4mf/34U6p5FR4ub5mWwTGPkWMDKsYhRJLS3OTc8tNtIrTswtLs1L10vO
 z93ECAzEbcd+btnB2PUu+BCjAAejEg+vwdHaeCHWxLLiytxDjBIczEoivE5nT8cJ8aYkVlal
 FuXHF5XmpBYfYjQFumois5Rocj4wSvJK4g1NDc0tLA3Njc2NzSyUxHk7BA7GCAmkJ5akZqem
 FqQWwfQxcXBKNTDumPv2U5Lv2SO2ZnMv/+86y1qR5O7LUa/wJFX1+kbeHcza899zXp8bsk6f
 rTS6XcjP6+N+Jz2rhc0mLSm82jX2XmtjhX7OeGjLJnVr5Sfjud4ntFeKf9VQtdsZwqqdrBUW
 Imhg3ne+xf36LomckJrUhrYXzUzzTp5Z8OJMhmZw6PEj2qs3FSuxFGckGmoxFxUnAgB6DBQc
 WgIAAA==
X-CMS-MailID: 20201008052344eucas1p270b04ad2c4346e6beb5f5ef844827085
X-Msg-Generator: CA
Content-Type: text/plain; charset="utf-8"
X-RootMTR: 20201008052344eucas1p270b04ad2c4346e6beb5f5ef844827085
X-EPHeader: CA
CMS-TYPE: 201P
X-CMS-RootMailID: 20201008052344eucas1p270b04ad2c4346e6beb5f5ef844827085
References: <20200925224209.12173-1-l.wojciechow@partner.samsung.com>
 <20201008052323.11547-1-l.wojciechow@partner.samsung.com>
 <CGME20201008052344eucas1p270b04ad2c4346e6beb5f5ef844827085@eucas1p2.samsung.com>
Subject: [dpdk-dev] [PATCH v5 10/15] distributor: align API documentation
	with code
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

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: david.hunt@intel.com
Cc: stable@dpdk.org

Signed-off-by: Lukasz Wojciechowski <l.wojciechow@partner.samsung.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 327c0c4ab..a073e6461 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.17.1