Annotation of src/usr.bin/pctr/pctr.1, Revision 1.13
1.13 ! sobrado 1: .\" $OpenBSD: pctr.1,v 1.12 2008/02/11 07:58:28 jmc Exp $
1.9 deraadt 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.13 ! sobrado 41: .Dd $Mdocdate: February 11 2008 $
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.10 jmc 49: .Op Fl AEeIiklMSu
1.9 deraadt 50: .Op Fl f Ar funct
51: .Op Fl m Ar umask
1.10 jmc 52: .Op Fl s Ar ctr
1.9 deraadt 53: .Op Fl t Ar thold
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
1.10 jmc 69: Some bus events differentiate between the originating physical processor
70: (a bus agent) and other agents on the bus.
1.9 deraadt 71: Specifying this option allows counting on all bus agents.
72: This is supported on Intel processors only.
1.10 jmc 73: .It Fl E
74: Enables counting exclusive cache coherency state (supported on Intel
75: processors only).
1.9 deraadt 76: .It Fl e
77: Enables Edge Detect.
78: It is mandatory to enable Edge Detect with certain counter functions.
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.
1.10 jmc 84: .It Fl I
85: Enables counting invalid cache coherency state (supported on Intel
86: processors only).
1.9 deraadt 87: .It Fl i
88: Invert the result of the threshold comparison, so that both greater than
89: and less than comparisons can be made.
90: .It Fl k
1.10 jmc 91: Count events occurring in kernel mode.
1.9 deraadt 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.
1.10 jmc 99: .It Fl M
100: Enables counting modified cache coherency state (supported on Intel
101: processors only).
1.9 deraadt 102: .It Fl m Ar umask
103: Specifies a Unit Mask value for a function, specified by the
104: .Fl f
105: option.
1.13 ! sobrado 106: .It Fl S
! 107: Enables counting shared cache coherency state (supported on Intel
! 108: processors only).
1.9 deraadt 109: .It Fl s Ar ctr
110: Program counter number
111: .Ar ctr
1.10 jmc 112: with the function number specified by the
1.9 deraadt 113: .Fl f
114: option.
1.10 jmc 115: A list of all possible functions supported on the current processor
116: can be obtained by the
1.9 deraadt 117: .Fl l
118: option output.
119: .It Fl t Ar thold
120: Specifies an increment threshold.
121: The counter
122: .Ar ctr
1.10 jmc 123: will be incremented if the number of events occurring during one cycle is
1.9 deraadt 124: greater or equal to
125: .Ar thold .
126: .It Fl u
1.10 jmc 127: Count events occurring in user mode.
1.9 deraadt 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
1.10 jmc 137: in user and kernel modes on an Intel Core2 Duo processor:
1.9 deraadt 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.1 downsj 146: .Sh SEE ALSO
147: .Xr pctr 4
1.9 deraadt 148: .Pp
149: OS and Kernel Developer's Guide for AMD NPT Family 0Fh Processors.
150: .Pp
151: Intel 64 and IA-32 Architectures Software Developer's Manual.
152: Volume 3B: System Programming Guide, Part 2.
153: Appendix A: Performance Monitoring Events.
1.1 downsj 154: .Sh HISTORY
155: The
156: .Nm
157: program appeared in
1.9 deraadt 158: .Ox 2.0
159: but was subsequently rewritten in
1.11 mikeb 160: .Ox 4.3 .
1.9 deraadt 161: .Sh CAVEATS
1.10 jmc 162: It is strongly advised to look through the manual for a particular processor
1.9 deraadt 163: 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