PERFMON(4)

✨ PERFMON(4) ✨

okay bestie, this is a page from the i386 Kernel Interfaces Manual — yes, the i386 one, we're going vintage today 💅 — and it's all about perfmon, the CPU performance-monitoring interface. buckle up 🎀

---

🌸 NAME 🌸

perfmon — the CPU performance-monitoring interface, i.e. the little door into your CPU's built-in "how hard am I working tho" hardware 🫶

---

✨ SYNOPSIS ✨

cpu I586_CPU
cpu I686_CPU
options PERFMON

like, you gotta have one of those CPUs and you gotta turn on that option. no option, no vibes. periodt.

---

💖 DESCRIPTION 💖

so the perfmon driver hands you the keys to the internal performance-monitoring capabilities of the Intel Pentium and Pentium Pro CPUs. these processors are lowkey flexing two internal counters that you can configure to measure a whole bunch of events, either as a count or as a duration (in CPU cycles, bestie, we're counting in cycles), plus there's a cycle counter that just counts clock cycles. and perfmon gives you a device-style interface to all of that. iconic. 🔥

every single bit of access to the performance-monitoring counters goes through the special device file /dev/perfmon. this device supports a bunch of ioctl(2) requests, which are defined in <machine/perfmon.h> — and that header is also where the definitions of the various counters live, for both Pentium and Pentium Pro processors. 🦋

NOTA BENE: the set of available events differs from processor to processor. it is the responsibility of the programmer to make sure the event numbers used are the correct ones for the CPU type being measured. no cap, this one matters. ⚠️

the following ioctl(2) requests are defined:

• PMIOSETUP — (struct pmc) set up a counter with the parameters and flags defined in the structure. the following fields are defined in struct pmc:
  • int pmc_num — the number of the counter in question; must be less than NPMC (currently 2).
  • u_char pmc_event — the particular event number to be monitored, as defined in <machine/perfmon.h>.
  • u_char pmc_unit — the unit mask value, specific to the event type (see the Intel documentation).
  • u_char pmc_flags — flags modifying the operation of the counter (see below).
  • u_char pmc_mask — the counter mask value; essentially, this is a threshold used to restrict the count to events lasting more (or less) than the specified number of clocks.

the following pmc_flags values are defined:

• PMCF_USR — count events in user mode
• PMCF_OS — count events in kernel mode
• PMCF_E — count number of events rather than their duration
• PMCF_INV — invert the sense of the counter mask comparison

• PMIOGET — (struct pmc) returns the current configuration of the specified counter. like a lil vibe check on your counter's settings 👀
• PMIOSTART
• PMIOSTOP — (int) starts (stops) the specified counter. and here's the tea 🍵: due to hardware deficiencies, counters must be started and stopped in numerical order. (that is to say, counter 0 can never be stopped without first stopping counter 1.) the driver will not enforce this restriction (since it may not be present in future CPUs). so like, it's on you, bestie 😭
• PMIORESET — (int) reset the specified counter to zero. the counter should be stopped with PMIOSTOP before it is reset. all counters are automatically reset by PMIOSETUP. 🧚
• PMIOREAD — (struct pmc_data) get the current value of the counter. the pmc_data structure defines two fields:
  • int pmcd_num — the number of the counter to read
  • quad_t pmcd_value — the resulting value as a 64-bit signed integer

in the future, it may be possible to use the RDPMC instruction on Pentium Pro processors to read the counters directly. ✨

• PMIOTSTAMP — (struct pmc_tstamp) read the time stamp counter. the pmc_tstamp structure defines two fields:
  • int pmct_rate — the approximate rate of the counter, in MHz
  • quad_t pmct_value — the current value of the counter as a 64-bit integer

it is important to note that the counter rate, as provided in the pmct_rate field, is often incorrect because of calibration difficulties and non-integral clock rates. this field should be considered more of a hint or sanity-check than an actual representation of the rate of clock ticks. so don't trust it with your life, she's just guessing 💀

---

🎀 FILES 🎀

• /dev/perfmon — character device interface to counters
• /usr/include/machine/perfmon.h — include file with definitions of structures and event types
• /usr/share/examples/perfmon — sample source code demonstrating use of all the ioctl() commands

---

🦋 SEE ALSO 🦋

• ioctl(2), hwpmc(4)
• Intel Corporation, Pentium Pro Family Developer's Manual, vol. 3, January 1996, Operating System Writer's Manual.

---

💜 HISTORY 💜

the perfmon device first appeared in FreeBSD 2.2. a true elder icon 👑

---

🌈 AUTHORS 🌈

the perfmon driver was written by Garrett A. Wollman, MIT Laboratory for Computer Science. we love a legend 🫶

---

and that's the whole page, bestie — Debian, March 26, 1996, the i386 Kernel Interfaces Manual era of it all. mwah 💅💖