Commit 56787300 authored by Gal Pressman's avatar Gal Pressman Committed by Jakub Kicinski
Browse files

ethtool: Clarify len/n_stats fields in/out semantics 



Document that the 'len' field in ethtool_gstrings and 'n_stats' field in
ethtool_stats optionally serve dual purposes: on entry they specify the
number of items requested, and on return they indicate the number
actually returned (which is not necessarily the same).

Signed-off-by: default avatarGal Pressman <gal@nvidia.com>
Reviewed-by: default avatarDragos Tatulea <dtatulea@nvidia.com>
Link: https://patch.msgid.link/20260115060544.481550-1-gal@nvidia.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent c2702249

include/uapi/linux/ethtool.h

+16 −2
Original line number Diff line number Diff line
@@ -1096,13 +1096,20 @@ enum ethtool_module_fw_flash_status { 
 * struct ethtool_gstrings - string set for data tagging

 * @cmd: Command number = %ETHTOOL_GSTRINGS

 * @string_set: String set ID; one of &enum ethtool_stringset

 * @len: On return, the number of strings in the string set

 * @len: Number of strings in the string set

 * @data: Buffer for strings.  Each string is null-padded to a size of

 *	%ETH_GSTRING_LEN.

 *

 * Users must use %ETHTOOL_GSSET_INFO to find the number of strings in

 * the string set.  They must allocate a buffer of the appropriate

 * size immediately following this structure.

 *

 * Setting @len on input is optional (though preferred), but must be zeroed

 * otherwise.

 * When set, @len will return the requested count if it matches the actual

 * count; otherwise, it will be zero.

 * This prevents issues when the number of strings is different than the

 * userspace allocation.

 */

struct ethtool_gstrings {

	__u32	cmd;
@@ -1179,13 +1186,20 @@ struct ethtool_test { 
/**

 * struct ethtool_stats - device-specific statistics

 * @cmd: Command number = %ETHTOOL_GSTATS

 * @n_stats: On return, the number of statistics

 * @n_stats: Number of statistics

 * @data: Array of statistics

 *

 * Users must use %ETHTOOL_GSSET_INFO or %ETHTOOL_GDRVINFO to find the

 * number of statistics that will be returned.  They must allocate a

 * buffer of the appropriate size (8 * number of statistics)

 * immediately following this structure.

 *

 * Setting @n_stats on input is optional (though preferred), but must be zeroed

 * otherwise.

 * When set, @n_stats will return the requested count if it matches the actual

 * count; otherwise, it will be zero.

 * This prevents issues when the number of stats is different than the

 * userspace allocation.

 */

struct ethtool_stats {

	__u32	cmd;