PMCSTUDY(8)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💖 PMCSTUDY(8) — the pmcstudy manual, but make it make sense 💖

okay bestie, so this is pmcstudy, straight out of the System Manager's Manual section 8, and it's genuinely one of my fave little performance-nerd tools. sit down, hydrate, let's go 🫶

✨ NAME ✨

pmcstudy — literally just runs a bunch of studies on your system's overall PMCs. that's the whole vibe. periodt.

🌸 SYNOPSIS 🌸

pmcstudy [-i inputfile | -A | -T | -v | -m max | -e -exp | -E | -h | -fl
         -H]
pmcstudy -i inputfile
pmcstudy -v
pmcstudy -m max
pmcstudy -e exp-name
pmcstudy -E your-expr
pmcstudy -h
pmcstudy -H
pmcstudy -T

like, yes, the first line is a whole mood and a half, but it's verbatim so don't come for me 💅

🦋 DESCRIPTION 🦋

okay so pmcstudy is designed to run a whole bunch of tests against your system's performance. there are roughly 20-22 canned tests, and each one sets up specific PMCs and then runs various formulas on the output information. it's giving "curated playlist but for CPU counters" ✨

those formulas live in the Intel documentation "Using Intel Vtune amplifier xe on NNN Generation Intel Core Processors". the NNN is either 2nd, 3rd, 4th or 5th generation — i.e. Sandy Bridge, Ivy Bridge, Haswell and Broadwell, bestie, keep up 😭

ngl, currently the program only works on these four Intel processor types. that's the whole roster. no cap.

🎀 OPTIONS 🎀

the following options are available, and yes i'm listing every single one because we don't skip:

  • -i filename — if you supply this option, instead of running a pmcstat(8) command to collect the current running information, the filename will be read in as input instead. like, replay the vibes from a file 🍓
  • -H — displays the complete list of canned formulas that can be run, including their names which can be input to the -e option. it's the menu, honey, and you're gonna read it 👑
  • -e name — execute the canned test name on the running kernel. main character energy fr fr.
  • -h — if you add this option to the -e option, the test will not execute; instead you get a small description of the test that would run. it's the trailer, not the movie 🙈
  • -T — executes a test of every PMC to validate that they're working on your system. if a PMC doesn't show up in this test, chances are the kernel hwpmc(4) driver needs updating with new PMC information. bestie, that's a code smell 💀
  • -m num — this option can restrict the number of one second samples that will be collected by your system when running a test (it bounds the time the test will run). without this option the test will run for 1024 seconds or until the user types Ctrl+C. lowkey a long hangout, so plan accordingly 😭
  • -v — the verbose option adds debugging output to the command. it's the "tell me everything" option and honestly? obsessed.
  • -E expression — for those that have their own ideas on what formulas they want to run 🔥 the expression given to the -E option is a "formula". the formula can declare directly the PMCs by name, or you can use an abbreviation %NNN. to find out the abbreviations on your system you may run the -L option. an example of a formula of your own might be -E "FP_ASSIST.ANY / INST_RETIRED.ANY_P" or, using the abbreviations on a Haswell machine, you would type -E " %176 / %150". you must have spaces between each entry, and you may use parentheses to prioritize the operators. Add (+), Subtract (-), Divide (/) and Multiplication (*) are supported. you may also introduce constant numbers. for example you can do a standard efficiency test like -E "UOPS_RETIRED.RETIRE_SLOTS / (4 * CPU_CLK_UNHALTED.THREAD_P)". slay, do the math 💜
  • -L — lists all known PMCs and their abbreviation (%NNN). it's the cheat sheet, iykyk 🌈
  • -A — run all canned tests. every single one. go off, icon ⭐

🧚 SEE ALSO 🧚

pmc(3), pmclog(3), hwpmc(4), pmcstat(8) — go read your friends, bestie 🫶

🌟 HISTORY 🌟

the pmcstudy utility first appeared in FreeBSD 11.0. a legend was born ✨

💅 AUTHORS 💅

Randall Stewart <rrs@FreeBSD.org> — give him his flowers, he ate 👑

and that's the page, gorgeous! this one's from the Debian crew, dated March 26, 2015, and that's your cute little sign-off — now go measure something, bestie 💖🎀🦋

📦 where this page comes from