STRUCT ANNOTATED_BRANCH(9)

✨ NAME ✨

struct annotated_branch — the whole entire lowdown on basic blocks and IPC info for a symbol, bestie 💅

okay so real quick before we dive in: this is a Kernel API Manual page (yes, the (9) girlies, section 9, kernel API) and honestly? she's giving main character energy. let's get into it 🫶

---

🌸 SYNOPSIS 🌸

struct annotated_branch {
    u64 hit_cycles;
    u64 hit_insn;
    unsigned int            total_insn;
    unsigned int            cover_insn;
    struct cyc_hist         *cycles_hist;
    u64 max_coverage;
    u64 *br_cntr;
 };

no cap, that's the whole shape of her. now let's meet the members one by one 🎀

---

💅 Members 💅

• hit_cycles — total executed cycles. literally the cycle count, periodt. 🔥
• hit_insn — total number of instructions executed. the way she just counts insns for you, obsessed.
• total_insn — number of instructions in the function. (unsigned int, so she's got limits, iykyk)
• cover_insn — number of distinct instructions that were actually executed. distinct!! not just any old repeat, okay? 🙈
• cycles_hist — struct cyc_hist *, an array of cyc_hist for each instruction. one per instruction bestie, a whole little lineup 🧚
• max_coverage — maximum number of covered basic block (used for block-range). she's a u64 and she's holding the ceiling for you 👑
• br_cntr — u64 *, array of the occurrences of events (branch counters) during a block. counting branches like it's her job, because it is 💀

---

🦋 Description 🦋

so this struct is used by two different codes when the sample has branch stack and cycles information. two codes, one struct, we love a shared-usage moment 🫶

Here's the tea on who does what:

• annotation__compute_ipc calculates average IPC using hit_insn / hit_cycles. math! slay! ⭐
• The actual coverage can be calculated using cover_insn / total_insn. another ratio, another vibe check.
• The cycles_hist can give IPC for each (longest) basic block ends at the given address. yes, longest — that's the qualifier, don't come for me.
• process_basic_block calculates coverage of instructions (or basic blocks) in the function.

and that's it, that's the whole description, no extra lore, no invented features, we stay factual in this group chat 💜

---

👑 SEE ALSO 👑

Kernel file ./tools/perf/util/annotate.h plus the whole friend group:

• struct sym_hist(9)
• struct cyc_hist(9)
• struct annotated_source(9)
• struct annotated_op_loc(9)
• struct annotated_insn_loc(9)
• struct annotated_basic_block(9)

go read them, they're literally iconic, fr fr 🌈

---

ngl the manual name is struct annotated_branch(9) from Kernel API Manual — and this page lives in ./tools/perf/util, October 2026 edition. that's the footer, folded into a sign-off because we're cute like that. byeeee ✨🎀💖