patches for DPDK stable branches
 help / color / mirror / Atom feed
From: Ferruh Yigit <ferruh.yigit@intel.com>
To: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>, <dev@dpdk.org>
Cc: Ivan Ilchenko <ivan.ilchenko@oktetlabs.ru>, <stable@dpdk.org>,
	"Andy Moreton" <amoreton@xilinx.com>,
	Thomas Monjalon <thomas@monjalon.net>,
	"Kuba Kozak" <kubax.kozak@intel.com>
Subject: Re: [dpdk-stable] [PATCH 03/11] ethdev: fix docs of functions getting xstats by IDs
Date: Tue, 20 Jul 2021 17:25:36 +0100
Message-ID: <0a2b1c55-bcf0-de80-0baa-eb0abb97f37d@intel.com> (raw)
In-Reply-To: <20210604144225.287678-4-andrew.rybchenko@oktetlabs.ru>

On 6/4/2021 3:42 PM, Andrew Rybchenko wrote:
> From: Ivan Ilchenko <ivan.ilchenko@oktetlabs.ru>
> 
> Document valid combinations of input arguments in accordance with
> current implementation in ethdev.
> 
> Fixes: 79c913a42f0 ("ethdev: retrieve xstats by ID")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Ivan Ilchenko <ivan.ilchenko@oktetlabs.ru>
> Signed-off-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
> Reviewed-by: Andy Moreton <amoreton@xilinx.com>
> ---
>  lib/ethdev/rte_ethdev.h | 23 ++++++++++++++---------
>  1 file changed, 14 insertions(+), 9 deletions(-)
> 
> diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
> index faf3bd901d..1f63118544 100644
> --- a/lib/ethdev/rte_ethdev.h
> +++ b/lib/ethdev/rte_ethdev.h
> @@ -2873,12 +2873,15 @@ int rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
>   *   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.
> + *   be filled. Must not be NULL if @p ids are specified (not NULL).

Removed part is also valid. If both 'ids' & 'xstats_names' are NULL, API returns
number of all elements.

Addition part looks good.

>   * @param ids
> - *   IDs array given by app to retrieve specific statistics
> + *   IDs array given by app to retrieve specific statistics. May be NULL
> + *   to retrieve all available statistics.

ack

>   * @param size
> - *   The size of the xstats_names array (number of elements).
> + *   If @p ids is not NULL, number of elements in the array with requested IDs
> + *   and number of elements in @p xstats_names to put names in. If @p ids is
> + *   NULL, number of elements in @p xstats_names to put all available statistics
> + *   names in.

ack

>   * @return
>   *   - A positive value lower or equal to size: success. The return value
>   *     is the number of entries filled in the stats table.
> @@ -2886,7 +2889,7 @@ int rte_eth_xstats_get(uint16_t port_id, struct rte_eth_xstat *xstats,
>   *     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.

ack


The 'eth_dev_get_xstats_count()' API is flexible but it makes API unnecessarily
complex, not for this patch but for future perhaps we can update the API and it
can return error if either 'ids' or 'xstats_names' is NULL. Remove support to
get all elements or getting number of elements support, these already supported
by non _id version of API.


And as a note for future, if we ever consider updating these _by_id APIs, we can
consider making the parameter order same for both, currently it is:
"rte_eth_xstats_get_names_by_id(port_id, values, size, ids)"
"      rte_eth_xstats_get_by_id(port_id, ids, values, size)"

>   */
>  int
>  rte_eth_xstats_get_names_by_id(uint16_t port_id,
> @@ -2900,13 +2903,15 @@ rte_eth_xstats_get_names_by_id(uint16_t 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
> + *   statistics values function should retrieve. May be NULL to retrieve
>   *   all available statistics.

Update is good. But what do you think to make it exact same in the both APIs
('rte_eth_xstats_get_names_by_id()' & 'rte_eth_xstats_get_by_id()')? Since it is
used for same purpose and exact same way in both APIs, no need to have slightly
different description.

>   * @param values
>   *   A pointer to a table to be filled with device statistics values.
> + *   Must not be NULL if ids are specified (not NULL).

Same comment on making description similar in both APIs.

Also both 'ids' & 'values' being NULL returns number of all elements should be
addressed.

>   * @param size
> - *   The size of the ids array (number of elements).
> + *   If @p ids is not NULL, number of elements in the array with requested IDs
> + *   and number of elements in values to put statistics in. If @p ids is NULL,
> + *   number of elements in values to put all available statistics in.

ack

>   * @return
>   *   - A positive value lower or equal to size: success. The return value
>   *     is the number of entries filled in the stats table.
> @@ -2914,7 +2919,7 @@ rte_eth_xstats_get_names_by_id(uint16_t port_id,
>   *     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.

ack

>   */
>  int rte_eth_xstats_get_by_id(uint16_t port_id, const uint64_t *ids,
>  			     uint64_t *values, unsigned int size);
> 


  reply	other threads:[~2021-07-20 16:25 UTC|newest]

Thread overview: 36+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <20210604144225.287678-1-andrew.rybchenko@oktetlabs.ru>
2021-06-04 14:42 ` [dpdk-stable] [PATCH 01/11] net/sfc: fix get xstats by ID callback to use MAC stats lock Andrew Rybchenko
2021-06-04 14:42 ` [dpdk-stable] [PATCH 02/11] net/sfc: fix reading adapter state without locking Andrew Rybchenko
2021-06-04 14:42 ` [dpdk-stable] [PATCH 03/11] ethdev: fix docs of functions getting xstats by IDs Andrew Rybchenko
2021-07-20 16:25   ` Ferruh Yigit [this message]
2021-07-22  9:12     ` Andrew Rybchenko
2021-07-23 14:19       ` Ferruh Yigit
2021-07-24 12:06         ` Andrew Rybchenko
2021-06-04 14:42 ` [dpdk-stable] [PATCH 04/11] ethdev: fix docs of drivers callbacks " Andrew Rybchenko
2021-07-20 16:51   ` Ferruh Yigit
2021-07-22  9:33     ` Andrew Rybchenko
2021-07-23 14:31       ` Ferruh Yigit
2021-07-23 18:47         ` Andrew Rybchenko
2021-06-04 14:42 ` [dpdk-stable] [PATCH 05/11] net/sfc: fix xstats by ID callbacks according to ethdev Andrew Rybchenko
2021-06-04 14:42 ` [dpdk-stable] [PATCH 06/11] net/sfc: fix accessing xstats by an unsorted list of IDs Andrew Rybchenko
2021-06-04 14:42 ` [dpdk-stable] [PATCH 07/11] net/sfc: fix MAC stats update to work for stopped device Andrew Rybchenko
     [not found] ` <20210722095433.1898589-1-andrew.rybchenko@oktetlabs.ru>
2021-07-22  9:54   ` [dpdk-stable] [PATCH v2 01/11] net/sfc: fix get xstats by ID callback to use MAC stats lock Andrew Rybchenko
2021-07-22  9:54   ` [dpdk-stable] [PATCH v2 02/11] net/sfc: fix reading adapter state without locking Andrew Rybchenko
2021-07-22  9:54   ` [dpdk-stable] [PATCH v2 03/11] ethdev: fix docs of functions getting xstats by IDs Andrew Rybchenko
2021-07-22  9:54   ` [dpdk-stable] [PATCH v2 04/11] ethdev: fix docs of drivers callbacks " Andrew Rybchenko
2021-07-22  9:54   ` [dpdk-stable] [PATCH v2 05/11] net/sfc: fix xstats by ID callbacks according to ethdev Andrew Rybchenko
2021-07-22  9:54   ` [dpdk-stable] [PATCH v2 06/11] net/sfc: fix accessing xstats by an unsorted list of IDs Andrew Rybchenko
2021-07-22  9:54   ` [dpdk-stable] [PATCH v2 07/11] net/sfc: fix MAC stats update to work for stopped device Andrew Rybchenko
     [not found] ` <20210723131515.2317168-1-andrew.rybchenko@oktetlabs.ru>
2021-07-23 13:15   ` [dpdk-stable] [PATCH v3 01/11] net/sfc: fix get xstats by ID callback to use MAC stats lock Andrew Rybchenko
2021-07-23 13:15   ` [dpdk-stable] [PATCH v3 02/11] net/sfc: fix reading adapter state without locking Andrew Rybchenko
2021-07-23 13:15   ` [dpdk-stable] [PATCH v3 03/11] ethdev: fix docs of functions getting xstats by IDs Andrew Rybchenko
2021-07-23 14:42     ` Ferruh Yigit
2021-07-24 12:07       ` Andrew Rybchenko
2021-07-23 13:15   ` [dpdk-stable] [PATCH v3 04/11] ethdev: fix docs of drivers callbacks " Andrew Rybchenko
2021-07-23 14:46     ` Ferruh Yigit
2021-07-23 13:15   ` [dpdk-stable] [PATCH v3 05/11] net/sfc: fix xstats by ID callbacks according to ethdev Andrew Rybchenko
2021-07-23 13:15   ` [dpdk-stable] [PATCH v3 06/11] net/sfc: fix accessing xstats by an unsorted list of IDs Andrew Rybchenko
2021-07-23 13:15   ` [dpdk-stable] [PATCH v3 07/11] net/sfc: fix MAC stats update to work for stopped device Andrew Rybchenko
2021-07-24 12:33 ` [dpdk-stable] [PATCH v4 1/2] ethdev: fix docs of functions getting xstats by IDs Andrew Rybchenko
2021-07-24 12:33   ` [dpdk-stable] [PATCH v4 2/2] ethdev: fix docs of drivers callbacks " Andrew Rybchenko
2021-07-26 10:13     ` [dpdk-stable] [dpdk-dev] " Olivier Matz
2021-07-26 10:13   ` [dpdk-stable] [dpdk-dev] [PATCH v4 1/2] ethdev: fix docs of functions " Olivier Matz

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=0a2b1c55-bcf0-de80-0baa-eb0abb97f37d@intel.com \
    --to=ferruh.yigit@intel.com \
    --cc=amoreton@xilinx.com \
    --cc=andrew.rybchenko@oktetlabs.ru \
    --cc=dev@dpdk.org \
    --cc=ivan.ilchenko@oktetlabs.ru \
    --cc=kubax.kozak@intel.com \
    --cc=stable@dpdk.org \
    --cc=thomas@monjalon.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

patches for DPDK stable branches

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/stable/0 stable/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 stable stable/ https://inbox.dpdk.org/stable \
		stable@dpdk.org
	public-inbox-index stable

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.stable


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git