FreeBSD manual
download PDF document: perfmon.4.pdf
PERFMON(4) FreeBSD Kernel Interfaces Manual (i386) PERFMON(4)
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) 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) 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
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), 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.
AUTHORS
The perfmon driver was written by Garrett A. Wollman, MIT Laboratory for
Computer Science.
FreeBSD 14.0-RELEASE-p11 March 26, 1996 FreeBSD 14.0-RELEASE-p11