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 perfor

mance-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 cy

cles), 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 per

formed through
the special device file ``/dev/perfmon''. This device sup

ports a number
of ioctl(2) requests, defined in #include

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

sor 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 (cur

rently 2).

u_char pmc_event the particular event number

to be moni

tored, as defined in

u_char pmc_unit the unit mask value, specific

to the event

type (see the Intel documen

tation).

u_char pmc_flags flags modifying the operation

of the

counter (see below).

u_char pmc_mask the counter mask value; es

sentially, this

is a threshold used to re

strict 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 speci

fied 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 re

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

ters 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 defini

tions of struc

tures and event types

/usr/share/examples/perfmon sample source code demon

strating use of

all the ioctl() commands

SEE ALSO

ioctl(2)

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.

BSD March 26, 1996

BSD