You have an either without an or any more.

While it is true that historically we used the same physical timer to drive statclock and profclock, it might be clearer to the reader to actually describe them as three separate logical clocks and then maybe add a note after the description of statclock and profclock to say that historically these two clocks were driven by the same physical timer. I think it will also fix Jess's comment about the missing or.

Phab's UI won't let me select the body of text to do an suggestion since there's already a comment, so I'll just do a suggestion by hand:

A second clock running at
.Va stathz
gathers statistics on the system and its processes.
It computes values for
...
.Xr top 1 .
.Pp
Finally, a third clock runs at
.Vt profhz
to sample user program counter values for profiling purposes.
This profiling clock has been replaced by the more functional
.Xr hwpmc 4
and may be removed in a future version of
.Fx .

Maybe it's not even worth mentioning the historical note that statclock and profclock use the same underlying timer, or that profclock doesn't run except when it is enabled by at least one process requesting profiling. If we did, maybe we would add it in a separate '.Sh IMPLEMENTATION NOTES' section. Also, I snuck in a fuller deprecation warning for profclock. :)

Discussed on IRC and @kib pointed out in email - this is not correct.

I think "up to .Va hz times per second" would be accurate, but I'm not sure if there's more context we should offer.

hardclock needs to be updated, and I'll put the details there.
Forgot to update this based on IRC earlier, and kib's comments made me revisit.
There's a lot of details that we try to do as well for when we call it when it isn't that many times a second, but that detail is best held elsewhere.
thanks.

In the hardclock.9 page, I'll say "the sum of cnt over a second will tend to be about hz" or something similar.... It looks like we make our best guesses on ticks, but nothing really cares how exact we are on that for time keeping, within certain limits dictated by overflow and such.

I think something along these lines would be more accurate:

This routine is called with the varying frequency, enough to handle events fired from it, in time. Highest frequency is hz, and current implementation ensures that the function is called at least once in a second if CPU is idle.

s/clock/mechanism/

I think that's correct, but probably not quite the right way to express it, essentially hardclock is called on an upcoming tick 1/hz boundry when necessary. But anyway this is outside of the scope of hz.9.

As an aside I brought up removing -pg profiling support last year (https://lists.freebsd.org/pipermail/freebsd-current/2020-January/075105.html)

Interesting, I wonder if we can eliminate the at least once per second?

Yea. I saw that and wasn't sure what to think, so said nothing.
Is that where we turned off PROFILE by default? Or was that prior?

No. I don't think so.

1. timecounters generally wrap in the few second range these days, and we have to poll them faster than that..
2. time_second needs to be bumped once a second.

There may be other reasons as well. hardclock clocks polling devices and queueing the end of epoch processing (If I'm reading the code right, I just took a quick glance). There may be other reasons I'm unaware of that kib@ or mav@ could expound upon.

Is that where we turned off PROFILE by default? Or was that prior?

We haven't turned PROFILE off by default yet.

Yes, the main reason is the timecounters. They are set up to return uint32_t value which we allow to wrap in approximately a second. In particular, this is why we have TSC-low timecounter which shifts TSC value right.

And this means that we should call tc_windup() once in half-second, actually, not once in a second. We indeed do, see getnextcpuevent().

Also this frequency determines how fast we can reclaim resources when epochs end, which imp noted above.

On the other hand, this 'once in half-second' really need to occur once in half-second globally, not on each CPU. Right now we do not utilize this possible optimization.

I know I called this "stat clock" earlier, so this is my bad.

Do we want to include ps(1) and top(1) here since we Xr them inline now?