If that's the case, this description is misleading. How about this:

The boottime is computed by the current time minus uptime.
When those two values change independently, the boottime
is re-calculated accordingly.
The
.Xr sysctl 8
.Va kern.boottime
returns this computed value.

Boot time is not computed. It is stored and adjusted. Current time is computed.

Again, it's stored and adjusted. Current time is computed. This wording can easily be misconstrued to mean that boot time is computed often.

How about this?

The current time is computed by boottime + uptime.
The uptime increases monotonically.
When the current time is adjusted, the boottime is adjusted
correspondingly, to maintain equivalence.
Therefore, boottime is not invariant and should not be cached.
The
.Xr sysctl 8
.Va kern.boottime
returns the boottime value.

Again, it's stored and adjusted. Current time is computed. This wording can easily be misconstrued to mean that boot time is computed often.

It appears the wording from your initial comment -- though perhaps not the actual change -- can also be misconstrued that way, because I misconstrued it that way. :-p

Boottime is set when the first time is obtained.
The current time is computed by boottime + uptime.
The uptime increases monotonically.
When the current time is set, boottime is adjusted to maintain equivalence.
Therefore, boottime is not invariant and should not be cached.
The
.Xr sysctl 8
.Va kern.boottime
returns the boottime value.

Do you think that might be clearer?

Hmmm, I take your meaning. Is the following any better?

System boot time. Adjusted when time is set so the current time always is the sum of the up time and the boot time.

This is clear to me.

How about,

System boot time: adjusted when current time is adjusted, see time.9

IMO a single line cannot give the topic of how boot epoch (which boot time in fact is) enough explanation without being incomplete or imprecise to possibly confuse the reader. And that boot epoch is what is adjusted when system time is changed or adjusted. That boot time is not immutable must be understood.

Or how about this?

System boot time: mutable, adjusted when current time is adjusted, see time.9

It's enough information to say that it's not immutable, that it's adjusted when the clock is adjusted, and for details read the man page.

I think that's how I'd approach it.

"when the first time is obtained" ; did you mean "the first time it is obtained"?

Otherwise, I concur with @cy, this is pretty clear.

s/time.9/time(9)/g, since we generally refer to manpages with the section in parens, even if the file itself uses a .section suffix.

When the current time is set, adjusted by ntpd, or when a new time is read when
the system resumes,

When the current time is set, adjusted by
.Xr ntpd 8 ,
or updated when the system resumes,

"acround" is not a cromulent word. :-)

"time" => "the current time"

"vaires" => "varies"

If we want to be really nit-picky: We only set it at boot if the hardware has a RTC+driver.

(I think we dropped the "set it from the filesystem", right ?)

... read from RTC ... ?

We have not.

Actually: What precisely happens at resume ?

We get a new RTC timestamp, but doing "boottime = new_time - uptime" would be bogus ?

I guess we should be recalculating uptime on resume and leave the boottime intact ?

I went with a simpler string and confined things to the comment since these strings don't have much visibility.

This time is initially set when the system boots, either from the RTC, or
from a time estimated from the system's root filesystem.

Except, what does "a time estimated from the system's root filesystem" refer to?

"Estimated system boottime");

(It's not a sentence, so no period is required.)

This is what happens. Uptime doesn't tick while we're suspended. so if we go to sleep with 1hr of up time and boot time of Jan 1 at 12:34pm and wake up on Jan 15th at 4:45am, the new boot time is set to Jan 15 at 3:45am. I'd like to document current behavior in this code review.

We can debate whether this is actually the right thing to do. :) ACPI and APM went back and forth on this back in the day. And there was much angst about what to do about timers across this event. It's not clear that this change would be better or worse than the current behavior.

For UFS, it's set to the time recorded in the superblock (which is time of last unmount).
For everything else, nothing (so if you use ZFS and have not RTC, you'll see 1970 times). I don't know if this was lost in the OpenZFS import, or was never there.
It's supposed to be 'whatever the filesystem set mp->mnt_time to' but only UFS does this trick.

This time is initially set when the system boots, either from the RTC, or
from a time estimated from the system's root filesystem.

The "is set initially" => "is initially set", and the comma after "boots", are still pending.

There's a PR for this: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=236702. Both Linux and OSX count sleep as part of uptime, and I'd argue that's the right thing to do: when sleeping the system is still up, it's just conserving power.

Yes. Unless stepping uptime causes issues for pending timeout... the += part of the change is easy, but making sure it all works after is harder... And at the moment, suspend and resume are totally broken on my laptop, so I can't test it. But regardless, beyond the scope of this change.