STRUCT CLOCKSOURCE(9)

💅 struct clocksource(9) — like, the Kernel API Manual, section 9, bestie 💖

okay so picture this: you're scrolling through the kernel docs, right, and you hit struct clocksource — and it's literally the hardware abstraction for a free running counter. it mostly gives you state-free accessors to the underlying hardware. it's the structure used for system time. main character energy, no cap 👑

---

✨ NAME ✨

struct clocksource — hardware abstraction for a free running counter 🕰️

it provides mostly state-free accessors to the underlying hardware. this is the structure used for system time. periodt.

---

🦋 SYNOPSIS 🦋

struct clocksource {
    u64 (*read)(struct clocksource *cs);
    u64 mask;
    u32 mult;
    u32 shift;
    u64 max_idle_ns;
    u32 maxadj;
    u64 max_cycles;
    u64 max_raw_delta;
    const char              *name;
    struct list_head        list;
    u32 freq_khz;
    int rating;
    enum clocksource_ids    id;
    enum vdso_clock_mode    vdso_clock_mode;
    unsigned long           flags;
    struct clocksource_base *base;
    u64 (*read_snapshot)(struct clocksource *cs, struct
clocksource_hw_snapshot *chs);
    int (*enable)(struct clocksource *cs);
    void (*disable)(struct clocksource *cs);
    void (*suspend)(struct clocksource *cs);
    void (*resume)(struct clocksource *cs);
    void (*mark_unstable)(struct clocksource *cs);
    void (*tick_stable)(struct clocksource *cs);
 };

---

🎀 Members 🎀

time to meet the cast, bestie — every single one of them, i'm not skipping anybody 🙈

• read — returns a cycle value, and passes the clocksource as its argument. the little guy that does the reading ✨
• mask — bitmask for two's complement subtraction of non 64 bit counters
• mult — cycle to nanosecond multiplier
• shift — cycle to nanosecond divisor (power of two)
• max_idle_ns — maximum idle time permitted by the clocksource, in nsecs
• maxadj — maximum adjustment value to mult (like ~11%)
• max_cycles — maximum safe cycle value which won't overflow on multiplication
• max_raw_delta — maximum safe delta value for negative motion detection
• name — pointer to clocksource name
• list — list head for registration (internal 👀)
• freq_khz — clocksource frequency in khz.
• rating — rating value for selection (higher is better). and bestie, to avoid rating inflation the following list should give you a guide as to how to assign your clocksource a rating:
  • 1-99: unfit for real use. only available for bootup and testing purposes.
  • 100-199: base level usability. functional for real use, but not desired.
  • 200-299: good. a correct and usable clocksource.
  • 300-399: desired. a reasonably fast and accurate clocksource.
  • 400-499: perfect. the ideal clocksource. a must-use where available. 💯
• id — defaults to CSID_GENERIC. the id value is captured in certain snapshot functions to allow callers to validate the clocksource from which the snapshot was taken
• flags — flags describing special properties
• base — hardware abstraction for clock on which a clocksource is based
• read_snapshot — extended read function for clocksources such as kvmclock or the Hyper-V scaled TSC where the actual clocksource value for timekeeping is calculated from an underlying hardware counter. returns the timekeeping relevant cycle value and stores the raw value of the underlying counter from which it was calculated — including the clocksource ID of that counter — in the clocksource hardware snapshot. like, it's giving two-for-one 🌸
• enable — optional function to enable the clocksource
• disable — optional function to disable the clocksource
• suspend — optional suspend function for the clocksource
• resume — optional resume function for the clocksource
• mark_unstable — optional function to inform the clocksource driver that the watchdog marked the clocksource unstable 💀
• tick_stable — optional function called periodically from the watchdog code to provide stable synchronization points

---

⭐ Note ⭐

this struct is not used in hotpathes of the timekeeping code, because the timekeeper caches the hot path fields in its own data structure — so no cache line alignment is required, okay? don't stress about it 🫶

the pointer to the clocksource itself is handed to the read callback. so if you need extra information there, you can wrap struct clocksource into your own struct. and depending on the amount of information you need, you should consider to cache line align that structure. iykyk 💅

---

🌈 SEE ALSO 🌈

• Kernel file ./include/linux/clocksource.h struct
• clocksource_hw_snapshot(9)
• clocksource_khz2mult(9)
• clocksource_hz2mult(9)
• clocksource_cyc2ns(9)
• struct clocksource_base(9)

---

and that's the whole page, bestie! 🎉 this one lives in ./include/linux, it's dated October 2026, and its official little nametag is struct clocksource(9) — go forth and keep time, you absolute icon 👑💜🍓