ethtool: Clarify len/n_stats fields in/out semantics
Subsystems (3)
PATCH v2 1/1 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).
---v1->v2: https://lore.kernel.org/all/[email protected]/
* Reword comments (Jakub).
--- include/uapi/linux/ethtool.h | 14 ++++++++++++++ 1 file changed, 14 insertions(+)
include/uapi/linux/ethtool.h +14 -0
@@ -1101,6 +1101,13 @@ enum ethtool_module_fw_flash_status {* 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;
@@ -1184,6 +1191,13 @@ struct ethtool_test {* 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;
Signature · 1 line
2.40.1
Jakub Kicinski
maintainerinclude/uapi/linux/ethtool.h enum ethtool_module_fw_flash_status { · line 1110
Quoted 13 lines · On Mon, 12 Jan 2026 13:57:08 +0200 Gal Pressman wrote:
include/uapi/linux/ethtool.h +7
-0@@ -1101,6 +1101,13 @@ enum ethtool_module_fw_flash_status {* 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.
Thanks the new text looks good, but we should also remove the "On return, the " from the field kdoc?
Quoted 17 lines · Jakub Kicinski
include/uapi/linux/ethtool.h enum ethtool_module_fw_flash_status { · line 1110
Quoted 13 lines · On Mon, 12 Jan 2026 13:57:08 +0200 Gal Pressman wrote:
include/uapi/linux/ethtool.h +7
-0@@ -1101,6 +1101,13 @@ enum ethtool_module_fw_flash_status {* 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. Thanks the new text looks good, but we should also remove the "On return, the " from the field kdoc?
I think it makes sense to keep.
The new text clarifies the in behavior, but the out behavior remains.
Jakub Kicinski
maintainerQuoted 19 lines · On Wed, 14 Jan 2026 08:50:01 +0200 Gal Pressman wrote:
Quoted 17 lines · Jakub Kicinski
include/uapi/linux/ethtool.h enum ethtool_module_fw_flash_status { · line 1110
Quoted 13 lines · On Mon, 12 Jan 2026 13:57:08 +0200 Gal Pressman wrote:
include/uapi/linux/ethtool.h +7
-0@@ -1101,6 +1101,13 @@ enum ethtool_module_fw_flash_status {* 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. Thanks the new text looks good, but we should also remove the "On return, the " from the field kdoc?
Quoted 3 lines
I think it makes sense to keep.
The new text clarifies the in behavior, but the out behavior remains.
I'd interpret the "On return," as an indication that it's an output only field. Not saying that's an intelligent interpretation, but it's an existence proof. The uAPI comments should avoid ambiguity...