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@fromorbit.com Cc: John Stultz john.stultz@linaro.org Cc: Thomas Gleixner tglx@linutronix.de Cc: Stephen Boyd sboyd@kernel.org Cc: Linus Walleij linus.walleij@linaro.org Signed-off-by: Arnd Bergmann arnd@arndb.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@infradead.org Reviewed-by: Randy Dunlap rdunlap@infradead.org
thanks,