Message-ID: <d437aba7-f25f-0a96-e42b-997a3b6cda23@infradead.org>
Date:   Tue, 26 Jun 2018 10:19:24 -0700
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Arnd Bergmann <arnd@...db.de>, Jonathan Corbet <corbet@....net>
Cc:     y2038@...ts.linaro.org, Dave Chinner <david@...morbit.com>,
        John Stultz <john.stultz@...aro.org>,
        Thomas Gleixner <tglx@...utronix.de>,
        Stephen Boyd <sboyd@...nel.org>,
        Linus Walleij <linus.walleij@...aro.org>,
        Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
        Matthew Wilcox <mawilcox@...rosoft.com>,
        Michal Hocko <mhocko@...e.com>, Ingo Molnar <mingo@...nel.org>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] Documentation: document ktime_get_*() APIs

On 06/26/2018 09:03 AM, Arnd Bergmann wrote:
> As Dave Chinner points out, we don't have a proper documentation for the
> ktime_get() family of interfaces, making it rather unclear which of the
> over 30 (!) interfaces one should actually use in a driver or elsewhere
> in the kernel.
> 
> I wrote up an explanation from how I personally see the interfaces,
> documenting what each of the functions do and hopefully making it a bit
> clearer which should be used where.
> 
> This is the first time I tried writing .rst format documentation, so
> in addition to any mistakes in the content, I probably also introduce
> nonstandard formatting ;-)
> 
> I first tried to add an extra section to
> Documentation/timers/timekeeping.txt, but this is currently not included
> in the generated API, and it seems useful to have the API docs as part
> of what gets generated in
> https://www.kernel.org/doc/html/latest/core-api/index.html#core-utilities
> instead, so I started a new file there.
> 
> I also considered adding the documentation inline in the
> include/linux/timekeeping.h header, but couldn't figure out how to do
> that in a way that would result both in helpful inline comments as
> well as readable html output, so I settled for the latter, with
> a small note pointing to it from the header.
> 
> Cc: Dave Chinner <david@...morbit.com>
> Cc: John Stultz <john.stultz@...aro.org>
> Cc: Thomas Gleixner <tglx@...utronix.de>
> Cc: Stephen Boyd <sboyd@...nel.org>
> Cc: Linus Walleij <linus.walleij@...aro.org>
> Signed-off-by: Arnd Bergmann <arnd@...db.de>
> ---
>  Documentation/core-api/index.rst       |   1 +
>  Documentation/core-api/timekeeping.rst | 185 +++++++++++++++++++++++++++++++++
>  include/linux/timekeeping.h            |  15 +++
>  3 files changed, 201 insertions(+)
>  create mode 100644 Documentation/core-api/timekeeping.rst
> 
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index f5a66b72f984..989c97cc232a 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -28,6 +28,7 @@ Core utilities
>     printk-formats
>     circular-buffers
>     gfp_mask-from-fs-io
> +   timekeeping
>  
>  Interfaces for kernel debugging
>  ===============================
> diff --git a/Documentation/core-api/timekeeping.rst b/Documentation/core-api/timekeeping.rst
> new file mode 100644
> index 000000000000..97dafa69dddf
> --- /dev/null
> +++ b/Documentation/core-api/timekeeping.rst
> @@ -0,0 +1,185 @@
> +ktime access
> +============

I would prefer "ktime accessors" or "ktime interfaces", but no big deal.

> +
> +Device drivers can read the current time using ktime_get() and the many
> +related functions declared in linux/timekeeping.h. As a rule of thumb,
> +using an accessor with a shorter name is preferred over one with a longer
> +name if both are equally fit for a particular use case.
> +
> +Basic ktime_t based interfaces
> +------------------------------
> +
> +The recommended simplest form returns an opaque ktime_t, with variants
> +that return time for different clock references:
> +
> +
> +.. c:function:: ktime_t ktime_get( void )
> +
> +	CLOCK_MONOTONIC
> +
> +	Useful for reliable timestamps and measuring short time intervals
> +	accurately. Starts at system boot time but stops during suspend.
> +
> +.. c:function:: ktime_t ktime_get_boottime( void )
> +
> +	CLOCK_BOOTTIME
> +
> +	Like ktime_get(), but does not stop when suspended. This can be
> +	used e.g. for key expiration times that need to be synchronized
> +	with other machines across a suspend operation.
> +
> +.. c:function:: ktime_t ktime_get_real( void )
> +
> +	CLOCK_REALTIME
> +
> +	Returns the time in relative to the UNIX epoch starting in 1970
> +	using the Coordinated Universal Time (UTC), same as gettimeofday()
> +	user space. This is used for all timestamps that need to
> +	persist across a reboot, like inode times, but should be avoided
> +	for internal uses, since it can jump backwards due to a leap
> +	second update, NTP adjustment settimeofday() operation from user
> +	space.
> +
> +.. c:function:: ktime_t ktime_get_clocktai( void )
> +
> +	 CLOCK_TAI
> +
> +	Like ktime_get_real(), but uses the International Atomic Time (TAI)
> +	reference instead of UTC to avoid jumping on leap second updates.
> +	This is rarely useful in the kernel.
> +
> +.. c:function:: ktime_t ktime_get_raw( void )
> +
> +	CLOCK_MONOTONIC_RAW
> +
> +	Like ktime_get(), but runs at the same rate as the hardware
> +	clocksource without (NTP) adjustments for clock drift. This is
> +	also rarely needed in the kernel.
> +
> +nanosecond, timespec64, and second output
> +-------------------------------------

Documentation/core-api/timekeeping.rst:60: WARNING: Title underline too short.

nanosecond, timespec64, and second output
-------------------------------------

and that's the only sphinx error or warning that I see.  Nice.



Tested-by: Randy Dunlap <rdunlap@...radead.org>
Reviewed-by: Randy Dunlap <rdunlap@...radead.org>

thanks,
-- 
~Randy

Powered by blists - more mailing lists