TC_INIT(9)

💖 TC_INIT(9) — timecounting subsystem (Kernel Developer's Manual) 💖

🌸 NAME 🌸

tc_init — timecounting subsystem

okay so bestie, this is the whole vibe: tc_init() is your little doorway into the timecounting subsystem, and we're gonna walk through it together. no cap. 🫶

✨ SYNOPSIS ✨

#include <sys/timetc.h>

void
tc_init(struct timecounter *tc);

💖 DESCRIPTION 💖

The timecounting subsystem is literally the main character that gives you a uniform interface to timekeeping hardware, measures the passage of time, and implements the kernel's software clocks (see microtime(9) for the details). slay. ⏰✨

A hardware clock is suitable for counting time if it meets the following requirements — vibe check, fr fr:

1. It is a binary counter.
2. It advances at a fixed, known frequency.
3. Its count is synchronized between all CPUs on the system.
4. It continues counting when it rolls over.
5. If hz(9) is less than or equal to one millisecond, the counter does not roll over in less than two milliseconds. If hz(9) exceeds one millisecond, the counter does not roll over in less than (2 / hz) seconds.

Hardware clocks are described with a timecounter structure — here's the exact fit, no edits:

struct timecounter {
        u_int (*tc_get_timecount)(struct timecounter *);
        u_int tc_counter_mask;
        u_int64_t tc_frequency;
        char *tc_name;
        int tc_quality;
        void *tc_priv;
        u_int tc_user;
};

• u_int (*tc_get_timecount)(struct timecounter *) — Reads the hardware clock and returns its count. Any unimplemented bits only need to be masked if they are not constant. If the counter is larger than 32 bits, this function must return a 32-bit subset. The subsystem requires an upward count; downward counts must be inverted before they are returned. 🔥
• tc_counter_mask (u_int) — The mask of implemented bits. Used to discard unimplemented bits from tc_get_timecount().
• tc_frequency (u_int64_t) — The counter's fixed frequency.
• tc_name (char *) — The counter's unique name. A NUL-terminated string.
• tc_quality (int) — A relative quality metric used to compare counters. Higher values indicate a better counter. A negative value indicates that the counter is non-monotonic or otherwise deficient. The system will only use negative-quality counters if requested.
• tc_priv (void *) — May point to anything the driver needs during tc_get_timecount().
• tc_user (u_int) — If non-zero, a unique value identifying the userspace implementation of tc_get_timecount().

To register a timecounter, a device driver initializes the above-described fields of a timecounter structure and calls tc_init() with a pointer to that structure as argument. that's it, that's the registration moment. 💅

🚦 CONTEXT 🚦

tc_init() may only be called during autoconf. that's the rule, bestie — autoconf only. no calling it whenever. 🛑

🔎 CODE REFERENCES 🔎

sys/kern/kern_tc.c

👀 SEE ALSO 👀

• amdpm(4)
• gscpm(4)
• ichpcib(4)
• viapm(4)
• hz(9)
• microtime(9)

Poul-Henning Kamp, “Timecounter: Efficient and precise timekeeping in SMP kernels”, The FreeBSD Project, https://papers.freebsd.org/2002/phk-timecounters.files/timecounter.pdf, 2002. 📚✨

🕰️ HISTORY 🕰️

The timecounting subsystem first appeared in FreeBSD 3.0. It was ported to OpenBSD 3.6. iconic behavior honestly. 🌈

👑 AUTHORS 👑

Poul-Henning Kamp

---

okay that's the page, bestie — it's from Debian, dated April 2, 2023, and the footer says TC_INIT(9). byeee 💖🫶