Re: Clarification of CLOCK_MONOTONIC

[Greg Troxel <gdt%lexort.com@localhost>]

Taylor R Campbell <riastradh%NetBSD.org@localhost> writes:

> I think it is arguable whether CLOCK_MONOTONIC _should_ include or
> exclude time suspended.  I'm not sure NetBSD is currently consistent
> across ports about this.

Not sure what you mean by should:
  posix requires that suspended time be included or excluded, or
  posix is wrong

> Either way, I'm tempted to suggest that for CLOCK_MONOTONIC we add a
> uniform random nanosecond-resolution offset in [0, 2^62 sec) some time
> at boot, maybe before userland starts or after /etc/rc.d/entropy runs.
> It'll still meet the POSIX.1-2024 requirements this way, and it will
> really emphasize the unspecified nature of the reference point, and
> help shake out bugs with 32-bit time_t truncation.  The interval of
> possible offsets is limited to guarantee that it won't overflow a
> signed 64-bit number of seconds for hosts with an uptime shorter than
> 146 billion years, which I think is a safe assumption.

that seems interesting, but also it seems the history of odd but
within-spec behavior is that it finds a lot of trouble and we turn it
off.   Maybe ifdef to start?

> * POSIX.1-2024
>
> - CLOCK_MONOTONIC counts time since unspecified epoch, without a clear
>   reference to time suspended.  Only requirements are [POSIXTIMEH]
>   [POSIXCLOCKGETRES]:
>
>   . cannot be set via clock_settime()
>   . cannot have backward clock jumps
>   . maximum possible clock jump shall be implementation-defined and
>     must be documented
>   . measured in seconds and nanoseconds
>   . reference point does not change after system start-up time
>
>   Not changing the reference point after system start-up time could be
>   construed to require including time suspended.  But it's arguable;
>   the language is certainly not explicit about the point.

I think it's clear from "max possible clock jump must be documented"
that they were not thinking about suspend/resume.

But, "time since some unspecified epoch" means what it says, and any
particular run of a system must pick a specific epoch.  After
suspend/resume, the spec doesn't allow the to change, and thus future
return values must be relative to that original choice, implying 
"time suspended counts".*  Changing the epoch because of suspend is as
reasonable as changing it because of a full moon.

* There's the edge case of suspend/resume after the kernel code reads the clock
  and before syscall return, but we're not talking about that.

> * macOS
>
> By hearsay [MOZILLATIME], since I am having trouble finding macOS man
> pages on the web, it sounds like:
>
> - CLOCK_MONOTONIC counts time since boot, incl. suspend

Yes, the man page on macOS 15 says that.  

> - CLOCK_MONOTONIC_RAW counts time running since boot, excl. suspend

On macOS 15, it says it is like CLOCK_MONOTONIC, but is "unaffected by
frequency or time adjustments".

CLOCK_UPTIME_RAW (there is no CLOCK_UPTIME) does not increment during
sleep.


> History: no idea but macOS probably exposed this distinction to
> applications long before anyone else

And, there are also _APPROX and it seems more complicated than other
systems.


I see Linux as the odd one out and also noncompliant to the spec in this
case.


I think the really hard call is about this "affected by adjtime".  POSIX
is clear about "time since an arbitrary epoch" but then adds this
not-backwards rule.  But when the time is set back because timekeeping
is bad, separately from always increasing a us per call, I think it's
fair to say that the value is 'real_time - assigned_epoch'.

But, if time is set back because it was wrong at boot, then the value
shouldn't be adjusted.

Overall I lean to not accepting steps and accepting adjtime.
CLOCK_MONOTONIC should definitely increase across suspend.


So I think NetBSD should:

  - fix any ports where CLOCK_MONOTONIC doesn't count across suspend

  - not try to exclude adjtime actions on this clock.  e.g. if a
    negative adjtime happens and instead of 1 ms the time goes forward
    990 us instead, that's fine to add into the CLOCK_MONOTONIC value.

  - continue to not change the CLOCK_MONOTONIC clock on settimeofday

  - adjust the documentation to be clear about suspend

  - adjust the documentation to be clear about ignoring settimeofday and
    being ok with adjtime.


Really systems should have electronic frequency control on their
crystals instead, and adjtime and the kernel clock PLL stuff is just a
replacement for that.  That's why I said what I did about adjtime.