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

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

[Arnd Bergmann]

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>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Arnd Bergmann <arnd@arndb.de>
---
v2: minor changes suggested by Randy
---
 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 e821cf78be3b..11b54e2bbce2 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -29,6 +29,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..93cbeb9daec0
--- /dev/null
+++ b/Documentation/core-api/timekeeping.rst
@@ -0,0 +1,185 @@
+ktime accessors
+===============
+
+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
+-----------------------------------------
+
+For all of the above, there are variants that return the time in a
+different format depending on what is required by the user:
+
+.. c:function:: u64 ktime_get_ns( void )
+		u64 ktime_get_boottime_ns( void )
+		u64 ktime_get_real_ns( void )
+		u64 ktime_get_tai_ns( void )
+		u64 ktime_get_raw_ns( void )
+
+	Same as the plain ktime_get functions, but returning a u64 number
+	of nanoseconds in the respective time reference, which may be
+	more convenient for some callers.
+
+.. c:function:: void ktime_get_ts64( struct timespec64 * )
+		void ktime_get_boottime_ts64( struct timespec64 * )
+		void ktime_get_real_ts64( struct timespec64 * )
+		void ktime_get_clocktai_ts64( struct timespec64 * )
+		void ktime_get_raw_ts64( struct timespec64 * )
+
+	Same above, but returns the time in a 'struct timespec64', split
+	into seconds and nanoseconds. This can avoid an extra division
+	when printing the time, or when passing it into an external
+	interface that expects a 'timespec' or 'timeval' structure.
+
+.. c:function:: time64_t ktime_get_seconds( void )
+		time64_t ktime_get_boottime_seconds( void )
+		time64_t ktime_get_real_seconds( void )
+		time64_t ktime_get_clocktai_seconds( void )
+		time64_t ktime_get_raw_seconds( void )
+
+	Return a coarse-grained version of the time as a scalar
+	time64_t. This avoids accessing the clock hardware and rounds
+	down the seconds to the full seconds of the last timer tick
+	using the respective reference.
+
+Coarse and fast_ns access
+-------------------------
+
+Some additional variants exist for more specialized cases:
+
+.. c:function:: ktime_t ktime_get_coarse_boottime( void )
+		ktime_t ktime_get_coarse_real( void )
+		ktime_t ktime_get_coarse_clocktai( void )
+		ktime_t ktime_get_coarse_raw( void )
+
+.. c:function:: void ktime_get_coarse_ts64( struct timespec64 * )
+		void ktime_get_coarse_boottime_ts64( struct timespec64 * )
+		void ktime_get_coarse_real_ts64( struct timespec64 * )
+		void ktime_get_coarse_clocktai_ts64( struct timespec64 * )
+		void ktime_get_coarse_raw_ts64( struct timespec64 * )
+
+	These are quicker than the non-coarse versions, but less accurate,
+	corresponding to CLOCK_MONONOTNIC_COARSE and CLOCK_REALTIME_COARSE
+	in user space, along with the equivalent boottime/tai/raw
+	timebase not available in user space.
+
+	The time returned here corresponds to the last timer tick, which
+	may be as much as 10ms in the past (for CONFIG_HZ=100), same as
+	reading the 'jiffies' variable.  These are only useful when called
+	in a fast path and one still expects better than second accuracy,
+	but can't easily use 'jiffies', e.g. for inode timestamps.
+	Skipping the hardware clock access saves around 100 CPU cycles
+	on most modern machines with a reliable cycle counter, but
+	up to several microseconds on older hardware with an external
+	clocksource.
+
+.. c:function:: u64 ktime_get_mono_fast_ns( void )
+		u64 ktime_get_raw_fast_ns( void )
+		u64 ktime_get_boot_fast_ns( void )
+		u64 ktime_get_real_fast_ns( void )
+
+	These variants are safe to call from any context, including from
+	a non-maskable interrupt (NMI) during a timekeeper update, and
+	while we are entering suspend with the clocksource powered down.
+	This is useful in some tracing or debugging code as well as
+	machine check reporting, but most drivers should never call them,
+	since the time is allowed to jump under certain conditions.
+
+Deprecated time interfaces
+--------------------------
+
+Older kernels used some other interfaces that are now being phased out
+but may appear in third-party drivers being ported here. In particular,
+all interfaces returning a 'struct timeval' or 'struct timespec' have
+been replaced because the tv_sec member overflows in year 2038 on 32-bit
+architectures. These are the recommended replacements:
+
+.. c:function:: void ktime_get_ts( struct timespec * )
+
+	Use ktime_get() or ktime_get_ts64() instead.
+
+.. c:function:: struct timeval do_gettimeofday( void )
+		struct timespec getnstimeofday( void )
+		struct timespec64 getnstimeofday64( void )
+		void ktime_get_real_ts( struct timespec * )
+
+	ktime_get_real_ts64() is a direct replacement, but consider using
+	monotonic time (ktime_get_ts64()) and/or a ktime_t based interface
+	(ktime_get()/ktime_get_real()).
+
+.. c:function:: struct timespec current_kernel_time( void )
+		struct timespec64 current_kernel_time64( void )
+		struct timespec get_monotonic_coarse( void )
+		struct timespec64 get_monotonic_coarse64( void )
+
+	These are replaced by ktime_get_coarse_real_ts64() and
+	ktime_get_coarse_ts64(). However, A lot of code that wants
+	coarse-grained times can use the simple 'jiffies' instead, while
+	some drivers may actually want the higher resolution accessors
+	these days.
+
+.. c:function:: struct timespec getrawmonotonic( void )
+		struct timespec64 getrawmonotonic64( void )
+		struct timespec timekeeping_clocktai( void )
+		struct timespec64 timekeeping_clocktai64( void )
+		struct timespec get_monotonic_boottime( void )
+		struct timespec64 get_monotonic_boottime64( void )
+
+	These are replaced by ktime_get_raw()/ktime_get_raw_ts64(),
+	ktime_get_clocktai()/ktime_get_clocktai_ts64() as well
+	as ktime_get_boottime()/ktime_get_boottime_ts64().
+	However, if the particular choice of clock source is not
+	important for the user, consider converting to
+	ktime_get()/ktime_get_ts64() instead for consistency.
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);
-- 
2.9.0

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

[Arnd Bergmann]

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>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Arnd Bergmann <arnd@arndb.de>
---
v2: minor changes suggested by Randy
---
 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 e821cf78be3b..11b54e2bbce2 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -29,6 +29,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..93cbeb9daec0
--- /dev/null
+++ b/Documentation/core-api/timekeeping.rst
@@ -0,0 +1,185 @@
+ktime accessors
+===============
+
+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
+-----------------------------------------
+
+For all of the above, there are variants that return the time in a
+different format depending on what is required by the user:
+
+.. c:function:: u64 ktime_get_ns( void )
+		u64 ktime_get_boottime_ns( void )
+		u64 ktime_get_real_ns( void )
+		u64 ktime_get_tai_ns( void )
+		u64 ktime_get_raw_ns( void )
+
+	Same as the plain ktime_get functions, but returning a u64 number
+	of nanoseconds in the respective time reference, which may be
+	more convenient for some callers.
+
+.. c:function:: void ktime_get_ts64( struct timespec64 * )
+		void ktime_get_boottime_ts64( struct timespec64 * )
+		void ktime_get_real_ts64( struct timespec64 * )
+		void ktime_get_clocktai_ts64( struct timespec64 * )
+		void ktime_get_raw_ts64( struct timespec64 * )
+
+	Same above, but returns the time in a 'struct timespec64', split
+	into seconds and nanoseconds. This can avoid an extra division
+	when printing the time, or when passing it into an external
+	interface that expects a 'timespec' or 'timeval' structure.
+
+.. c:function:: time64_t ktime_get_seconds( void )
+		time64_t ktime_get_boottime_seconds( void )
+		time64_t ktime_get_real_seconds( void )
+		time64_t ktime_get_clocktai_seconds( void )
+		time64_t ktime_get_raw_seconds( void )
+
+	Return a coarse-grained version of the time as a scalar
+	time64_t. This avoids accessing the clock hardware and rounds
+	down the seconds to the full seconds of the last timer tick
+	using the respective reference.
+
+Coarse and fast_ns access
+-------------------------
+
+Some additional variants exist for more specialized cases:
+
+.. c:function:: ktime_t ktime_get_coarse_boottime( void )
+		ktime_t ktime_get_coarse_real( void )
+		ktime_t ktime_get_coarse_clocktai( void )
+		ktime_t ktime_get_coarse_raw( void )
+
+.. c:function:: void ktime_get_coarse_ts64( struct timespec64 * )
+		void ktime_get_coarse_boottime_ts64( struct timespec64 * )
+		void ktime_get_coarse_real_ts64( struct timespec64 * )
+		void ktime_get_coarse_clocktai_ts64( struct timespec64 * )
+		void ktime_get_coarse_raw_ts64( struct timespec64 * )
+
+	These are quicker than the non-coarse versions, but less accurate,
+	corresponding to CLOCK_MONONOTNIC_COARSE and CLOCK_REALTIME_COARSE
+	in user space, along with the equivalent boottime/tai/raw
+	timebase not available in user space.
+
+	The time returned here corresponds to the last timer tick, which
+	may be as much as 10ms in the past (for CONFIG_HZ=100), same as
+	reading the 'jiffies' variable.  These are only useful when called
+	in a fast path and one still expects better than second accuracy,
+	but can't easily use 'jiffies', e.g. for inode timestamps.
+	Skipping the hardware clock access saves around 100 CPU cycles
+	on most modern machines with a reliable cycle counter, but
+	up to several microseconds on older hardware with an external
+	clocksource.
+
+.. c:function:: u64 ktime_get_mono_fast_ns( void )
+		u64 ktime_get_raw_fast_ns( void )
+		u64 ktime_get_boot_fast_ns( void )
+		u64 ktime_get_real_fast_ns( void )
+
+	These variants are safe to call from any context, including from
+	a non-maskable interrupt (NMI) during a timekeeper update, and
+	while we are entering suspend with the clocksource powered down.
+	This is useful in some tracing or debugging code as well as
+	machine check reporting, but most drivers should never call them,
+	since the time is allowed to jump under certain conditions.
+
+Deprecated time interfaces
+--------------------------
+
+Older kernels used some other interfaces that are now being phased out
+but may appear in third-party drivers being ported here. In particular,
+all interfaces returning a 'struct timeval' or 'struct timespec' have
+been replaced because the tv_sec member overflows in year 2038 on 32-bit
+architectures. These are the recommended replacements:
+
+.. c:function:: void ktime_get_ts( struct timespec * )
+
+	Use ktime_get() or ktime_get_ts64() instead.
+
+.. c:function:: struct timeval do_gettimeofday( void )
+		struct timespec getnstimeofday( void )
+		struct timespec64 getnstimeofday64( void )
+		void ktime_get_real_ts( struct timespec * )
+
+	ktime_get_real_ts64() is a direct replacement, but consider using
+	monotonic time (ktime_get_ts64()) and/or a ktime_t based interface
+	(ktime_get()/ktime_get_real()).
+
+.. c:function:: struct timespec current_kernel_time( void )
+		struct timespec64 current_kernel_time64( void )
+		struct timespec get_monotonic_coarse( void )
+		struct timespec64 get_monotonic_coarse64( void )
+
+	These are replaced by ktime_get_coarse_real_ts64() and
+	ktime_get_coarse_ts64(). However, A lot of code that wants
+	coarse-grained times can use the simple 'jiffies' instead, while
+	some drivers may actually want the higher resolution accessors
+	these days.
+
+.. c:function:: struct timespec getrawmonotonic( void )
+		struct timespec64 getrawmonotonic64( void )
+		struct timespec timekeeping_clocktai( void )
+		struct timespec64 timekeeping_clocktai64( void )
+		struct timespec get_monotonic_boottime( void )
+		struct timespec64 get_monotonic_boottime64( void )
+
+	These are replaced by ktime_get_raw()/ktime_get_raw_ts64(),
+	ktime_get_clocktai()/ktime_get_clocktai_ts64() as well
+	as ktime_get_boottime()/ktime_get_boottime_ts64().
+	However, if the particular choice of clock source is not
+	important for the user, consider converting to
+	ktime_get()/ktime_get_ts64() instead for consistency.
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);
-- 
2.9.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Linus Walleij]

On Tue, Jul 10, 2018 at 4:48 PM Arnd Bergmann <arnd@arndb.de> 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>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Signed-off-by: Arnd Bergmann <arnd@arndb.de>
> ---
> v2: minor changes suggested by Randy

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

This brings into question commit bc2b7dab629a5
"iio:core: timestamping clock selection support"
that has bothered me for some time. Now that is ABI, but
we might be able to do some recommendations based on the
time base and have a sensible default moving forward.

As I want to make that clock base parsing similar for GPIO
I first thought it was a good idea to support the same clocks,
but now it seems like a bad idea.

IIRC you told me to simply hammer down the clock that
makes the most sense.

At the same time userspace libraries (such as GNU radio) will
be confused if they can't match the timestamping clocks,
as correlating GPIO and IIO events is something they will
want to do. And I guess these clocks are there for a reason.

So asking Lars-Peter and Gregor: from a userspace point
of view, what makes most sense for the usecases you
have seen? Having one consistent time base or all of these
as we currently have? Different clocks under different
circumstances?

Yours,
Linus Walleij

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

[Linus Walleij]

On Tue, Jul 10, 2018 at 4:48 PM Arnd Bergmann <arnd@arndb.de> 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>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Signed-off-by: Arnd Bergmann <arnd@arndb.de>
> ---
> v2: minor changes suggested by Randy

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

This brings into question commit bc2b7dab629a5
"iio:core: timestamping clock selection support"
that has bothered me for some time. Now that is ABI, but
we might be able to do some recommendations based on the
time base and have a sensible default moving forward.

As I want to make that clock base parsing similar for GPIO
I first thought it was a good idea to support the same clocks,
but now it seems like a bad idea.

IIRC you told me to simply hammer down the clock that
makes the most sense.

At the same time userspace libraries (such as GNU radio) will
be confused if they can't match the timestamping clocks,
as correlating GPIO and IIO events is something they will
want to do. And I guess these clocks are there for a reason.

So asking Lars-Peter and Gregor: from a userspace point
of view, what makes most sense for the usecases you
have seen? Having one consistent time base or all of these
as we currently have? Different clocks under different
circumstances?

Yours,
Linus Walleij
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Arnd Bergmann]

On Fri, Jul 13, 2018 at 9:24 AM, Linus Walleij <linus.walleij@linaro.org> wrote:
> On Tue, Jul 10, 2018 at 4:48 PM Arnd Bergmann <arnd@arndb.de> wrote:
>>
>> 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>
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>> Signed-off-by: Arnd Bergmann <arnd@arndb.de>
>> ---
>> v2: minor changes suggested by Randy
>
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Thanks!

> This brings into question commit bc2b7dab629a5
> "iio:core: timestamping clock selection support"
> that has bothered me for some time. Now that is ABI, but
> we might be able to do some recommendations based on the
> time base and have a sensible default moving forward.
>
> As I want to make that clock base parsing similar for GPIO
> I first thought it was a good idea to support the same clocks,
> but now it seems like a bad idea.
>
> IIRC you told me to simply hammer down the clock that
> makes the most sense.

Right, my general recommendation would be to return the
result of ktime_get_ns() in a __u64, since this does not suffer
from the settimeofday or leap second issues that clock_realtime
has, using the coarse clock to save 100 cycles per call probably
won't help.

       Arnd

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

[Arnd Bergmann]

On Fri, Jul 13, 2018 at 9:24 AM, Linus Walleij <linus.walleij@linaro.org> wrote:
> On Tue, Jul 10, 2018 at 4:48 PM Arnd Bergmann <arnd@arndb.de> wrote:
>>
>> 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>
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>> Signed-off-by: Arnd Bergmann <arnd@arndb.de>
>> ---
>> v2: minor changes suggested by Randy
>
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Thanks!

> This brings into question commit bc2b7dab629a5
> "iio:core: timestamping clock selection support"
> that has bothered me for some time. Now that is ABI, but
> we might be able to do some recommendations based on the
> time base and have a sensible default moving forward.
>
> As I want to make that clock base parsing similar for GPIO
> I first thought it was a good idea to support the same clocks,
> but now it seems like a bad idea.
>
> IIRC you told me to simply hammer down the clock that
> makes the most sense.

Right, my general recommendation would be to return the
result of ktime_get_ns() in a __u64, since this does not suffer
from the settimeofday or leap second issues that clock_realtime
has, using the coarse clock to save 100 cycles per call probably
won't help.

       Arnd
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Jonathan Cameron]

On Fri, 13 Jul 2018 09:24:52 +0200
Linus Walleij <linus.walleij@linaro.org> wrote:

> On Tue, Jul 10, 2018 at 4:48 PM Arnd Bergmann <arnd@arndb.de> 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>
> > Tested-by: Randy Dunlap <rdunlap@infradead.org>
> > Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> > Signed-off-by: Arnd Bergmann <arnd@arndb.de>
> > ---
> > v2: minor changes suggested by Randy  
> 
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
> 
> This brings into question commit bc2b7dab629a5
> "iio:core: timestamping clock selection support"
> that has bothered me for some time. Now that is ABI, but
> we might be able to do some recommendations based on the
> time base and have a sensible default moving forward.
> 
> As I want to make that clock base parsing similar for GPIO
> I first thought it was a good idea to support the same clocks,
> but now it seems like a bad idea.
> 
> IIRC you told me to simply hammer down the clock that
> makes the most sense.
> 
> At the same time userspace libraries (such as GNU radio) will
> be confused if they can't match the timestamping clocks,
> as correlating GPIO and IIO events is something they will
> want to do. And I guess these clocks are there for a reason.
> 
> So asking Lars-Peter and Gregor: from a userspace point
> of view, what makes most sense for the usecases you
> have seen? Having one consistent time base or all of these
> as we currently have? Different clocks under different
> circumstances?

Yeah, this mess in IIO was all a silly mistake I made years
ago, though we may have messed up how to 'fix' it.

Basically I should probably have gone with a monotonic clock
but I didn't.  This leads to some really odd algorithm issues
when the non monotonic clocks are updated.

Still when we originally looked at it, the answer is that there
are different 'right' choices depending largely on what timescales
you are working at.

There are systems where you want to sample fairly infrequently enough
that you are not going to see the non monotonic jumps, and where your
biggest requirement is absolute precision on the time stamp.  In these
you would be frequently updating your clock.

Others are running at high speed and you need a best estimate smoothed
result that doesn't ever go backwards.

The right answer was probably to limit it to a couple of 'almost'
right choices - but that's hind sight.  Certainly don't copy this
without a lot of thought!

Now I wonder which of those clocks choices we can remove without anyone
ever noticing?

Jonathan

> 
> Yours,
> Linus Walleij
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Jonathan Cameron]

On Fri, 13 Jul 2018 09:24:52 +0200
Linus Walleij <linus.walleij@linaro.org> wrote:

> On Tue, Jul 10, 2018 at 4:48 PM Arnd Bergmann <arnd@arndb.de> 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>
> > Tested-by: Randy Dunlap <rdunlap@infradead.org>
> > Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> > Signed-off-by: Arnd Bergmann <arnd@arndb.de>
> > ---
> > v2: minor changes suggested by Randy  
> 
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
> 
> This brings into question commit bc2b7dab629a5
> "iio:core: timestamping clock selection support"
> that has bothered me for some time. Now that is ABI, but
> we might be able to do some recommendations based on the
> time base and have a sensible default moving forward.
> 
> As I want to make that clock base parsing similar for GPIO
> I first thought it was a good idea to support the same clocks,
> but now it seems like a bad idea.
> 
> IIRC you told me to simply hammer down the clock that
> makes the most sense.
> 
> At the same time userspace libraries (such as GNU radio) will
> be confused if they can't match the timestamping clocks,
> as correlating GPIO and IIO events is something they will
> want to do. And I guess these clocks are there for a reason.
> 
> So asking Lars-Peter and Gregor: from a userspace point
> of view, what makes most sense for the usecases you
> have seen? Having one consistent time base or all of these
> as we currently have? Different clocks under different
> circumstances?

Yeah, this mess in IIO was all a silly mistake I made years
ago, though we may have messed up how to 'fix' it.

Basically I should probably have gone with a monotonic clock
but I didn't.  This leads to some really odd algorithm issues
when the non monotonic clocks are updated.

Still when we originally looked at it, the answer is that there
are different 'right' choices depending largely on what timescales
you are working at.

There are systems where you want to sample fairly infrequently enough
that you are not going to see the non monotonic jumps, and where your
biggest requirement is absolute precision on the time stamp.  In these
you would be frequently updating your clock.

Others are running at high speed and you need a best estimate smoothed
result that doesn't ever go backwards.

The right answer was probably to limit it to a couple of 'almost'
right choices - but that's hind sight.  Certainly don't copy this
without a lot of thought!

Now I wonder which of those clocks choices we can remove without anyone
ever noticing?

Jonathan

> 
> Yours,
> Linus Walleij
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Lars-Peter Clausen]

On 07/13/2018 09:24 AM, Linus Walleij wrote:
> On Tue, Jul 10, 2018 at 4:48 PM Arnd Bergmann <arnd@arndb.de> 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>
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>> Signed-off-by: Arnd Bergmann <arnd@arndb.de>
>> ---
>> v2: minor changes suggested by Randy
> 
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
> 
> This brings into question commit bc2b7dab629a5
> "iio:core: timestamping clock selection support"
> that has bothered me for some time. Now that is ABI, but
> we might be able to do some recommendations based on the
> time base and have a sensible default moving forward.
> 
> As I want to make that clock base parsing similar for GPIO
> I first thought it was a good idea to support the same clocks,
> but now it seems like a bad idea.
> 
> IIRC you told me to simply hammer down the clock that
> makes the most sense.
> 
> At the same time userspace libraries (such as GNU radio) will
> be confused if they can't match the timestamping clocks,
> as correlating GPIO and IIO events is something they will
> want to do. And I guess these clocks are there for a reason.
> 
> So asking Lars-Peter and Gregor: from a userspace point
> of view, what makes most sense for the usecases you
> have seen? Having one consistent time base or all of these
> as we currently have? Different clocks under different
> circumstances?

It is a question of correlation. What other events do you want to correlate
your events to.

If you only want to correlate events to other events from the same source
(i.e. know the amount of time that has elapsed between two events) the best
in my opinion is a monotonic clock. You can't account for changes to the
realtime clock and it will screw up your measurements when it changes in
between two events.

Now for monotonic clocks there are two variants available MONOTONIC and
BOOTTIME. BOOTTIME will account for time that the device has been in
suspend, MONOTONIC will not. Most applications will not care for either. But
those which care about it and want to measure the duration between two
events will most likely prefer BOOTTIME, especially if the wakeup event was
caused by the device itself.

So in my opinion BOOTTIME is the most sensible default.

REALTIME should probably also be an option in case you want to correlate
your events to other events for which only a REALTIME timestamp is available
or when the absolute time matters rather than the relative time. This could
for example be rare events and you want to log time and date when they happened.

Right now I can't think of a usecase where soembody would prefer MONOTONIC
over BOOTTIME, but I'm sure there are some.

TAI and MONOTONIC_RAW are kind of the same thing. They are more immune to
changes of the exact duration of what is reported as a second. I'm sure
there are special applications that would prefer this over REALTIME and
MONOTONIC.

The only thing that is probably not really needed are the coarse variants.
But even there I could see people arguing that it serves their performance
and precision requirements better.

And to make this a lot more complicated many applications, especially in the
high-speed area, don't really care about the system time as reported by the
CPU (or a on-SoC timer) at all. They care about the time as reported by a
clock that is synchronous to the signal processing itself.

Different oscillators in a system will run at slightly different
frequencies, even if they are nominal the same frequency. So if you have 1
counter that says 1 second has elapsed another might say that 1.0001 seconds
have elapsed. If you do timestamping using a clock that is not synchronous
to your signal processing clock your results will be imprecise.

So that is something to keep in mind. Beyond just the system clock we might
want to have the ability to assign other timestamp sources in a way that is
consistent across subsystems. So that we can for example as you said
correlate events between IIO and GPIO.

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

[Lars-Peter Clausen]

On 07/13/2018 09:24 AM, Linus Walleij wrote:
> On Tue, Jul 10, 2018 at 4:48 PM Arnd Bergmann <arnd@arndb.de> 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>
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>> Signed-off-by: Arnd Bergmann <arnd@arndb.de>
>> ---
>> v2: minor changes suggested by Randy
> 
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
> 
> This brings into question commit bc2b7dab629a5
> "iio:core: timestamping clock selection support"
> that has bothered me for some time. Now that is ABI, but
> we might be able to do some recommendations based on the
> time base and have a sensible default moving forward.
> 
> As I want to make that clock base parsing similar for GPIO
> I first thought it was a good idea to support the same clocks,
> but now it seems like a bad idea.
> 
> IIRC you told me to simply hammer down the clock that
> makes the most sense.
> 
> At the same time userspace libraries (such as GNU radio) will
> be confused if they can't match the timestamping clocks,
> as correlating GPIO and IIO events is something they will
> want to do. And I guess these clocks are there for a reason.
> 
> So asking Lars-Peter and Gregor: from a userspace point
> of view, what makes most sense for the usecases you
> have seen? Having one consistent time base or all of these
> as we currently have? Different clocks under different
> circumstances?

It is a question of correlation. What other events do you want to correlate
your events to.

If you only want to correlate events to other events from the same source
(i.e. know the amount of time that has elapsed between two events) the best
in my opinion is a monotonic clock. You can't account for changes to the
realtime clock and it will screw up your measurements when it changes in
between two events.

Now for monotonic clocks there are two variants available MONOTONIC and
BOOTTIME. BOOTTIME will account for time that the device has been in
suspend, MONOTONIC will not. Most applications will not care for either. But
those which care about it and want to measure the duration between two
events will most likely prefer BOOTTIME, especially if the wakeup event was
caused by the device itself.

So in my opinion BOOTTIME is the most sensible default.

REALTIME should probably also be an option in case you want to correlate
your events to other events for which only a REALTIME timestamp is available
or when the absolute time matters rather than the relative time. This could
for example be rare events and you want to log time and date when they happened.

Right now I can't think of a usecase where soembody would prefer MONOTONIC
over BOOTTIME, but I'm sure there are some.

TAI and MONOTONIC_RAW are kind of the same thing. They are more immune to
changes of the exact duration of what is reported as a second. I'm sure
there are special applications that would prefer this over REALTIME and
MONOTONIC.

The only thing that is probably not really needed are the coarse variants.
But even there I could see people arguing that it serves their performance
and precision requirements better.

And to make this a lot more complicated many applications, especially in the
high-speed area, don't really care about the system time as reported by the
CPU (or a on-SoC timer) at all. They care about the time as reported by a
clock that is synchronous to the signal processing itself.

Different oscillators in a system will run at slightly different
frequencies, even if they are nominal the same frequency. So if you have 1
counter that says 1 second has elapsed another might say that 1.0001 seconds
have elapsed. If you do timestamping using a clock that is not synchronous
to your signal processing clock your results will be imprecise.

So that is something to keep in mind. Beyond just the system clock we might
want to have the ability to assign other timestamp sources in a way that is
consistent across subsystems. So that we can for example as you said
correlate events between IIO and GPIO.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Jonathan Corbet]

On Tue, 10 Jul 2018 16:46:41 +0200
Arnd Bergmann <arnd@arndb.de> 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 ;-)

It looks good to me - I guess you really can teach an old dog new
tricks :)

I've (finally) applied this, thanks.

jon

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

[Jonathan Corbet]

On Tue, 10 Jul 2018 16:46:41 +0200
Arnd Bergmann <arnd@arndb.de> 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 ;-)

It looks good to me - I guess you really can teach an old dog new
tricks :)

I've (finally) applied this, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html