STRUCT CYCLECOUNTER(9)

📦 version 7.3.1, in nixpkgs unstable

💖 struct cyclecounter(9) 💖

okay so this is from the Kernel API Manual (yes the actual kernel, bestie, we're in the big leagues now) and it's lowkey one of those pages that makes you feel smarter just reading it. let's get into it ✨

🌸 NAME 🌸

struct cyclecounter — hardware abstraction for a free running counter 🎀

so basically it gives you completely state-free accessors to the underlying hardware. like, no state, none, she's just vibing and reading the raw thing for you 💅

but real talk — depending on which hardware it reads, the cycle counter may wrap around quickly. yes, that fast. so don't get comfy 🫶

and the locking rules (if necessary, key phrase if necessary) have to be defined by the implementor and the user of specific instances of this API. not us, not the kernel, you. no cap. 🔥

✨ SYNOPSIS ✨

struct cyclecounter {
    u64 (*read)(struct cyclecounter *cc);
    u64 mask;
    u32 mult;
    u32 shift;
 };

look at her. four little members. iconic. 👑

🦋 Members 🦋

  • read — returns the current cycle value. she reads. that's the whole job. main character energy honestly 🌈
  • mask — bitmask for two's complement subtraction of non-64-bit counters, see the CYCLECOUNTER_MASK helper macro. so if your counter isn't a full 64 bits, this is how the subtraction math stays correct 💖
  • mult — cycle to nanosecond multiplier. multiplying, slay 🎀
  • shift — cycle to nanosecond divisor (power of two, don't forget that part, it matters 💀)

🌟 SEE ALSO 🌟

Kernel file ./include/linux/timecounter.h — plus her whole friend group:

go read them, iykyk 🧚

heads up bestie: that wrap-around warning up in NAME is fr fr — this thing can flip over fast depending on the hardware, and the locking is your problem to define. not me, not the kernel. you. 🙈

and that's the page!! sourced straight from ./include/linux, dated October 2026, filed under struct cyclecounter(9) 💜 🦋 ⭐

muah, go read your cycle counters responsibly 💅✨🍓

📦 where this page comes from