PCTR(1)                    OpenBSD Reference Manual                    PCTR(1)

NAME
     pctr - display CPU performance counters

SYNOPSIS
     pctr [-AEeIiklMSu] [-f funct] [-m umask] [-s ctr] [-t thold]

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 In-
             tel 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 cur-
             rent processor.

     -M      Enables counting modified cache coherency state (supported on In-
             tel 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 incre-
             mented 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 pro-
     cessor before programming a counter and interpreting the results.

OpenBSD 4.7                      July 8, 2008                                2
