Page MenuHomeFreeBSD

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

Authored by imp on Jun 17 2021, 3:38 PM.

Details

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

Diff Detail

Repository
R10 FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

imp requested review of this revision.Jun 17 2021, 3:38 PM

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
38

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

share/man/man9/hardclock.9
38

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

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

allanjude added inline comments.
share/man/man9/hz.9
48

Should this be .Fx?

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 marked 2 inline comments as done.Jun 17 2021, 4:53 PM
imp added inline comments.
share/man/man9/hz.9
48

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

gnn added a subscriber: gnn.

LGTM

This revision is now accepted and ready to land.Jun 17 2021, 5:00 PM
pstef added inline comments.
share/man/man9/hz.9
49

typo: single

50

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

69

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

99

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

share/man/man9/hz.9
107

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

imp marked an inline comment as done.

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.

This revision now requires review to proceed.Jun 17 2021, 8:46 PM
This revision is now accepted and ready to land.Jun 18 2021, 1:31 AM
share/man/man9/hz.9
48

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 ..." ?

60

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.

update based on phk's feedback

This revision now requires review to proceed.Jun 18 2021, 1:29 PM
This revision is now accepted and ready to land.Jun 18 2021, 1:44 PM
This revision was automatically updated to reflect the committed changes.


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