From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-lj1-f195.google.com ([209.85.208.195]:36094 "EHLO mail-lj1-f195.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751869AbeFZQIF (ORCPT ); Tue, 26 Jun 2018 12:08:05 -0400 MIME-Version: 1.0 In-Reply-To: <20180626002417.GH13748@dastard> References: <20180620150138.49380-1-arnd@arndb.de> <20180621202339.GC13748@dastard> <20180626002417.GH13748@dastard> From: Arnd Bergmann Date: Tue, 26 Jun 2018 18:08:01 +0200 Message-ID: Subject: Re: [Y2038] [PATCH] vfs: replace current_kernel_time64 with ktime equivalent To: Dave Chinner Cc: Jens Axboe , Jan Kara , Jeff Layton , "Darrick J. Wong" , y2038 Mailman List , Brian Foster , Miklos Szeredi , Pavel Tatashin , Linux Kernel Mailing List , Linux FS-devel Mailing List , Alexander Viro , Andi Kleen , Andrew Morton , Deepa Dinamani Content-Type: text/plain; charset="UTF-8" Sender: linux-fsdevel-owner@vger.kernel.org List-ID: On Tue, Jun 26, 2018 at 2:24 AM, Dave Chinner wrote: > On Fri, Jun 22, 2018 at 03:24:48PM +0200, Arnd Bergmann wrote: >> On Thu, Jun 21, 2018 at 10:23 PM, Dave Chinner wrote: >> > On Wed, Jun 20, 2018 at 05:01:24PM +0200, Arnd Bergmann wrote: >> You definitely have a point about the documentation. I meant to >> fix that as part of the recent rework of the timekeeping.h header >> but haven't finished it, partly because the header is still being >> changed as we get rid of the older interfaces. > > The interface documentation should be introduced with the new > interfaces, not left for later as that leaves people like me with no > fucking clue about what the changes actually mean or why they are > being done. Perhaps you'd have done better to explain this API as > an internal implementation of clock_gettime(CLOCK_REALTIME_COARSE), > which is clearly documented in the man page as: > > "Use when you need very fast, but not fine-grained timestamps." > > Put that comment on ktime_get_coarse_real_ts64(), and almost all the > questions about "WTF does this whacky function do?" go away.... I've tried to come up with a coherent documentation now and sent a patch for that. For this version, I ended up not documenting each of the ktime_get() functions separately but instead added a new file in the core-api documentation and a reference to that from the header. This seemed easier to understand than duplicating the same text for over 30 very similar interfaces. Arnd