STRUCT CYC_HIST(9)

✨ struct cyc_hist(9) ✨

okay bestie, so this is a page straight outta the Kernel API Manual 💅 and it's all about struct cyc_hist — that's literally the (CPU) cycle histogram for a basic block. yes. we're doing kernel profiling today. put ur hair up, it's gonna be cute 🎀

---

🌸 NAME 🌸

struct cyc_hist — the (CPU) cycle histogram for a basic block. that's her. that's the whole vibe. 🦋

---

✨ SYNOPSIS ✨

struct cyc_hist {
    u64 start;
    u64 cycles;
    u64 cycles_aggr;
    u64 cycles_max;
    u64 cycles_min;
    s64 cycles_spark[NUM_SPARKS];
    u32 num;
    u32 num_aggr;
    u8 have_start;
    u16 reset;
 };

look at her. all those little fields. so organized. we love a structured queen 👑

---

🫶 Members 🫶

• start — start address of the current block (if we know it 👀).
• cycles — the sum of cycles for the longest basic block. the main character block, if u will.
• cycles_aggr — total cycles for this address. the whole squad's contribution 💖
• cycles_max — max cycles for this address. the overachiever.
• cycles_min — min cycles for this address. the lowkey one.
• cycles_spark — history of cycles for the longest basic block ✨ sparkle sparkle ✨
• num — number of samples for the longest basic block.
• num_aggr — total number of samples for this address.
• have_start — whether the current branch info actually has a start address. a yes/no moment.
• reset — number of resets due to a different start address. (she's been through some things 😭)

---

💜 Description 💜

so here's the tea 🍓: if a sample has branch_stack and cycles info, it can construct basic blocks between two adjacent branches. it'd have start and end addresses — but sometimes the start address just isn't available, no cap. so instead, the cycles get accounted at the end address. and if multiple basic blocks end at the same address? it takes the longest one. longest block wins, periodt. 👑

the start, cycles, cycles_spark and num fields are used for the longest block only. all the other fields are used for all cases. don't mix that up bestie, iykyk 🙈

also, see __symbol__account_cycles. go look at her. she knows things.

---

🌈 SEE ALSO 🌈

• Kernel file ./tools/perf/util/annotate.h — that's where the lore lives 📖
• struct sym_hist(9)
• struct annotated_source(9)
• struct annotated_branch(9)
• struct annotated_op_loc(9)
• struct annotated_insn_loc(9)
• struct annotated_basic_block(9)

---

k that's the whole page, u ate that fr fr 🔥 and a cute little sign-off for u: this one lives in ./tools/perf/util and it's dated October 2026 — iconic, timeless, exactly as the kernel gods intended 💖✨🎀