man9: add hz(9) and hardclock(9)

[imp]

Summary

Document aspects of system time keeping. Hz is the rate that we
interrupt the system and is known and the 'tick' rate of the system. hardclock
is the routine that does various bits of timekeeping.

Obtained from: NetBSD (with FreeBSD adjustments)
Sponsored by: Netflix

[imp]

more / better / vm

[mav]

The hardclock(9) is OK to me, but hz(9) mention of two timers is out of date. As I see, there are no more platforms having separate stathz/profhz timers. Now all three routines hardclock(), statclock() and profclock() are called from the same source of handleevents() in kern_clocksource.c according to eventtimers(4), driven by whatever hardware available on specific system (periodic or one-shot, global or per-cpu, etc), but in any case trying to emulate legacy hz, stathz and profhz rates as much as possible by reprogramming the hardware via eventtimers(9) KPI.

share/man/man9/hardclock.9

39

Why is it "fake" here, while referenced as "usermode" below?

[imp]

share/man/man9/hardclock.9

39

because I was looking at the wrong function header and caught my mistake everywhere but here.

[imp]

Update to more closely match FreeBSD's implementation, as noted by
mav@. Hopefully this gets closer, but if not...

[allanjude]

share/man/man9/hz.9

49

Should this be .Fx?

[imp]

In D30802#692635, @mav wrote:

Now all three routines hardclock(), statclock() and profclock() are called from the same source of handleevents() in kern_clocksource.c according to eventtimers(4), driven by whatever hardware available on specific system (periodic or one-shot, global or per-cpu, etc), but in any case trying to emulate legacy hz, stathz and profhz rates as much as possible by reprogramming the hardware via eventtimers(9) KPI.

OK. Added detail to the man page. If you think I should add one more layer of detail like you've described here, please let me know. I was on the fence.

[imp]

share/man/man9/hz.9

49

looks like .Fx to me :)
But I changed that while you were making this comment, so great minds :)

[gnn]

LGTM

[pstef]

share/man/man9/hz.9

50

typo: single

51

As a non-native speaker, I'm not sure whether this sentence is missing a predicate or it's "structures" that "are emulated".

70

It's probably due to my ignorance, but I don't understand what "the it" here is.

100

I think we need to use a space to separate numbers from units.

[mav]

share/man/man9/hz.9

108

I think it would be good to link eventtimers(4) here, or even more synchronize them.

[imp]

basically rewrite hz(9): it now doesn't have anything but the most trivial bits
from NetBSD, so drop the NetBSD copyright on hz.9 as not relevant.

[phk]

share/man/man9/hz.9

49

This makes it sound a little bit like wall time is simply counted up here?

Maybe something like "The main clock is used to refresh timecounters(4), and ..." ?

61

stathz should not be documented, it should be removed.

To have any statistical strength, statistical sampling must sample approx 0.1% of all instructions without aliasing effects.

Running stathz at tens of MHz (~= NCORE*CPUCLOCK/1000) is maybe doable, but avoiding aliasing is impossible with the deep pipelines and telegraphic memory service of modern hardware.

That is why modern chips have hardware performance counters.

The profiled libraries should be converted to gcov instead.

[imp]

update based on phk's feedback

[imp]

is what it sometimes feels to work on the time code.