Re: [dpdk-dev] [PATCH 04/11] ethdev: fix docs of drivers callbacks getting xstats by IDs

[Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>]

On 7/23/21 5:31 PM, Ferruh Yigit wrote:
> On 7/22/2021 10:33 AM, Andrew Rybchenko wrote:
>> On 7/20/21 7:51 PM, Ferruh Yigit wrote:
>>> On 6/4/2021 3:42 PM, Andrew Rybchenko wrote:
>>>> From: Ivan Ilchenko <ivan.ilchenko@oktetlabs.ru>
>>>>
>>>> Update xstats by IDs callbacks documentation in accordance with
>>>> ethdev usage of these callbacks. Document valid combinations of
>>>> input arguments to make driver implementation simpler.
>>>>
>>>> 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>

[snip]

>>>> + * @param dev
>>>> + *   ethdev handle of port.
>>>> + * @param xstats_names
>>>> + *   An rte_eth_xstat_name array of at least *size* elements to
>>>> + *   be filled. Can be NULL together with @p ids to retrieve number of
>>>> + *   available statistics.
>>>
>>> As far as I understand both _by_id APIs and devops behave same, so argument
>>> descriptions/behavior should be same.
>>
>> In fact no, it is slightly different. For example, devops is never
>> called with NULL ids and not NULL names or non-zero size. It allows to
>> check less in drivers.
>>
> 
> I am not sure if this difference is intentional.

What we're trying to do here is to document existing usage of these
callbacks to more strictly define valid input parameters to allow
drivers to support less combinations (to make implementation simpler).

So, intentional.

If you're trying to say that API functions could handle less variants,
the answer is simple - it could be discussed, but out of scope of the
patch series since it will be API change.
> 'eth_dev_get_xstats_count()' is ethdev internal function, what do you think
> removing 'xstats_get_names_by_id()' call from it. And make both _by_id() dev_ops
> doesn't accept NULL ids and NULL values/names, so simplifies PMD implementations.
>
In fact the function eth_dev_get_xstats_count() looks buggy since it
does not use  xstats_get_names_by_id positive result if
xstats_get_names is not NULL. Really confusing.

Again, it will be slight change on PMD requirements. May be it is OK
to do, but I'd conduct it separately since it is logically a separate
thing. Current patches just clarify documentation.