Received-SPF: pass (google.com: domain of linux-kernel+bounces-130462-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249;
From: "Keller, Jacob E" <jacob.e.keller@intel.com>
To: Rahul Rameshbabu <rrameshbabu@nvidia.com>, Jakub Kicinski
	<kuba@kernel.org>
CC: "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
Thread-Topic: [PATCH net-next v1 1/6] ethtool: add interface to read Tx
 hardware timestamping statistics
Thread-Index: AQHahT/KhBQgJ7xfRU6OkjwNf3vRTbFVz/4AgAAxKACAAOIfoA==
Date: Wed, 3 Apr 2024 18:44:52 +0000
Message-ID: <CO1PR11MB508917567D84B711C2BD5821D63D2@CO1PR11MB5089.namprd11.prod.outlook.com>
References: <20240402205223.137565-1-rrameshbabu@nvidia.com>
 <20240402205223.137565-2-rrameshbabu@nvidia.com>
 <20240402191842.66decfd3@kernel.org> <87r0fn2e2b.fsf@nvidia.com>
In-Reply-To: <87r0fn2e2b.fsf@nvidia.com>
Accept-Language: en-US
Content-Language: en-US
x-ms-exchange-antispam-messagedata-chunkcount: 1
x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?4ZkybWUXwr5BgjPLu0Pc1ZagWoW3gqH1hGyfVvwxnmemP8bvhZa0NOUe0ZI4?=
 =?us-ascii?Q?w+u/ebMko2aqlabWQ4XRKiBlkrB8LFhaHyY7qAfh7pcHcOrgG7DBvp2kQ+6i?=
 =?us-ascii?Q?I2wZsAvghoMHnPCh4D60hYe/UyPO32UHW3v/ab86m4YYdOfnrIyzkpm4FzAx?=
 =?us-ascii?Q?l6lfVZ4U1n10yA3Y1kIEE2LaALSIfzeGPQ9M9MAvmCCdDAon9gHdSDCYqhQA?=
 =?us-ascii?Q?IfTzcj+VsNqb1HCcUj8Epz56XUlnTMEdr6YeFecPwL/wPJNL+IUFj9z8JjMl?=
 =?us-ascii?Q?msG8+l+uwhH5pw6aSaBss8103Dg6aiBH0C9RPM8uGxzMhjJb4sIqBi23Oaf2?=
 =?us-ascii?Q?TIKCAWSXfsH0nCgFG8EZn5KRqUBerTpl3iZUYJWW2ryIPRGYwK5rH+Oc2DME?=
 =?us-ascii?Q?V1pVXftGcGP8Pyu8/pF3OrZDhpqZodU1zjcpvdCNLMVu7wDWUY8NNyec/sRC?=
 =?us-ascii?Q?eNg1bmC9jNiTckAE1XKoriZSt4jc/AwpNVqHSJHV6mdrY47BCeSuHVtbjHpU?=
 =?us-ascii?Q?Z4ISpNxqzJF79tvM2H4NaIKNAAQtexdE9dAqxjAQT7mdtNroNRjCe/0FzKrR?=
 =?us-ascii?Q?OmzlB7InzTnRZb+ZAUIcy6bmlnN7PkWmUluo72EFHil4dvcHSNDWdN8Roi2G?=
 =?us-ascii?Q?0mIgUIXA6+g25jStvW+0QxPK3tDaN9tw8sjEmLQHAf7AF6ibLfUfhgCe1NWW?=
 =?us-ascii?Q?VOp6BngZ7xWYGIsgu72aPOKkQmZa/hnxXWoOSbRWKXlrzb4dnpHkkVOg24pk?=
 =?us-ascii?Q?LBOGeTwQ5SP4TIKj+h+Il9qAOlqtVm4XCxmAs6iGQ+xPR7m83+IlfF6HCVEX?=
 =?us-ascii?Q?XkMOKjwlglOD44ZV/9L+dzG0bSH2jHRrNJ61h5VKl4Is67IeNxtMESgWaeKN?=
 =?us-ascii?Q?JIhBNMwFSDBw3aPIdleU70k7H/EyugOo73nXvlR3b+ur4mMcolqDTro2pY4v?=
 =?us-ascii?Q?lVhsmU/rB2iO//vlIrOXZO4yushYcdRJm8yQ/HcjZOxN19gBOedQP72+PEgf?=
 =?us-ascii?Q?3HeQ98ykqp9tpASh/V+DCD+Lr8QEKF80/Gvy53zCY/GmASALWEZ65iRO3g9s?=
 =?us-ascii?Q?wJcKcjv/s81OvQr6AzhzYiO4c7HijA1M0ABm+ST3JdRiNIswDaim3ZNQdzhr?=
 =?us-ascii?Q?Fkf/U878msTXfoFV+4x2RDgdrm7sEOCZ/T8ldlcUxWJe2Ax5ej2E8MEUyOPO?=
 =?us-ascii?Q?DVqhMWxMJxyaD8bQQnKMQTcaR/9egAom6m1lB7oYd4BQpPdesw/OazVZbwL2?=
 =?us-ascii?Q?tiklSwGC/RKA8xkK+lAKn+SeOXP+zu4F8P3GEtKflb56wIZ8Mt3qqLOL77iy?=
 =?us-ascii?Q?jIQqjd5jW7fvF9Ao/lbG9KZe0SlFJ63y7LssjUOZucZftXOouuPfX/Degekv?=
 =?us-ascii?Q?E0DZOlWp71HWu2xzJWhLUB2D5iSgejcCKwDo0360Oh+HUdgwA18VKw6rI0Zm?=
 =?us-ascii?Q?fh8O6sw7mBqoCKHS0n0kcq9UJxjr8S1Ob5Fsrkv3YjOl1vdf3kGKp6ZXtOan?=
 =?us-ascii?Q?VXVhhRjLQPzm8iI93L4nVPuceIemNLr6zdm9z69I0cPQEV0F1ZjJO4kjFX3F?=
 =?us-ascii?Q?ZjHCMHOEW9I9LYT91prD/koOT78TbmU3dNa5xtGR?=
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Precedence: bulk
X-Mailing-List: linux-kernel@vger.kernel.org
List-Id: <linux-kernel.vger.kernel.org>
List-Subscribe: <mailto:linux-kernel+subscribe@vger.kernel.org>
List-Unsubscribe: <mailto:linux-kernel+unsubscribe@vger.kernel.org>
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-AuthSource: CO1PR11MB5089.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 4d14f5dd-69dd-4d88-c176-08dc540e261d
X-MS-Exchange-CrossTenant-originalarrivaltime: 03 Apr 2024 18:44:52.5281
 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: Gs7vyWffv/H+1o8Krd02eY4B8zqhk4wHa2s2C+9E/CQgKulPPN6dWYR/uJT/ztrnc7MSWJj7gt3sWVXLSLgIRhY1cGPmR07Dy4ZWRzWeL0A=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ1PR11MB6299
X-OriginatorOrg: intel.com


> -----Original Message-----
> From: Rahul Rameshbabu <rrameshbabu@nvidia.com>
> Sent: Tuesday, April 2, 2024 10:15 PM
> To: Jakub Kicinski <kuba@kernel.org>
> Cc: netdev@vger.kernel.org; linux-kernel@vger.kernel.org; linux-
> doc@vger.kernel.org; Zaki, Ahmed <ahmed.zaki@intel.com>; Lobakin, Aleksan=
der
> <aleksander.lobakin@intel.com>; alexandre.torgue@foss.st.com;
> andrew@lunn.ch; cjubran@nvidia.com; corbet@lwn.net; davem@davemloft.net;
> dtatulea@nvidia.com; edumazet@google.com; gal@nvidia.com;
> hkallweit1@gmail.com; Keller, Jacob E <jacob.e.keller@intel.com>;
> jiri@resnulli.us; joabreu@synopsys.com; justinstitt@google.com;
> kory.maincent@bootlin.com; leon@kernel.org; liuhangbin@gmail.com;
> maxime.chevallier@bootlin.com; pabeni@redhat.com; Greenwalt, Paul
> <paul.greenwalt@intel.com>; Kitszel, Przemyslaw <przemyslaw.kitszel@intel=
com>;
> rdunlap@infradead.org; richardcochran@gmail.com; saeed@kernel.org;
> tariqt@nvidia.com; vadim.fedorenko@linux.dev; vladimir.oltean@nxp.com;
> Drewek, Wojciech <wojciech.drewek@intel.com>
> Subject: Re: [PATCH net-next v1 1/6] ethtool: add interface to read Tx ha=
rdware
> timestamping statistics
>=20
> On Tue, 02 Apr, 2024 19:18:42 -0700 Jakub Kicinski <kuba@kernel.org> wrot=
e:
> > 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 t=
he
> >> + *		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'
>=20
> Was looking into why our internal verification did not catch this. We
> run W=3D1 with clang, but looks like the warning does not get triggered
> unless explicitly run with scripts/kernel-doc.
>=20
>   https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#how-to=
-
> format-kernel-doc-comments
>=20
> I have debugged using strace that the way the kernel doc checking works
> when W=3D1 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.
>=20

It would be great if the W=3D1 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 warn=
ings because a lot fewer people manually run kernel-doc on the entire sourc=
e.

> Anyway, I will send out a v2 with this fixed but wait for potentially
> more feedback on v1.
>=20
> --
> Thanks,
>=20
> Rahul Rameshbabu