NAME

pctr — display CPU performance counters

SYNOPSIS

DESCRIPTION

The pctr program is a sample implementation of how to access the pctr(4) pseudo device available on many i386 and amd64 compatible machines.

By default, the pctr command displays the current values of the TSC and any vendor specific counter registers.

The options are as follows:

-A

Some bus events differentiate between the originating physical processor (a bus agent) and other agents on the bus. Specifying this option allows counting on all bus agents. This is supported on Intel processors only.

-E

Enables counting exclusive cache coherency state (supported on Intel processors only).

-e

Enables Edge Detect. It is mandatory to enable Edge Detect with certain counter functions.

-f funct

Specifies a function number in hexadecimal to program the counter, specified by the -s option.

-I

Enables counting invalid cache coherency state (supported on Intel processors only).

-i

Invert the result of the threshold comparison, so that both greater than and less than comparisons can be made.

-k

Count events occurring in kernel mode. Specification of either -k or -u options is mandatory.

-l

List all possible vendor specific counters available on the current processor.

-M

Enables counting modified cache coherency state (supported on Intel processors only).

-m umask

Specifies a Unit Mask value for a function, specified by the -f option.

-S

Enables counting shared cache coherency state (supported on Intel processors only).

-s ctr

Program counter number ctr with the function number specified by the -f option. A list of all possible functions supported on the current processor can be obtained by the -l option output.

-t thold

Specifies an increment threshold. The counter ctr will be incremented if the number of events occurring during one cycle is greater or equal to thold.

-u

Count events occurring in user mode. Specification of either -k or -u options is mandatory.

EXAMPLES

The following command, executed from the command line, will set the first performance counter to count the number of cacheable L1 data cache reads in user and kernel modes on an Intel Core2 Duo processor:

# pctr -s 0 -f 40 -uk -MESI

To reset the counter run the following command:

# pctr -s 0 -f 0

SEE ALSO

pctr(4)

OS and Kernel Developer's Guide for AMD NPT Family 0Fh Processors.

Intel 64 and IA-32 Architectures Software Developer's Manual. Volume 3B: System Programming Guide, Part 2. Appendix A: Performance Monitoring Events.

HISTORY

The pctr program appeared in OpenBSD 2.0 but was subsequently rewritten in OpenBSD 4.3.

CAVEATS

It is strongly advised to look through the manual for a particular processor before programming a counter and interpreting the results.