Received-SPF: pass (google.com: domain of linux-kernel+bounces-172824-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1;
From: Thomas Gleixner <tglx@linutronix.de>
To: Richard Cochran <richardcochran@gmail.com>, Mahesh Bandewar
 <maheshb@google.com>
Cc: Netdev <netdev@vger.kernel.org>, Linux <linux-kernel@vger.kernel.org>,
 David Miller <davem@davemloft.net>, Jakub Kicinski <kuba@kernel.org>, Eric
 Dumazet <edumazet@google.com>, Paolo Abeni <pabeni@redhat.com>, Arnd
 Bergmann <arnd@arndb.de>, Sagi Maimon <maimon.sagi@gmail.com>, Jonathan
 Corbet <corbet@lwn.net>, John Stultz <jstultz@google.com>, Mahesh Bandewar
 <mahesh@bandewar.net>
Subject: Re: [PATCHv4 net-next] ptp/ioctl: support MONOTONIC_RAW timestamps
 for PTP_SYS_OFFSET_EXTENDED
In-Reply-To: <ZjsDJ-adNCBQIbG1@hoboy.vegasvil.org>
References: <20240502211047.2240237-1-maheshb@google.com>
 <ZjsDJ-adNCBQIbG1@hoboy.vegasvil.org>
Date: Wed, 08 May 2024 09:38:58 +0200
Message-ID: <87cypwpxbh.ffs@tglx>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain

On Tue, May 07 2024 at 21:44, Richard Cochran wrote:
> On Thu, May 02, 2024 at 02:10:47PM -0700, Mahesh Bandewar wrote:
>> +/*
>> + * ptp_sys_offset_extended - data structure for IOCTL operation
>> + *			     PTP_SYS_OFFSET_EXTENDED
>> + *
>> + * @n_samples:	Desired number of measurements.
>> + * @clockid:	clockid of a clock-base used for pre/post timestamps.
>> + * @rsv:	Reserved for future use.
>> + * @ts:		Array of samples in the form [pre-TS, PHC, post-TS]. The
>> + *		kernel provides @n_samples.
>> + *
>> + * History:
>> + * v1: Initial implementation.
>> + *
>> + * v2: Use the first word of the reserved-field for @clockid. That's
>> + *     backward compatible since v1 expects all three reserved words
>> + *     (@rsv[3]) to be 0 while the clockid (first word in v2) for
>> + *     CLOCK_REALTIME is '0'.
>
> This is not really appropriate for a source code comment.  The
> un-merged patch series iterations are preserved at lore.kernel in case
> someone needs that.
>
> The "backward compatible" information really wants to be in the commit
> message.

I agree that it wants to be in the commit message, but having the
version information in the kernel-doc which describes the UAPI is
sensible and useful. That's where I'd look first and asking a user to
dig up this information on lore is not really helpful.

Thanks,

        tglx