linux-kernel - Re: [PATCH net-next v1 1/6] ethtool: add interface to read Tx hardware timestamping statistics

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87r0fn2e2b.fsf@nvidia.com>
Date: Tue, 02 Apr 2024 22:14:38 -0700
From: Rahul Rameshbabu <rrameshbabu@...dia.com>
To: Jakub Kicinski <kuba@...nel.org>
Cc: netdev@...r.kernel.org, linux-kernel@...r.kernel.org,
 linux-doc@...r.kernel.org, ahmed.zaki@...el.com,
 aleksander.lobakin@...el.com, alexandre.torgue@...s.st.com,
 andrew@...n.ch, cjubran@...dia.com, corbet@....net, davem@...emloft.net,
 dtatulea@...dia.com, edumazet@...gle.com, gal@...dia.com,
 hkallweit1@...il.com, jacob.e.keller@...el.com, jiri@...nulli.us,
 joabreu@...opsys.com, justinstitt@...gle.com, kory.maincent@...tlin.com,
 leon@...nel.org, liuhangbin@...il.com, maxime.chevallier@...tlin.com,
 pabeni@...hat.com, paul.greenwalt@...el.com, przemyslaw.kitszel@...el.com,
 rdunlap@...radead.org, richardcochran@...il.com, saeed@...nel.org,
 tariqt@...dia.com, vadim.fedorenko@...ux.dev, vladimir.oltean@....com,
 wojciech.drewek@...el.com
Subject: Re: [PATCH net-next v1 1/6] ethtool: add interface to read Tx
 hardware timestamping statistics

On Tue, 02 Apr, 2024 19:18:42 -0700 Jakub Kicinski <kuba@...nel.org> wrote:
> On Tue,  2 Apr 2024 13:52:01 -0700 Rahul Rameshbabu wrote:
>> +/**
>> + * struct ethtool_ts_stats - HW timestamping statistics
>> + * @tx_stats: struct group for TX HW timestamping
>> + *	@pkts: Number of packets successfully timestamped by the hardware.
>> + *	@lost: Number of hardware timestamping requests where the timestamping
>> + *		information from the hardware never arrived for submission with
>> + *		the skb.
>> + *	@err: Number of arbitrary timestamp generation error events that the
>> + *		hardware encountered, exclusive of @lost statistics. Cases such
>> + *		as resource exhaustion, unavailability, firmware errors, and
>> + *		detected illogical timestamp values not submitted with the skb
>> + *		are inclusive to this counter.
>> + */
>> +struct ethtool_ts_stats {
>> +	struct_group(tx_stats,
>
> Doesn't seem like the group should be documented:
>
> include/linux/ethtool.h:503: warning: Excess struct member 'tx_stats' description in 'ethtool_ts_stats'

Was looking into why our internal verification did not catch this. We
run W=1 with clang, but looks like the warning does not get triggered
unless explicitly run with scripts/kernel-doc.

  https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#how-to-format-kernel-doc-comments

I have debugged using strace that the way the kernel doc checking works
when W=1 is set is that the matching source file that is being compiled
is passed to scripts/kernel-doc, so include files are missed from the
doc check. I think this is worth adding to the kernel documentation.

Anyway, I will send out a v2 with this fixed but wait for potentially
more feedback on v1.

--
Thanks,

Rahul Rameshbabu