---
name: "perfmon"
section: "4freebsd"
platform: "linux"
package: "freebsd-manpages"
version: "12.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/perfmon/4freebsd"
---

# perfmon(4freebsd)

CPU performance-monitoring interface

## NAME

**perfmon** – CPU performance-monitoring interface

## SYNOPSIS

**cpu** **I586\_CPU** **cpu** **I686\_CPU** **options** **PERFMON**

## DESCRIPTION

The **perfmon** driver provides access to the internal performance-monitoring capabilities of the Intel Pentium and Pentium Pro CPUs. These processors implement two internal counters which can be configured to measure a variety of events for either count or duration (in CPU cycles), as well as a cycle counter which counts clock cycles. The **perfmon** driver provides a device-style interface to these capabilities.

All access to the performance-monitoring counters is performed through the special device file “*/dev/perfmon*”. This device supports a number of [ioctl(2)](/ioctl/2.md) requests, defined in ⟨machine/perfmon.h⟩ along with the definitions of the various counters 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 ensure that the event numbers used are the correct ones for the CPU type being measured.

The following [ioctl(2)](/ioctl/2.md) requests are defined:

- PMIOSETUP

  (struct pmc) Set up a counter with 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.

- PMIOSTART

  - PMIOSTOP

  (int) starts (stops) the specified counter. 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).

- 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.

## 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)](/ioctl/2.md), [hwpmc(4)](/hwpmc/4.md) 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.

## AUTHORS

The **perfmon** driver was written by Garrett A. Wollman, MIT Laboratory for Computer Science.