summaryrefslogtreecommitdiff
path: root/include/linux/timekeeping.h
diff options
context:
space:
mode:
authorArnd Bergmann <arnd@arndb.de>2018-07-10 17:46:41 +0300
committerJonathan Corbet <corbet@lwn.net>2018-07-23 18:16:56 +0300
commit0e3fd810c4f41dbd63fb7caddc11684959176727 (patch)
treec82a2a422f8f1bbd02adeef4458021ba573470ad /include/linux/timekeeping.h
parent6b4c1360e8adc2cbecf400b97c1ffcf9c5aad31e (diff)
downloadlinux-0e3fd810c4f41dbd63fb7caddc11684959176727.tar.xz
Documentation: document ktime_get_*() APIs
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> Tested-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Linus Walleij <linus.walleij@linaro.org> Signed-off-by: Arnd Bergmann <arnd@arndb.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'include/linux/timekeeping.h')
-rw-r--r--include/linux/timekeeping.h15
1 files changed, 15 insertions, 0 deletions
diff --git a/include/linux/timekeeping.h b/include/linux/timekeeping.h
index 86bc2026efce..947b1b8d2d01 100644
--- a/include/linux/timekeeping.h
+++ b/include/linux/timekeeping.h
@@ -21,6 +21,21 @@ extern int do_sys_settimeofday64(const struct timespec64 *tv,
const struct timezone *tz);
/*
+ * ktime_get() family: read the current time in a multitude of ways,
+ *
+ * The default time reference is CLOCK_MONOTONIC, starting at
+ * boot time but not counting the time spent in suspend.
+ * For other references, use the functions with "real", "clocktai",
+ * "boottime" and "raw" suffixes.
+ *
+ * To get the time in a different format, use the ones wit
+ * "ns", "ts64" and "seconds" suffix.
+ *
+ * See Documentation/core-api/timekeeping.rst for more details.
+ */
+
+
+/*
* timespec64 based interfaces
*/
extern void ktime_get_raw_ts64(struct timespec64 *ts);