Re: [PATCH] Documentation: document ktime_get_*() APIs

From: Randy Dunlap
Date: Tue Jun 26 2018 - 13:19:35 EST


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@xxxxxxxxxxxxx>
> Cc: John Stultz <john.stultz@xxxxxxxxxx>
> Cc: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
> Cc: Stephen Boyd <sboyd@xxxxxxxxxx>
> Cc: Linus Walleij <linus.walleij@xxxxxxxxxx>
> Signed-off-by: Arnd Bergmann <arnd@xxxxxxxx>
> ---
> 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@xxxxxxxxxxxxx>
Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

thanks,
--
~Randy