PMCANNOTATE(8)

👑 PMCANNOTATE(8) — like, the manual page but make it make sense 💅

okay so bestie, welcome to pmcannotate, from the System Manager's Manual — it's an 8-section (system manager) page and it's genuinely iconic once you get it. Let me walk you through it 🫶

---

✨ NAME ✨

pmcannotate — sources printout with inlined profiling. yes that's the whole name line, she's brief but she's powerful 💖

---

🌸 SYNOPSIS 🌸

pmcannotate [-a] [-h] [-k pathname] [-l level] [-m mode] pmcout.out
            binaryobj

that's it, that's the whole vibe check 🔥

---

🦋 DESCRIPTION 🦋

okay so here's the tea: the pmcannotate utility can produce both C sources or assembly sources of a program, with a line-by-line based profiling. like, it's giving "annotated code" main character energy ✨

so how does it get this info? the profiling information is retrieved through a pmcstat(8) raw output — and the program operations are retrieved through the objdump(1) tool. two besties doing the heavy lifting, fr fr 💅

when you call pmcannotate, the raw output is passed through the pmcout.out argument, while the program is passed through the binaryobj argument. two arguments, no cap.

lowkey important: as long as pmcannotate relies on objdump(1) and pmcstat(8) to work, it will fail if one of them is not available. so like, check your supplies before you start the group project, bestie 😭

---

🎀 OPTIONS 🎀

the following options are available:

• -a — shows the program profiling inlined in the assembly code only. no C information involving C sources is provided. straight assembly, no crumbs 🌈
• -h — prints out information about the usage of the tool. the "help me help you" button 🫶
• -l level — changes the lower bound (expressed in percentage) for traced functions that will be printed out in the report. the default value is 0.5%. so like, anything under half a percent gets left on read 💀
• -k kerneldir — set the pathname of the kernel directory to argument kerneldir. this directory specifies where pmcannotate should look for the kernel and its modules. the default is /boot/kernel. it's giving "where's my stuff" energy 🧚
• -m mode — format to use when annotating source or assembly lines. one of:
  • block — display percentage of matching samples relative to samples falling in the current block.
  • global — display percentage of matching samples relative to all samples.
  • raw — display the raw count of matching samples.

pick your fighter, all three are valid 👑 ⭐

---

🙈 LIMITATIONS 🙈

okay bestie, this is the part where we get real. as long as pmcannotate relies on the objdump(1) utility to retrieve the C code, the program needs to be compiled with debugging options. no debug info, no C code, periodt. 😭

sometimes — in particular with heavy optimization levels — the objdump(1) utility embeds the code of inlining functions directly in the callers, making an output difficult to read. so like, your report comes out looking like a group chat with no context 🙈

and the x86 version? it reports the sampling from pmcstat collecting the following instruction in regard of the interrupted one. this means that the samples may be attributed to the line below the one of interest. so always double-check, ngl — off-by-one is out here ruining lives 💀

---

🌈 SEE ALSO 🌈

objdump(1), pmcstat(8) — go read those too, iykyk 💜

---

💖 AUTHORS 💖

Attilio Rao <attilio@FreeBSD.org> — thank you for your service, icon 🫶

---

and that's the whole page!! this Debian version of PMCANNOTATE(8) is dated January 14, 2025 — screenshot it, cite it, live your truth ✨ see you in the next manpage bestie 💅