Received-SPF: pass (google.com: domain of linux-kernel+bounces-130603-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
References: <20240402205223.137565-1-rrameshbabu@nvidia.com>
 <20240402205223.137565-2-rrameshbabu@nvidia.com>
 <20240402191842.66decfd3@kernel.org> <87r0fn2e2b.fsf@nvidia.com>
 <CO1PR11MB508917567D84B711C2BD5821D63D2@CO1PR11MB5089.namprd11.prod.outlook.com>
User-agent: mu4e 1.10.8; emacs 28.2
From: Rahul Rameshbabu <rrameshbabu@nvidia.com>
To: "Keller, Jacob E" <jacob.e.keller@intel.com>
Cc: Jakub Kicinski <kuba@kernel.org>, "netdev@vger.kernel.org"
 <netdev@vger.kernel.org>, "linux-kernel@vger.kernel.org"
 <linux-kernel@vger.kernel.org>, "linux-doc@vger.kernel.org"
 <linux-doc@vger.kernel.org>, "Zaki, Ahmed" <ahmed.zaki@intel.com>,
 "Lobakin, Aleksander" <aleksander.lobakin@intel.com>,
 "alexandre.torgue@foss.st.com" <alexandre.torgue@foss.st.com>,
 "andrew@lunn.ch" <andrew@lunn.ch>, "cjubran@nvidia.com"
 <cjubran@nvidia.com>, "corbet@lwn.net" <corbet@lwn.net>,
 "davem@davemloft.net" <davem@davemloft.net>, "dtatulea@nvidia.com"
 <dtatulea@nvidia.com>, "edumazet@google.com" <edumazet@google.com>,
 "gal@nvidia.com" <gal@nvidia.com>, "hkallweit1@gmail.com"
 <hkallweit1@gmail.com>, "jiri@resnulli.us" <jiri@resnulli.us>,
 "joabreu@synopsys.com" <joabreu@synopsys.com>, "justinstitt@google.com"
 <justinstitt@google.com>, "kory.maincent@bootlin.com"
 <kory.maincent@bootlin.com>, "leon@kernel.org" <leon@kernel.org>,
 "liuhangbin@gmail.com" <liuhangbin@gmail.com>,
 "maxime.chevallier@bootlin.com" <maxime.chevallier@bootlin.com>,
 "pabeni@redhat.com" <pabeni@redhat.com>, "Greenwalt, Paul"
 <paul.greenwalt@intel.com>, "Kitszel, Przemyslaw"
 <przemyslaw.kitszel@intel.com>, "rdunlap@infradead.org"
 <rdunlap@infradead.org>, "richardcochran@gmail.com"
 <richardcochran@gmail.com>, "saeed@kernel.org" <saeed@kernel.org>,
 "tariqt@nvidia.com" <tariqt@nvidia.com>, "vadim.fedorenko@linux.dev"
 <vadim.fedorenko@linux.dev>, "vladimir.oltean@nxp.com"
 <vladimir.oltean@nxp.com>, "Drewek, Wojciech" <wojciech.drewek@intel.com>
Subject: Re: [PATCH net-next v1 1/6] ethtool: add interface to read Tx
 hardware timestamping statistics
Date: Wed, 03 Apr 2024 13:56:06 -0700
In-reply-to: <CO1PR11MB508917567D84B711C2BD5821D63D2@CO1PR11MB5089.namprd11.prod.outlook.com>
Message-ID: <87wmpeyx70.fsf@nvidia.com>
Content-Type: text/plain
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?us-ascii?Q?Z7OTiZw5SLenPKvSfKlaG8xIGAx63kMAGSfDQ6OeO0uQxisRv8zzWyi43LJj?=
 =?us-ascii?Q?RCHyr9/kSBOuU9S+/1zOScJTL9+eefs4l95EhiZukabmhm1oQpE87yBkFdlc?=
 =?us-ascii?Q?lVchSha/uz0KR0BE33h1EitTh6zIFO6Q8AcAWH7RcFN+ZGrYqL2GzoJ55mRC?=
 =?us-ascii?Q?fShEX3hal3ujOXS40mucG3IpfFFwZhptAbUBpFdzkqHiTR6OTiz5+p6fdcu0?=
 =?us-ascii?Q?HuBEW3rifnbT/JQdkCZy1p1s3LV8Pqoy2Fqv8hQPUs8fv0CvdHcP/UGcnd09?=
 =?us-ascii?Q?mWlSJeKVEjZC0afgzkocifHZrHkGH0Dk3kPmZhq0OMiJtOK7gyMOsGNWiIXl?=
 =?us-ascii?Q?hhs5RR1k4H3W1XYH+U4mJEEaTCMqb7/wTlDSCczYjYT3tQylT+z9l1FeSRJ0?=
 =?us-ascii?Q?zOfW25d39W4JpdUuMW9GwZtqteokhdbUDr4MM738oHQy8VKcAoUJFfo+4jR1?=
 =?us-ascii?Q?LMZeBdVj31bQzemwUiiyeMhSwGVevTly/Y4yw6oecNyiEauBZMBsm1CfX0IH?=
 =?us-ascii?Q?H8sfRNJAY1W2+PXNsKt0IqhpeTjFJcYdYo9wfO//96hjbhLVLpJSo4zctAtO?=
 =?us-ascii?Q?8nmqPdwaHLwWnrlPw0s73rpahPD+yGd2HCZlTyJAh9iok1jDQHZVl3eOTywh?=
 =?us-ascii?Q?KlbuFvFhYtqbmWMxaUqo4TY9bJSV9ptma3asO4gVTrtg3joU5QCd2bw2KUe2?=
 =?us-ascii?Q?pjaPLPvQImMsWfENStdJpGqnlPYCEBE1BjPjf64IWKIUpbyqReTdmGMH77vt?=
 =?us-ascii?Q?wIhUlHh79a+bjd0/HJVNR95rj6FaGHXIUvN0+r0CtfM22m4Xop7kQaHdxreR?=
 =?us-ascii?Q?Zpz7em9c86TCsXG/uP3YDSW7jlHBYgenYKWO8d+93NDiU8QVs9WIYgcikdHl?=
 =?us-ascii?Q?Zj4brmgxiH3stS8dbiOpT7BEbS7Yy4/eGCZ3Okf2/KdfiCuhLkAJmUL9Li/k?=
 =?us-ascii?Q?OK+dvy7n2dpEw5mWTw23wHRXSbKg88pCaHqzTEXdRLDqys94rqdguZWztLxD?=
 =?us-ascii?Q?+76ljiz4ZfI182S4xkdj8Feinry5oxHrgLLF+01bGrt7PHGNy6Up5ozNDWMP?=
 =?us-ascii?Q?cmBZpAnM7M1dh/yylzmPXU32eb3DxhAtO02H6UB5tSaliH4+xrxgG04c+U6n?=
 =?us-ascii?Q?9fYVzCScfkHky+sHTIi4T1j4bMiVQoZvXX7w5SLVGkjOIE6m/Gpmrn1TSOi7?=
 =?us-ascii?Q?ZdwzWfdDmc2KAPYY8W8jFtPpu/608s52n/bR8FF9HkF0LAlf7A2VbxwOvYw/?=
 =?us-ascii?Q?djhrQvgBP1I4LTfpMzJYv0hUpW1IemPxejR523cgKFjX+1xdYy0l27D4A46e?=
 =?us-ascii?Q?xGBYrWIhnZw4j300crL7nZm3E7Ih/hWA13bOe1aUrd/hQ1ET1q7Lr3ZwZh1+?=
 =?us-ascii?Q?VA4eeJOnc8DSolWZ+rNqwqiX8U1063uWTnuLbM8RLIZy19qg2a1YmYfMZziL?=
 =?us-ascii?Q?bJQpBOx5FXgxEWQWaEEKNuXUJzh/yzkjIimjQQSOP3rzjEDHfk5ReQt5LOCS?=
 =?us-ascii?Q?2laTvAtf+lcUVl9/4RUV5xCEdcajE+qPughQqYtitarzg1CKJ2RrMdXvMpw5?=
 =?us-ascii?Q?S1KF6kDagMOSMBDAJTydYAeAJM6FhbufbzYITr15MV2JvBS8zEiKKN1cuBS9?=
 =?us-ascii?Q?Wg=3D=3D?=
X-OriginatorOrg: Nvidia.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 24fb27c9-0aa8-4c3f-5d2c-08dc5421b53c
X-MS-Exchange-CrossTenant-AuthSource: BYAPR12MB2743.namprd12.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 03 Apr 2024 21:04:53.2893
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 43083d15-7273-40c1-b7db-39efd9ccc17a
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: z1udrScBQIquOrsjz5xGdLesRHB9GCXjvPxiKjCoQIJFLVUpQAsd0YsIVoSzr6sTSy++JHWt83kGsdSKdZPoLQ==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA3PR12MB7922

On Wed, 03 Apr, 2024 18:44:52 +0000 "Keller, Jacob E" <jacob.e.keller@intel.com> wrote:
>> On Tue, 02 Apr, 2024 19:18:42 -0700 Jakub Kicinski <kuba@kernel.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.
>> 
>
> It would be great if the W=1 setup could figure out the include files and send
> those to kernel-doc too, but I'm not sure if this is possible and if so how
> difficult it would be to implement it. A lot of headers produce warnings because
> a lot fewer people manually run kernel-doc on the entire source.
>

I took a look into this, and the one naive solution I had in mind was a
checkdocs target for the kernel where you use gcc -MM to deduce all the
includes, create a unique list, and then run scripts/kernel-doc against
the list of include files. That said, I do think this is excessive
compared to having a checkpatch logic that runs scripts/kernel-doc on
the parts that change in your commit before and after the patch is
applied.

Kudos to the netdev CI for having this.

  https://github.com/linux-netdev/nipa/blob/main/tests/patch/kdoc/kdoc.sh