[PATCH net-next v2] ethtool: Clarify len/n_stats fields in/out semantics

[PATCH net-next v2] ethtool: Clarify len/n_stats fields in/out semantics

[Gal Pressman]

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).

Reviewed-by: Dragos Tatulea <dtatulea@nvidia.com>
Signed-off-by: Gal Pressman <gal@nvidia.com>
---
v1->v2: https://lore.kernel.org/all/20260105163923.49104-1-gal@nvidia.com/
* Reword comments (Jakub).
---
 include/uapi/linux/ethtool.h | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/include/uapi/linux/ethtool.h b/include/uapi/linux/ethtool.h
index eb7ff2602fbb..de810f1c3bfb 100644
--- a/include/uapi/linux/ethtool.h
+++ b/include/uapi/linux/ethtool.h
@@ -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;
-- 
2.40.1

Re: [PATCH net-next v2] ethtool: Clarify len/n_stats fields in/out semantics

[Jakub Kicinski]

On Mon, 12 Jan 2026 13:57:08 +0200 Gal Pressman wrote:
> --- a/include/uapi/linux/ethtool.h
> +++ b/include/uapi/linux/ethtool.h
> @@ -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?

Re: [PATCH net-next v2] ethtool: Clarify len/n_stats fields in/out semantics

[Gal Pressman]

On 14/01/2026 5:06, Jakub Kicinski wrote:
> On Mon, 12 Jan 2026 13:57:08 +0200 Gal Pressman wrote:
>> --- a/include/uapi/linux/ethtool.h
>> +++ b/include/uapi/linux/ethtool.h
>> @@ -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.

Re: [PATCH net-next v2] ethtool: Clarify len/n_stats fields in/out semantics

[Jakub Kicinski]

On Wed, 14 Jan 2026 08:50:01 +0200 Gal Pressman wrote:
> On 14/01/2026 5:06, Jakub Kicinski wrote:
> > On Mon, 12 Jan 2026 13:57:08 +0200 Gal Pressman wrote:  
> >> --- a/include/uapi/linux/ethtool.h
> >> +++ b/include/uapi/linux/ethtool.h
> >> @@ -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.

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...