[RFC] Abstract Clock Subsystem Architecture

[pabigot]

This RFC was closed in favor of a full summary in #76335

Based on discussion in #17162 the following describes a proposed API extension that is enabled by #17155 given a few minor API changes.

Proposed Zephyr Clocks

I would like the end goal to be support for the following clocks:

• K_CLOCK_HARDWARE corresponds to the Zephyr hardware clock. It is provided by k_cycle_get(). This is a monotonic non-decreasing non-wrapping 64-bit source with zero at the instant the system hardware clock is initialized. A duration of 1 corresponds to a Zephyr cycle. The rate Z_HZ_cyc is a constant number of nominal cycles per second, but the actual rate may vary, and may not be a compile-time constant.
• K_CLOCK_SYSTEM corresponds to the the system clock. This is a monotonic non-decreasing non-wrapping 64-bit source with a zero at the instant of the zero of K_CLOCK_HARDWARE. A duration of 1 corresponds to a Zephyr tick. The rate Z_HZ_ticks is a compile-time constant, but the criteria for advancing the clock depends on CONFIG_TICKLESS_KERNEL. For a tickless kernel this source is a linear transformation scaling K_CLOCK_HARDWARE by Z_HZ_ticks / Z_HZ_cyc.
• K_CLOCK_MONOTONIC is the documented clock used for the timeout API defined in New timeout API #17155. It should be an alias for K_CLOCK_SYSTEM.
• (TBD) K_CLOCK_UPTIME corresponds to k_uptime_get(). This is a linear transformation using K_CLOCK_MONOTONIC nominal tick rate to convert to a time scale where a duration of 1 corresponds to one millisecond. This probably isn't necessary, though it might be convenient.
• (TBD) K_CLOCK_REALTIME would correspond to something that tracks civil time a la NTP. This is very TBD.

Let k_clock_id_t denote the type of the above K_CLOCK_FOO constants. Additional clock sources are possible by a Kconfig option to enable them for specific devices. This would extend the device API with functions provide frequency, gettime, and alarm capabilities for the provider. For example:

k_clock_id_t hires = counter_get_clock(dev);

would provide a clock id for timeouts that use that counter to control their duration, assuming the counter identified by dev was configured to support use as a clock source. Other non-counter providers may exist as well. Any clock id could be used in the following generic API:

u64_t k_clock_get(k_clock_id_t id);
u32_t k_clock_frequency(k_clock_id_t id);
k_timeout_t k_clock_convert(k_timeout_t t, k_clock_id id);

We then have:

• k_clock_get(K_CLOCK_HARDWARE) == k_cycle_get()
• k_clock_get(K_CLOCK_UPTIME) == k_uptime_get()
• k_clock_get(K_CLOCK_SYSTEM) returns the tick counter (curr_tick)

Currently the opaque k_ticks_t value encodes a count in ticks that is either relative or absolute. In the future it should also encode the id of the clock to which it applies, so we should be able to use z_add_timeout and have that record on the queue for the corresponding clock.

We will also need API extensions:

• Every K_TIMEOUT_suffix(args...) will have a corresponding K_CLOCK_TIMEOUT_suffix(id, args...) which implements it for clocks other than K_CLOCK_MONOTONIC.
• All k_?s_to_ticks_suffix(args...) will have a corresponding k_?s_to_clock_ticks_suffix(id, args...) which implements the conversion between time and clock values/durations using the rate for a specific clock.
• A new k_delay(k_timeout_t t) that extends the capability of k_sleep() to other clock sources.

[jukkar]

For gPTP (generalized Precicion Time Protocol) enabled system, there is a high accuracy clock source, with nanosecond accuracy, provided by Ethernet controller. For example frdm-k64f (eth_mcux driver) and sam-e70-xplained (eth_sam_gmac driver) boards have support for gPTP.
This clock is currently accessed only by gPTP code, which uses PTP driver for access (API at include/ptp_clock.h). I am not sure if this clock source would need to be accessed by other system than gPTP, so just fyi atm.

[pabigot]

If that clock provides high-accuracy realtime (e.g. UTC or TA1) it could certainly be useful.

[pizi-nordic]

Some questions/comments:

• Are we going to have alarms set on given clock source (including K_CLOCK_HARDWARE) and custom-clock sources? If so, who will be responsible for dealing with low-level constraints (example: I cannot set alarm earlier that X clock from now).
• What we should do if given clock is not available (for example when system is going into low power state) but there is alarm set on that clock?
• Are we going to inform the application about "clock lost" / "clock restored" event? Or rather application should "lock" given clock source to ensure that it will be ticking all the time?
• Have you considered Automatic wake-up from system-level sleep modes #14306 in the design? Ideally we should be able to 'move' wake-up event from one clock source to another.

[sslupsky]

I have not read through all of the related issues but one thing appears to be absent from this discussion, which is power consumption. I've been working with the SAMD21 and Zephyr recently and have discovered that the clock domain used for the system timers is the same clock used to clock the CPU. That is a problem for a low power application. To achieve low power on the SAMD21, the SAMD21 RTC needs to be clocked by the 32KHz lower power clock source. This implies another clock domain. Has anyone considered the implications of this with respect to this work?

[pabigot]

This implies another clock domain. Has anyone considered the implications of this with respect to this work?

Yes. Initial thoughts, at least. It depends on the second TBD in #19282 relating to a domain model for clocks, which considers fixed rates, monotonicity, and the effect of discontinuities when mapping between domains.

[ghost]

For gPTP (generalized Precicion Time Protocol) enabled system, there is a high accuracy clock source [...] not sure if this clock source would need to be accessed by other system than gPTP, so just fyi atm.

I'd vote in favor. This is what Linux does under the notion of "dynamic clocks", see clock_getres(2)

[cfriedt]

@nordic-krch Some of the ideas in your Enhancement/RFC already seem to be implemented by now,

Ah, I see - this one should probably be assigned to me. Is it ok if I take this one, @nordic-krch ? It was originally created by Peter.

zephyr/lib/posix/clock.c allows for access to (non-settable) CLOCK_MONOTONIC and (settable) CLOCK_REALTIME, currently both based on uptime_ticks(), ie. scaled in a POSIX compliant way similarly to what you propose as K_CLOCK_UPTIME/K_CLOCK_REALTIME. In principle I'd say these clocks could also be adjusted/compensated w/o discontinuities similarly to adjtime(3).

This is very much a WIP area, as I'm literally tying in the pieces for CLOCK_REALTIME as I write this comment.

The monotonic clock should likely not be adjusted, but the realtime clock, certainly. For something like adjtime(3) to work, we would need a system-wide service.

Would it make sense to try and map constants to those defined in POSIX and/or Linux, see clock_getres(2), e.g.

• K_CLOCK_UPTIME -> K_CLOCK_MONOTONIC;
• K_CLOCK_SYSTEM -> K_CLOCK_MONOTONIC_RAW;
• K_CLOCK_HARDWARE -> K_CLOCK_MONOTONIC_COARSE?

For now, I would suggest we stick to monotonic and real-time clocks for now. Advanced features will be added to the agenda as well.

This would simplify adding those to Zephyr's clock_gettime() implementation in a readable and obvious way.

Sort of - likely what should be done is that a separate but parallel Zephyr clock subsystem / library / whatever is needed, and then the posix layer should be a very thin layer that wraps around it. However, there are some potentially non-obvious things, like

• when there are multiple clock sources, how do we choose which is monotonic, real, etc
  • my take on this is to use DT chosen nodes
• what if the system designer does not want to use the default system clock for the monotonic clock?
  • my take on this is to use DT chosen nodes
• how do we make a queryable interface for clock resolution?
  • probably need to specify resolution via DT again

@cfriedt Maybe it makes sense to close this one and continue discussion in #40099 (or the other way round). It's hard to discuss HF clock extension w/o also discussing multiple clocks.

I'd prefer to leave this open as well, but thanks for commenting on this ticket again, because it's directly relevant.

[cfriedt]

The monotonic clock should likely not be adjusted,

@cfriedt: Then it should probably be K_CLOCK_MONOTONIC_RAW for compatibility with Linux? CLOCK_MONOTONIC is adjustable (but not settable) by default in POSIX if I'm not mistaken. See clock_getres(2): "The CLOCK_MONOTONIC clock is [...] affected by the incremental adjustments performed by adjtime(3) and NTP."

My guess is that you're looking at Linux man pages.

Would be better to stick with POSIX via

https://pubs.opengroup.org/onlinepubs/9699919799/

Not 100% sure ATM if adjusting monotonic is part of POSIX. We could make it a kconfig option for a deviation though, and support it anyway.

If we were to support adjustments on monotonic on the Zephyr side, it would very likely need to be done outside of the existing k_uptime_get() machinery, but at least there is no spec to restrict that.

[cfriedt]

@fgrandel - This API is mainly for hardware real-time clocks, and less for e.g. clock_gettime(CLOCK_REALTIME).

.. ah, I see Bjarki got to it already.

[bjarki-andreasen]

@fgrandel

I would suggest you focus this issue on what you actually want to achieve, instead of writing all you grievances in lists in comments. Its hard to follow and respond to concisely, leading to repetitions of answers and lack of focus.

Put simply, The RTC and Counter APIs are the lowest level APIs for the hardware (as already stated). For this reason, there is an inherent contradiction and possible lack of understanding when you state:

strip down rtc.h to a pure RTC HW driver and move the rest to higher-layer or hardware-agnostic abstractions
This is already the case. There is nothing to strip back or move here.

Higher level abstractions are just that, higher level, built upon the lower levels.

Please read the documentation regarding API API Status and Guidelines, specifically the API Lifetime section, then look at a few of the existing RTC device drivers RTC Drivers to gain an understanding of how the API is used and what the hardware capabilities are. Lastly, look into what the rtc-emul driver is actually used for Hint

This should address most of your points, and help focus this issue.

[ghost]

I would suggest you focus this issue on what you actually want to achieve

@bjarki-trackunit You are right, the rtc.h discussion belongs in separate issues (I opened some as you've seen). Unfortunately it landed here because of my initial misunderstanding about the role of rtc.h. With hindsight the error is obvious.

UPDATE: rtc.h-related discussion entries which turned out to be irrelevant wrt the clock subsystem architecture were hidden from this RFC. If you wish you can hide yours as well then focus of this RFC will be completely restored.

[ghost]

Closed in favor of #76335 which summarizes results from this and prior discussions for easier reference and visibility. Feel free to re-open if you think that this RFC still has merit on its own.