Merge from vendor branch GDB:
[dragonfly.git] / share / man / man4 / man4.i386 / perfmon.4
1 .\"
2 .\" Copyright 1996 Massachusetts Institute of Technology
3 .\"
4 .\" Permission to use, copy, modify, and distribute this software and
5 .\" its documentation for any purpose and without fee is hereby
6 .\" granted, provided that both the above copyright notice and this
7 .\" permission notice appear in all copies, that both the above
8 .\" copyright notice and this permission notice appear in all
9 .\" supporting documentation, and that the name of M.I.T. not be used
10 .\" in advertising or publicity pertaining to distribution of the
11 .\" software without specific, written prior permission.  M.I.T. makes
12 .\" no representations about the suitability of this software for any
13 .\" purpose.  It is provided "as is" without express or implied
14 .\" warranty.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
17 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
20 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
23 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
25 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
26 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" SUCH DAMAGE.
28 .\"
29 .\" $FreeBSD: src/share/man/man4/man4.i386/perfmon.4,v 1.8.2.5 2001/08/17 13:08:46 ru Exp $
30 .\" $DragonFly: src/share/man/man4/man4.i386/perfmon.4,v 1.3 2006/05/26 19:39:40 swildner Exp $
31 .Dd March 26, 1996
32 .Dt PERFMON 4 i386
33 .Os
34 .Sh NAME
35 .Nm perfmon
36 .Nd CPU performance-monitoring interface
37 .Sh SYNOPSIS
38 .Cd cpu I586_CPU
39 .Cd cpu I686_CPU
40 .Cd options PERFMON
41 .Sh DESCRIPTION
42 The
43 .Nm
44 driver provides access to the internal performance-monitoring
45 capabilities of the
46 .Tn Intel
47 .Tn Pentium
48 and
49 .Tn "Pentium Pro"
50 CPUs.  These processors implement two internal counters which can be
51 configured to measure a variety of events for either count or duration
52 (in CPU cycles), as well as a cycle counter which counts clock cycles.
53 The
54 .Nm
55 driver provides a device-style interface to these capabilities.
56 .Pp
57 All access to the performance-monitoring counters is performed through
58 the special device file
59 .Dq Pa /dev/perfmon .
60 This device supports a number of
61 .Xr ioctl 2
62 requests, defined in
63 .In machine/perfmon.h
64 along with the definitions of the various counters for both
65 .Tn Pentium
66 and
67 .Tn "Pentium Pro"
68 processors.
69 .Pp
70 .Sy NOTA BENE :
71 The set of available events differs from processor to processor.  It
72 is the responsibility of the programmer to ensure that the event
73 numbers used are the correct ones for the CPU type being measured.
74 .Pp
75 The following
76 .Xr ioctl 2
77 requests are defined:
78 .Bl -tag -width PMIOTSTAMP
79 .It Dv PMIOSETUP
80 .Pq Li "struct pmc"
81 Set up a counter with parameters and flags defined in the structure.
82 The following fields are defined in
83 .Li struct pmc :
84 .Bl -tag -width "u_char pmc_eventx"
85 .It Li "int pmc_num"
86 the number of the counter in question; must be less than
87 .Dv NPMC
88 (currently 2).
89 .It Li "u_char pmc_event"
90 the particular event number to be monitored, as defined in
91 .In machine/perfmon.h .
92 .It Li "u_char pmc_unit"
93 the unit mask value, specific to the event type (see the
94 .Tn Intel
95 documentation).
96 .It Li "u_char pmc_flags"
97 flags modifying the operation of the counter (see below).
98 .It Li "u_char pmc_mask"
99 the counter mask value; essentially, this is a threshold used to
100 restrict the count to events lasting more (or less) than the specified
101 number of clocks.
102 .El
103 .Pp
104 The following
105 .Li pmc_flags
106 values are defined:
107 .Bl -tag -compact -width PMCF_USRxx
108 .It Dv PMCF_USR
109 count events in user mode
110 .It Dv PMCF_OS
111 count events in kernel mode
112 .It Dv PMCF_E
113 count number of events rather than their duration
114 .It Dv PMCF_INV
115 invert the sense of the counter mask comparison
116 .El
117 .It Dv PMIOGET
118 .Pq Li "struct pmc"
119 returns the current configuration of the specified counter.
120 .It Dv PMIOSTART
121 .It Dv PMIOSTOP
122 .Pq Li int
123 starts (stops) the specified counter.  Due to hardware deficiencies,
124 counters must be started and stopped in numerical order.  (That is to
125 say, counter 0 can never be stopped without first stopping counter 1.)
126 The driver will
127 .Em not
128 enforce this restriction (since it may not be present in future CPUs).
129 .It Dv PMIORESET
130 .Pq Li int
131 reset the specified counter to zero.  The counter should be stopped
132 with
133 .Dv PMIOSTOP
134 before it is reset.  All counters are automatically reset by
135 .Dv PMIOSETUP .
136 .It Dv PMIOREAD
137 .Pq Li "struct pmc_data"
138 get the current value of the counter.  The
139 .Li pmc_data
140 structure defines two fields:
141 .Pp
142 .Bl -tag -compact -width "quad_t pmcd_value"
143 .It Li "int pmcd_num"
144 the number of the counter to read
145 .It Li "quad_t pmcd_value"
146 the resulting value as a 64-bit signed integer
147 .El
148 .Pp
149 In the future, it may be possible to use the
150 .Li RDPMC
151 instruction on
152 .Tn "Pentium Pro"
153 processors to read the counters directly.
154 .It Dv PMIOTSTAMP
155 .Pq Li "struct pmc_tstamp"
156 read the time stamp counter.  The
157 .Li pmc_tstamp
158 structure defines two fields:
159 .Pp
160 .Bl -tag -compact -width "quad_t pmct_value"
161 .It Li "int pmct_rate"
162 the approximate rate of the counter, in MHz
163 .It Li "quad_t pmct_value"
164 the current value of the counter as a 64-bit integer
165 .El
166 .Pp
167 It is important to note that the counter rate, as provided in the
168 .Li pmct_rate
169 field, is often incorrect because of calibration difficulties and
170 non-integral clock rates.  This field should be considered more of a
171 hint or sanity-check than an actual representation of the rate of
172 clock ticks.
173 .El
174 .Sh FILES
175 .Bl -tag -compact -width "/usr/include/machine/perfmon.h"
176 .It Pa /dev/perfmon
177 character device interface to counters
178 .It In machine/perfmon.h
179 include file with definitions of structures and event types
180 .It Pa /usr/share/examples/perfmon
181 sample source code demonstrating use of all the
182 .Fn ioctl
183 commands
184 .El
185 .Sh SEE ALSO
186 .Xr ioctl 2
187 .Rs
188 .%A Intel Corporation
189 .%B Pentium Pro Family Developer's Manual
190 .%D January 1996
191 .%V vol. 3
192 .%O Operating System Writer's Manual
193 .Re
194 .Sh HISTORY
195 The
196 .Nm
197 device first appeared in
198 .Fx 2.2 .
199 .Sh AUTHORS
200 The
201 .Nm
202 driver was written by
203 .An Garrett A. Wollman ,
204 MIT Laboratory for Computer Science.