.\"	$OpenBSD: pctr.1,v 1.13 2008/07/08 21:39:52 sobrado Exp $
.\"
.\" Copyright (c) 2007 Mike Belopuhov, Aleksey Lomovtsev
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"
.\" Copyright (c) 1998, Jason Downs.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: July 8 2008 $
.Dt PCTR 1
.Os
.Sh NAME
.Nm pctr
.Nd display CPU performance counters
.Sh SYNOPSIS
.Nm pctr
.Op Fl AEeIiklMSu
.Op Fl f Ar funct
.Op Fl m Ar umask
.Op Fl s Ar ctr
.Op Fl t Ar thold
.Sh DESCRIPTION
The
.Nm
program is a sample implementation of how to access the
.Xr pctr 4
pseudo device available on many i386 and amd64 compatible machines.
.Pp
By default, the
.Nm
command displays the current values of the TSC and any vendor specific
counter registers.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 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.
.It Fl E
Enables counting exclusive cache coherency state (supported on Intel
processors only).
.It Fl e
Enables Edge Detect.
It is mandatory to enable Edge Detect with certain counter functions.
.It Fl f Ar funct
Specifies a function number in hexadecimal to program the counter,
specified by the
.Fl s
option.
.It Fl I
Enables counting invalid cache coherency state (supported on Intel
processors only).
.It Fl i
Invert the result of the threshold comparison, so that both greater than
and less than comparisons can be made.
.It Fl k
Count events occurring in kernel mode.
Specification of either
.Fl k
or
.Fl u
options is mandatory.
.It Fl l
List all possible vendor specific counters available on the current processor.
.It Fl M
Enables counting modified cache coherency state (supported on Intel
processors only).
.It Fl m Ar umask
Specifies a Unit Mask value for a function, specified by the
.Fl f
option.
.It Fl S
Enables counting shared cache coherency state (supported on Intel
processors only).
.It Fl s Ar ctr
Program counter number
.Ar ctr
with the function number specified by the
.Fl f
option.
A list of all possible functions supported on the current processor
can be obtained by the
.Fl l
option output.
.It Fl t Ar thold
Specifies an increment threshold.
The counter
.Ar ctr
will be incremented if the number of events occurring during one cycle is
greater or equal to
.Ar thold .
.It Fl u
Count events occurring in user mode.
Specification of either
.Fl k
or
.Fl u
options is mandatory.
.El
.Sh 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:
.Bd -unfilled -offset indent
# pctr -s 0 -f 40 -uk -MESI
.Ed
.Pp
To reset the counter run the following command:
.Bd -unfilled -offset indent
# pctr -s 0 -f 0
.Ed
.Sh SEE ALSO
.Xr pctr 4
.Pp
OS and Kernel Developer's Guide for AMD NPT Family 0Fh Processors.
.Pp
Intel 64 and IA-32 Architectures Software Developer's Manual.
Volume 3B: System Programming Guide, Part 2.
Appendix A: Performance Monitoring Events.
.Sh HISTORY
The
.Nm
program appeared in
.Ox 2.0
but was subsequently rewritten in
.Ox 4.3 .
.Sh CAVEATS
It is strongly advised to look through the manual for a particular processor
before programming a counter and interpreting the results.