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

[Randy Dunlap]

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