STRUCT TMIGR_GROUP(9)

👑 struct tmigr_group(9) 👑

okay bestie, so this is a page straight out of the Kernel API Manual — we're talking kernel internals, timer stuff, the whole vibe. and the star of the show today is struct tmigr_group, aka the timer migration hierarchy group ✨ think of it as one little clique in a whole friendship-hierarchy of timer groups, fr fr.

---

🌸 NAME 🌸

struct tmigr_group — the timer migration hierarchy group. that's her. that's the icon.

---

✨ SYNOPSIS ✨

struct tmigr_group {
    raw_spinlock_t lock;
    struct tmigr_group      *parent;
    struct tmigr_event      groupevt;
    u64 next_expiry;
    struct timerqueue_head  events;
    atomic_t migr_state;
    unsigned int            level;
    int numa_node;
    unsigned int            num_children;
    u8 groupmask;
    struct list_head        list;
 };

like, look at her. every field is doing something. no filler. periodt 💅

---

🫶 Members 🫶

okay so let's go field by field, no skipping, i promise 🎀

• lock — this is the lock that protects the event information AND the group hierarchy information while setup is happening. guard the vibes 🔒
• parent — pointer to the parent group, obviously. the way it works: this pointer gets updated when a new hierarchy level is added because of a CPU coming online the first time. once it's set, the pointer will not be removed or updated — she's committed, no take-backs 💖

and here's the nuance, bestie: when you access the parent pointer lockless just to decide whether to abort a propagation or not, it's fine, not a problem. the worst outcome is an unnecessary/early CPU wake up — literally the gentlest failure ever, nbd. BUT do not access the parent pointer several times in the same 'action' (like activation, deactivation, check for remote expiry,...) without holding the lock, because it is not ensured that the value will not change. highkey important, don't do it 🙈

• groupevt — the next event of the group, and it's only used when the group is !active. when it is used, the group event is queued into the parent timer queue. also: the Ignore bit of groupevt is set when the group is active. iykyk 👑
• next_expiry — base monotonic expiry time of the next event of the group. it's used for the racy lockless check of whether a remote expiry is required. and unlike some of these fields... it is always reliable ⭐ (yes she's the trustworthy one)
• events — timer queue for child events queued in the group. the little waiting room 🌈
• migr_state — state of the group (see union tmigr_state). go read that page too, bestie, i'm not kidding 🦋
• level — hierarchy level of the group. required during setup only 🎀
• numa_node — required for setup only, to make sure CPU and low level group information is NUMA local. it is set to the NUMA node as long as the group level is per NUMA node (level < tmigr_crossnode_level); otherwise it is set to NUMA_NO_NODE. so it's like, conditional residency 💀
• num_children — counter of group children, there to make sure the group is only filled with TMIGR_CHILDREN_PER_GROUP. required for setup only 🔥
• groupmask — mask of the group in the parent group. it is set during setup and will never change; and it can be read lockless — icon behaviour, honestly 👑
• list — list head that gets added to the per level tmigr_level_list. it's required during setup when a new group needs to be connected to the existing hierarchy groups — the linking-up moment, we love to see it 🫶

---

💜 SEE ALSO 💜

• Kernel file ./kernel/time/timer_migration.h
• struct tmigr_hierarchy(9)
• struct tmigr_event(9)
• struct tmigr_cpu(9)
• union tmigr_state(9)

go read them, they're all connected, it's giving cinematic universe 🧚

---

okay that's the whole page, bestie, you ate that 🍓 mwah 💋

sign-off time: this beauty lives in ./kernel/time, and it's dated October 2026 — so yeah, mark your calendar, the struct is booked and busy 📅✨