1.\" $OpenBSD: pctr.1,v 1.13 2008/07/08 21:39:52 sobrado Exp $ 2.\" 3.\" Copyright (c) 2007 Mike Belopuhov, Aleksey Lomovtsev 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" 18.\" Copyright (c) 1998, Jason Downs. All rights reserved. 19.\" 20.\" Redistribution and use in source and binary forms, with or without 21.\" modification, are permitted provided that the following conditions 22.\" are met: 23.\" 1. Redistributions of source code must retain the above copyright 24.\" notice, this list of conditions and the following disclaimer. 25.\" 2. Redistributions in binary form must reproduce the above copyright 26.\" notice, this list of conditions and the following disclaimer in the 27.\" documentation and/or other materials provided with the distribution. 28.\" 29.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS 30.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 31.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 32.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, 33.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 34.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 35.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 36.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 37.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 38.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 39.\" SUCH DAMAGE. 40.\" 41.Dd $Mdocdate: July 8 2008 $ 42.Dt PCTR 1 43.Os 44.Sh NAME 45.Nm pctr 46.Nd display CPU performance counters 47.Sh SYNOPSIS 48.Nm pctr 49.Op Fl AEeIiklMSu 50.Op Fl f Ar funct 51.Op Fl m Ar umask 52.Op Fl s Ar ctr 53.Op Fl t Ar thold 54.Sh DESCRIPTION 55The 56.Nm 57program is a sample implementation of how to access the 58.Xr pctr 4 59pseudo device available on many i386 and amd64 compatible machines. 60.Pp 61By default, the 62.Nm 63command displays the current values of the TSC and any vendor specific 64counter registers. 65.Pp 66The options are as follows: 67.Bl -tag -width Ds 68.It Fl A 69Some bus events differentiate between the originating physical processor 70(a bus agent) and other agents on the bus. 71Specifying this option allows counting on all bus agents. 72This is supported on Intel processors only. 73.It Fl E 74Enables counting exclusive cache coherency state (supported on Intel 75processors only). 76.It Fl e 77Enables Edge Detect. 78It is mandatory to enable Edge Detect with certain counter functions. 79.It Fl f Ar funct 80Specifies a function number in hexadecimal to program the counter, 81specified by the 82.Fl s 83option. 84.It Fl I 85Enables counting invalid cache coherency state (supported on Intel 86processors only). 87.It Fl i 88Invert the result of the threshold comparison, so that both greater than 89and less than comparisons can be made. 90.It Fl k 91Count events occurring in kernel mode. 92Specification of either 93.Fl k 94or 95.Fl u 96options is mandatory. 97.It Fl l 98List all possible vendor specific counters available on the current processor. 99.It Fl M 100Enables counting modified cache coherency state (supported on Intel 101processors only). 102.It Fl m Ar umask 103Specifies a Unit Mask value for a function, specified by the 104.Fl f 105option. 106.It Fl S 107Enables counting shared cache coherency state (supported on Intel 108processors only). 109.It Fl s Ar ctr 110Program counter number 111.Ar ctr 112with the function number specified by the 113.Fl f 114option. 115A list of all possible functions supported on the current processor 116can be obtained by the 117.Fl l 118option output. 119.It Fl t Ar thold 120Specifies an increment threshold. 121The counter 122.Ar ctr 123will be incremented if the number of events occurring during one cycle is 124greater or equal to 125.Ar thold . 126.It Fl u 127Count events occurring in user mode. 128Specification of either 129.Fl k 130or 131.Fl u 132options is mandatory. 133.El 134.Sh EXAMPLES 135The following command, executed from the command line, will set the first 136performance counter to count the number of cacheable L1 data cache reads 137in user and kernel modes on an Intel Core2 Duo processor: 138.Bd -unfilled -offset indent 139# pctr -s 0 -f 40 -uk -MESI 140.Ed 141.Pp 142To reset the counter run the following command: 143.Bd -unfilled -offset indent 144# pctr -s 0 -f 0 145.Ed 146.Sh SEE ALSO 147.Xr pctr 4 148.Pp 149OS and Kernel Developer's Guide for AMD NPT Family 0Fh Processors. 150.Pp 151Intel 64 and IA-32 Architectures Software Developer's Manual. 152Volume 3B: System Programming Guide, Part 2. 153Appendix A: Performance Monitoring Events. 154.Sh HISTORY 155The 156.Nm 157program appeared in 158.Ox 2.0 159but was subsequently rewritten in 160.Ox 4.3 . 161.Sh CAVEATS 162It is strongly advised to look through the manual for a particular processor 163before programming a counter and interpreting the results. 164