Annotation of src/usr.bin/pctr/pctr.1, Revision 1.9
1.9 ! deraadt 1: .\" $OpenBSD: pctr.1,v 1.8 2007/05/31 19:20:14 jmc 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: .\"
1.1 downsj 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: .\"
1.9 ! deraadt 41: .Dd $Mdocdate: May 31 2007 $
1.1 downsj 42: .Dt PCTR 1
43: .Os
44: .Sh NAME
45: .Nm pctr
1.2 aaron 46: .Nd display CPU performance counters
1.1 downsj 47: .Sh SYNOPSIS
1.3 aaron 48: .Nm pctr
1.9 ! deraadt 49: .Op Fl AeEiIklMu
! 50: .Op Fl f Ar funct
! 51: .Op Fl m Ar umask
! 52: .Op Fl t Ar thold
! 53: .Op Fl s Ar ctr
1.1 downsj 54: .Sh DESCRIPTION
55: The
56: .Nm
57: program is a sample implementation of how to access the
58: .Xr pctr 4
1.9 ! deraadt 59: pseudo device available on many i386 and amd64 compatible machines.
1.1 downsj 60: .Pp
61: By default, the
62: .Nm
63: command displays the current values of the TSC and any vendor specific
64: counter registers.
1.4 aaron 65: .Pp
66: The options are as follows:
1.6 aaron 67: .Bl -tag -width Ds
1.9 ! deraadt 68: .It Fl A
! 69: Some bus events provide specificity between the originating physical processor
! 70: (a bus agent) versus other agents on the bus.
! 71: Specifying this option allows counting on all bus agents.
! 72: This is supported on Intel processors only.
! 73: .It Fl e
! 74: Enables Edge Detect.
! 75: It is mandatory to enable Edge Detect with certain counter functions.
! 76: .It Fl E
! 77: Enables counting exclusive cache coherency state (supported on Intel
! 78: processors only).
! 79: .It Fl f Ar funct
! 80: Specifies a function number in hexadecimal to program the counter,
! 81: specified by the
! 82: .Fl s
! 83: option.
! 84: .It Fl i
! 85: Invert the result of the threshold comparison, so that both greater than
! 86: and less than comparisons can be made.
! 87: .It Fl I
! 88: Enables counting invalid cache coherency state (supported on Intel
! 89: processors only).
! 90: .It Fl k
! 91: Count events occurred in kernel mode.
! 92: Specification of either
! 93: .Fl k
! 94: or
! 95: .Fl u
! 96: options is mandatory.
! 97: .It Fl l
! 98: List all possible vendor specific counters available on the current processor.
! 99: .It Fl m Ar umask
! 100: Specifies a Unit Mask value for a function, specified by the
! 101: .Fl f
! 102: option.
! 103: .It Fl M
! 104: Enables counting modified cache coherency state (supported on Intel
! 105: processors only).
! 106: .It Fl s Ar ctr
! 107: Program counter number
! 108: .Ar ctr
! 109: with function number specified by the
! 110: .Fl f
! 111: option.
! 112: List of all possible functions, supported on the current processor,
! 113: could be obtained by the
! 114: .Fl l
! 115: option output.
! 116: .It Fl S
! 117: Enables counting shared cache coherency state (supported on Intel
! 118: processors only).
! 119: .It Fl t Ar thold
! 120: Specifies an increment threshold.
! 121: The counter
! 122: .Ar ctr
! 123: will be incremented if number of events occurred during the one cycle is
! 124: greater or equal to
! 125: .Ar thold .
! 126: .It Fl u
! 127: Count events occurred in user mode.
! 128: Specification of either
! 129: .Fl k
! 130: or
! 131: .Fl u
! 132: options is mandatory.
1.1 downsj 133: .El
1.9 ! deraadt 134: .Sh EXAMPLES
! 135: The following command, executed from the command line, will set the first
! 136: performance counter to count the number of cacheable L1 data cache reads
! 137: in user and kernel modes on Intel Core2 Duo processor:
! 138: .Bd -unfilled -offset indent
! 139: # pctr -s 0 -f 40 -uk -MESI
! 140: .Ed
! 141: .Pp
! 142: To reset the counter run the following command:
! 143: .Bd -unfilled -offset indent
! 144: # pctr -s 0 -f 0
! 145: .Ed
1.4 aaron 146: .Pp
1.1 downsj 147: .Sh SEE ALSO
148: .Xr pctr 4
1.9 ! deraadt 149: .Pp
! 150: OS and Kernel Developer's Guide for AMD NPT Family 0Fh Processors.
! 151: .Pp
! 152: Intel 64 and IA-32 Architectures Software Developer's Manual.
! 153: Volume 3B: System Programming Guide, Part 2.
! 154: Appendix A: Performance Monitoring Events.
1.1 downsj 155: .Sh HISTORY
156: The
157: .Nm
158: program appeared in
1.9 ! deraadt 159: .Ox 2.0
! 160: but was subsequently rewritten in
! 161: .Ox 4.2 .
! 162: .Sh CAVEATS
! 163: It is strongly advised to look through a manual for a particular processor
! 164: before programming a counter and interpreting the results.
![[BACK]](/icons/back.gif){kind=icon}
Return to pctr.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / pctr