Document the boottime calls - #388
Draft
nicholasberlin wants to merge 4 commits into
Draft
Conversation
Contributor
Author
|
Pushed 4d96cf0 documenting that Merge order: that statement is only true once #393 merges — it routes all access to the process-wide |
nicholasberlin
marked this pull request as draft
August 14, 2026 17:02
nicholasberlin
force-pushed
the
boottime-manpages
branch
from
August 14, 2026 17:10
4d96cf0 to
e73c9ad
Compare
biscout42
approved these changes
Aug 14, 2026
biscout42
left a comment
biscout42
left a comment
Contributor
There was a problem hiding this comment.
LGTM; I would appreciate a second review from a person with more experience in the times we collect for quark events to verify the docs.
nicholasberlin
force-pushed
the
boottime-manpages
branch
from
August 14, 2026 19:52
e73c9ad to
7728c46
Compare
Manpages for quark_update_boottime(3), quark_get_boottime(3) and quark_time_to_wallclock(3), listed in quark(7), with the HTML docs and README.md regenerated. The pages document which times are expressed since boot, that btime comes from /proc/stat and moves on clock steps, and two common ways of detecting a step.
The boottime epoch is process-wide, shared by every queue, and auditbeat updates it from one thread while others translate timestamps, which no caller-side lock can span. State explicitly that quark_update_boottime(), quark_get_boottime() and quark_time_to_wallclock() may be called from any thread without synchronization, as an exception to the queue synchronization convention in quark(7). Only true once the boottime-atomics branch merges, which makes the epoch access atomic.
The kprobe backend stamps times with a monotonic clock that does not advance during suspend. quark_time_to_wallclock() applies unchanged, but the result lags the wallclock by the total suspended time, exactly as it did before 0.8. Spell this out in quark_time_to_wallclock(3) and point QQ_MONOTONIC in quark_queue_open(3) at it, so kprobe users know the boottime calls treat both backends the same and how to compensate if they care about suspend.
nicholasberlin
force-pushed
the
boottime-manpages
branch
from
August 14, 2026 20:17
7728c46 to
5f6459d
Compare
Review feedback: make explicit which clock problem the epoch refresh solves. Slewing adjusts the wallclock and the boot clock at the same rate so the epoch never moves, only a step does.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Split out of #372; this carries only the documentation.
Manpages for quark_update_boottime(3), quark_get_boottime(3) and quark_time_to_wallclock(3), listed in quark(7), with the HTML docs and README.md regenerated. The pages document which times are expressed since boot, that btime comes from /proc/stat and moves on clock steps, and two common ways of detecting a step (polling the CLOCK_REALTIME - CLOCK_BOOTTIME delta, or a timerfd armed with TFD_TIMER_CANCEL_ON_SET). Each page carries a HISTORY section noting the calls appeared in quark 0.8, when all times handed out by quark switched from epoch to since-boot, so readers on older versions aren't misled.
mandoc -Tlint passes on the new pages.