From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 89530A0C50; Fri, 23 Jul 2021 16:19:30 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 206074014D; Fri, 23 Jul 2021 16:19:30 +0200 (CEST) Received: from mga05.intel.com (mga05.intel.com [192.55.52.43]) by mails.dpdk.org (Postfix) with ESMTP id CB13540040; Fri, 23 Jul 2021 16:19:28 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10053"; a="297458112" X-IronPort-AV: E=Sophos;i="5.84,264,1620716400"; d="scan'208";a="297458112" Received: from orsmga004.jf.intel.com ([10.7.209.38]) by fmsmga105.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 23 Jul 2021 07:19:27 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,264,1620716400"; d="scan'208";a="565517295" Received: from fmsmsx603.amr.corp.intel.com ([10.18.126.83]) by orsmga004.jf.intel.com with ESMTP; 23 Jul 2021 07:19:27 -0700 Received: from fmsmsx608.amr.corp.intel.com (10.18.126.88) by fmsmsx603.amr.corp.intel.com (10.18.126.83) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.10; Fri, 23 Jul 2021 07:19:26 -0700 Received: from fmsmsx603.amr.corp.intel.com (10.18.126.83) by fmsmsx608.amr.corp.intel.com (10.18.126.88) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.10; Fri, 23 Jul 2021 07:19:26 -0700 Received: from fmsedg601.ED.cps.intel.com (10.1.192.135) by fmsmsx603.amr.corp.intel.com (10.18.126.83) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.10 via Frontend Transport; Fri, 23 Jul 2021 07:19:26 -0700 Received: from NAM12-DM6-obe.outbound.protection.outlook.com (104.47.59.168) by edgegateway.intel.com (192.55.55.70) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2242.10; Fri, 23 Jul 2021 07:19:24 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=gWp4qJ6QPcEwuf2e0+KgNDDOxwPaGQblspid/4ji3ySUeGJo9p45r3BCPtiGAcvXEtbu9n8UqsOjvfRTtpEqsrs19JPa6uorariA1txcYtBH0PreultDfHPQQyJuS+nyiKCwDrmKbS+zVAdhIE8i+nF954JC26XTurbsBA403jhGYYiyLC5XKHHdbpx/ePV/1vSaGGxcjT5YzRJs3EKhSZY1lGtQo1xNwAs1Dstq2MkciAXNI+lndG+bek8a79wRJamOSrvXWRzcSLs1W+1p1kBh3wFF1IEEmlCJxdzBpGy10joh0qg9gGTBl06pb32lM++I9Y8hwORzHt74RJIz1g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=xya0/imVrfpiCO8Qmta5bWdkoElRla017su5StaSNJw=; b=cTzedaFnoxMP5ZRdtk52LAoE8TS8ID0haOump/El0/lJKk5uff5oJkhpDxeK6oHY3lSveUyXOQuqlRBUwxRqra9euQ6Eeqlvh3/DXhzahwT/TM5FP97/070cybBGvmNTl+E5JNS38182YCOzuubaWYrLtetfQou9K2WFniK4Kts63YEJ2lqxF27/+cnT+PjvVFQUnyrxeVESPI6mymfDRk4NQuS/+cw2omfZ7lQQZ05EUgDxB5rKNSozfjnb3BqrppHsgUhiD3V0H9mtxVrXx7F8IXSfODaqmtfqd0OOqbLNDXCKVFkcLGCUk5fWL6xw4454qFsZe6/oB60KpNX27w== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com; dkim=pass header.d=intel.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=intel.onmicrosoft.com; s=selector2-intel-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=xya0/imVrfpiCO8Qmta5bWdkoElRla017su5StaSNJw=; b=GBnTbMlpZyk6LIgys7KsL9cfvkTtu1ExGdsbA7FwpooRuOn2YD/vNclBKtjgYls5JMxgPTL5nIiVEb6+fdEVPy0TUdiJJtZrCACGA8/KSTXOiTJj5mHdE1W/4Vb3Zm0rSJfXJ/YpuWGP3e23kppDEXb5Ii5cO9H4b0WC6CrT7BU= Authentication-Results: intel.com; dkim=none (message not signed) header.d=none;intel.com; dmarc=none action=none header.from=intel.com; Received: from PH0PR11MB5000.namprd11.prod.outlook.com (2603:10b6:510:41::19) by PH0PR11MB5047.namprd11.prod.outlook.com (2603:10b6:510:3c::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4352.28; Fri, 23 Jul 2021 14:19:20 +0000 Received: from PH0PR11MB5000.namprd11.prod.outlook.com ([fe80::bde5:66de:e755:c5bb]) by PH0PR11MB5000.namprd11.prod.outlook.com ([fe80::bde5:66de:e755:c5bb%5]) with mapi id 15.20.4352.029; Fri, 23 Jul 2021 14:19:20 +0000 To: Andrew Rybchenko , CC: Ivan Ilchenko , , "Andy Moreton" , Thomas Monjalon , "Kuba Kozak" References: <20210604144225.287678-1-andrew.rybchenko@oktetlabs.ru> <20210604144225.287678-4-andrew.rybchenko@oktetlabs.ru> <0a2b1c55-bcf0-de80-0baa-eb0abb97f37d@intel.com> From: Ferruh Yigit X-User: ferruhy Message-ID: Date: Fri, 23 Jul 2021 15:19:14 +0100 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 8bit X-ClientProxiedBy: LO4P123CA0449.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:1a9::22) To PH0PR11MB5000.namprd11.prod.outlook.com (2603:10b6:510:41::19) MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 Received: from [192.168.0.206] (37.228.236.146) by LO4P123CA0449.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:1a9::22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4352.24 via Frontend Transport; Fri, 23 Jul 2021 14:19:18 +0000 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 506db969-567c-4b49-e4d5-08d94de4dc8f X-MS-TrafficTypeDiagnostic: PH0PR11MB5047: X-MS-Exchange-Transport-Forked: True X-Microsoft-Antispam-PRVS: X-MS-Oob-TLC-OOBClassifiers: OLM:8882; X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: MxiVpbvBgiJokp5nzdPV3NRAsr1fchkZxLrs1PgFXBA+kWOBUikLRLaRwGXdXQ58jYzPL3QsEavwDpaWLtKAZu6/Dp/J5zCjV7u+bgBX9vGGE4i3DT1NtBElG6lDcozOcoZudSCfbRyErd+84K4ZUdfseSuk0rXoI2aK3jqgKQuf/dqAOhyMjA7GnLSUeiEH6Hasr8luSSbfCU099sw3gJfUkNxUfw2Lw+W+f3VPwpVLQniSGIT8HjKarE9rqpWDVX/PToJUreDIFYwe9Y/kAep/lFrKrPV2bRPquJNiIec7eycNzGK+95hr7uumY8bhcD21lLU1RWEQhJVCBtOhwQMBSwwKcv6ea9Q/2aHSaMrAxtvb8oUn7eF/QtSb2CZ2roQrxkp76QtqLmv1WzBwu8IB3whMcL8CQrTCFYQaujDUPUtdJ8IqltoH/eQENX1pC+q1KUMaLyw6usSg7rMc51h+iGW4jPL1UdI/ZWAy+3G7hywTODneYHK1G3rbl2EFq2pnveN8IqINoVu8UEsnrSOWmlLaIQt84KMDWwMO9cjpHH4vV2VarRDIU398g6oQ/qCX3k3Vn1T8HPIH1MRmhi2+8C7hcD9QFpxbRyXkXQseTsV7W+gVh1WZlnaRqL6CuUJZqmMEUm680fvyBuR88F3mCHvBtTt87YyhvA+sRfzjFoUp5YA9zYQJ/XtYiKqmoqMZlNRUZEswSLRO8/t0pA== X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:PH0PR11MB5000.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(346002)(136003)(366004)(376002)(39860400002)(396003)(38100700002)(26005)(5660300002)(31696002)(83380400001)(2906002)(478600001)(36756003)(86362001)(53546011)(107886003)(8936002)(2616005)(956004)(66946007)(54906003)(66476007)(66556008)(44832011)(16576012)(8676002)(31686004)(4326008)(6486002)(186003)(6666004)(316002)(45980500001); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?N1d5c3NVYUdQVEJUV2pmclpCNVliRGlJc3ZTd21ON3UvdWwxbGEzNzNuK3ZT?= =?utf-8?B?cGFVa3Q0aWdyYTQ2T2VkbzFZSjZuRzJieTMvNzFjdkJWZTl2cFg0bWZKa0Fy?= =?utf-8?B?TnFlYzYvS0YwK3NjYy9MdFR0QVVPcjhiTnpGT01ZMEE5OFBIcXU0K0prV3hE?= =?utf-8?B?ZDNXU2F6aE5nOEcwTkRITmw0M1ZzcTYrWW9KWjVjTHQ0a1duTytSR001OWZj?= =?utf-8?B?WHhVQjRoWS9HMTY1Tnc3dlFKSHF2R3JyNWNwdU9tTlFYdGs2VTZPNThLSXJr?= =?utf-8?B?UHF3Z0VwTVF4dmNZTnptVmhjZXQ1SkpmMXpLL2dCa1hueHYxZGJHMkthUXZx?= =?utf-8?B?YURwdkNaNlVPU1ZXeHgrTmpQaWRZY1ZFRGc5eXBqS2JKUlh4MWYzeG5TSUFT?= =?utf-8?B?S2Q3RC9oV2tJUks4MGtvOXpGaHNmMnBncmJ6Z1J3cVA2Y1gzNnA0OXB4SHZ4?= =?utf-8?B?ZFRGWW05eHI4T0dkM3dVMWZHTTZnMmdzWGRhWDI3WGZkQXNGMDZydnFUM2JF?= =?utf-8?B?SjRrZDZYdE9jSncwRDMrV2ZiMmp2VlNsKzNMNWlLOTZnc0NjZ2JrWWpqM2ZJ?= =?utf-8?B?ZnY4VlNDOHBOT1gwWGIrRU1uZkR1bmJtZ25zK3FyQ3krcXNVakliWC9Qb3hF?= =?utf-8?B?aldsejB0aGNWYUlDNHJhRGUrdFJReUJxYVgzQ3F4eTViTUJzUWdQRCtnTHZD?= =?utf-8?B?UUZvd2I2RXZtNVhteXBLUGtmVi9KWEpGcjV3d0s4bDlESnJ6WTRkczJuRDd6?= =?utf-8?B?SDV2bEl5NW1MNU4zWHRZQ25IcEdQWXZQSjVDWjVVZlZLZGxHQjZBdmRrZThO?= =?utf-8?B?N0ovZFB6emxjRkJVMS83LzhnaDRSMDQ0NHBkYktGNFFON2ovdkxoTHhqTkha?= =?utf-8?B?WWxxZXc3R3pmUDNyUVdDM2grazZqNDFhaVZYMWs2Mm55U1VnREdZSUlVTkVq?= =?utf-8?B?YkhZOFRudkx3aEdRYkJ4Z3I5amtDNndMbzluUnhwTEFOTlU3aEVDd2k3TkxK?= =?utf-8?B?dFVpWE1yeDdiTjZkNDdZVVlXb2d4UFVsUTVzQllpSE4zYnpVU0F1L3N0V1g0?= =?utf-8?B?SzMyYVNaUTI3ejIzV3BuTk9pTkNLUjAwcnh5Z1ZGQ1p1MG5oTUtoZHgvV0lk?= =?utf-8?B?ekl6dzlCMHVGTXgrQytreGZ2eWlCL2tNTEVkbm01Y0oxWEN1L3dpdXhWeHgy?= =?utf-8?B?ZXhMNDYzN0RvNjJXSTVQQ3Y3LzBHWHZpb2VoNHlHWFJUWmRJV05IdHNOSEFi?= =?utf-8?B?dWlDMVhGQldvdDZPOFdnZy9jZ3hiWVZxUXZ6a3A5akVwSmhFcU1obXQwbFNV?= =?utf-8?B?NWtCOXErRG93dUg3bWpTVlEwaW9RcElEWHh1M1czWFBSZmw0WGhCOTcyNmhJ?= =?utf-8?B?TkZoN0xDQzFpS2Z0ZFkvWDJXUXdDZXJ3R1BUOFRlVyszdnVPQXNxbHExaldr?= =?utf-8?B?ZjdvdTJ5eEJkRlNJRWY5WnhNOHZFempLLzBiUG1iRm5FZEU1Mm9MMVAxRCsv?= =?utf-8?B?T01TSEVFT3ZwN1pjS0FQSnY1VmswVU5DNGxQcytLdGtDN292RU8yVmlwK1gy?= =?utf-8?B?QVNWWXNYUmJ2em1rVXdpZnZDYkprQXk5T3hHTHNPa2U2Wkt4YitEeGNFcVg4?= =?utf-8?B?cHI3d0lqSlZSZ09kQmt6ak84dllBTGRQWUR6N0lZZUVCM1p6NmY1Y0V5aE9t?= =?utf-8?B?SWVleUU2bnM4ZU9YejgwbFU4Yk5FdTY1dndibk1UaE1vdDJNYWRncURoWXYw?= =?utf-8?Q?qzRQp3l9QzbxrjbS5wynYQtoOwSzfG+64iynKJh?= X-MS-Exchange-CrossTenant-Network-Message-Id: 506db969-567c-4b49-e4d5-08d94de4dc8f X-MS-Exchange-CrossTenant-AuthSource: PH0PR11MB5000.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 23 Jul 2021 14:19:20.0584 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: +nhhLp29eJSn9VAC8X5IC46tYxBOK7+yUlnUiE7fHQ/wettudWOtnqwV6BZ3XPNx5lW7SFjaDQpMCGHPmSiGQA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR11MB5047 X-OriginatorOrg: intel.com Subject: Re: [dpdk-dev] [PATCH 03/11] ethdev: fix docs of functions getting xstats by IDs X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On 7/22/2021 10:12 AM, Andrew Rybchenko wrote: > On 7/20/21 7:25 PM, Ferruh Yigit wrote: >> On 6/4/2021 3:42 PM, Andrew Rybchenko wrote: >>> From: Ivan Ilchenko >>> >>> 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 >>> Signed-off-by: Andrew Rybchenko >>> Reviewed-by: Andy Moreton >>> --- >>>   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. > > Yes, but it is an excessive information. The trigger to return number > of all elements is 'ids == NULL'. Here we are talking about > 'xstats_names' parameter. If the parameter is NULL, but ids is not > null, it does not trigger number of all elements return. It is an > invalid input parameters. That's what a new description says. > ids xstats_names a) NULL NULL valid, return _number_ of all elements b) NULL !NULL valid, return all elements (if size big enough) c) !NULL NULL invalid Above a) is a valid option, the previous comment tries to describe it via "If set to NULL, the function returns the required number of elements." and that part is removed. Since it is valid option I think we should keep it documented, location or wording is up to you. >> >> 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. > > I'm not sure that it is a right direction. The support allows > application to use less number of functions and depend on less > number of function prototypes. > True, but makes API more complex, and creates multiple way to do same thing (get number of all entries), trade off. >> 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)" > > +1, current difference is terribly bad > >>>    */ >>>   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. > > I agree. I'll fix in v2. > >>>    * @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. > > OK > >> Also both 'ids' & 'values' being NULL returns number of all elements should be >> addressed. > > I think it is excessibe. It is sufficient to say so for ids==NULL which > is a trigger to get all elements. > But these two are different things, one fills values with stats and return number of filled elements other doesn't fill any value, but only return number of all elements >>>    * @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); >>> >