2 .\" Copyright 1996 Massachusetts Institute of Technology
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
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
35 .Nd CPU performance-monitoring interface
43 driver provides access to the internal performance-monitoring
50 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.
55 driver provides a device-style interface to these capabilities.
57 All access to the performance-monitoring counters is performed through
58 the special device file
60 This device supports a number of
64 along with the definitions of the various counters for both
71 The set of available events differs from processor to processor.
73 is the responsibility of the programmer to ensure that the event
74 numbers used are the correct ones for the CPU type being measured.
79 .Bl -tag -width PMIOTSTAMP
82 Set up a counter with parameters and flags defined in the structure.
83 The following fields are defined in
85 .Bl -tag -width "u_char pmc_eventx"
87 the number of the counter in question; must be less than
90 .It Li "u_char pmc_event"
91 the particular event number to be monitored, as defined in
92 .In machine/perfmon.h .
93 .It Li "u_char pmc_unit"
94 the unit mask value, specific to the event type (see the
97 .It Li "u_char pmc_flags"
98 flags modifying the operation of the counter (see below).
99 .It Li "u_char pmc_mask"
100 the counter mask value; essentially, this is a threshold used to
101 restrict the count to events lasting more (or less) than the specified
108 .Bl -tag -compact -width PMCF_USRxx
110 count events in user mode
112 count events in kernel mode
114 count number of events rather than their duration
116 invert the sense of the counter mask comparison
120 returns the current configuration of the specified counter.
124 starts (stops) the specified counter.
125 Due to hardware deficiencies,
126 counters must be started and stopped in numerical order.
128 say, counter 0 can never be stopped without first stopping counter 1.)
131 enforce this restriction (since it may not be present in future CPUs).
134 reset the specified counter to zero.
135 The counter should be stopped
139 All counters are automatically reset by
142 .Pq Li "struct pmc_data"
143 get the current value of the counter.
146 structure defines two fields:
148 .Bl -tag -compact -width "quad_t pmcd_value"
149 .It Li "int pmcd_num"
150 the number of the counter to read
151 .It Li "quad_t pmcd_value"
152 the resulting value as a 64-bit signed integer
155 In the future, it may be possible to use the
159 processors to read the counters directly.
161 .Pq Li "struct pmc_tstamp"
162 read the time stamp counter.
165 structure defines two fields:
167 .Bl -tag -compact -width "quad_t pmct_value"
168 .It Li "int pmct_rate"
169 the approximate rate of the counter, in MHz
170 .It Li "quad_t pmct_value"
171 the current value of the counter as a 64-bit integer
174 It is important to note that the counter rate, as provided in the
176 field, is often incorrect because of calibration difficulties and
177 non-integral clock rates.
178 This field should be considered more of a
179 hint or sanity-check than an actual representation of the rate of
183 .Bl -tag -compact -width "/usr/include/machine/perfmon.h"
185 character device interface to counters
186 .It Pa /usr/include/machine/perfmon.h
187 include file with definitions of structures and event types
188 .It Pa /usr/share/examples/perfmon
189 sample source code demonstrating use of all the
197 .%A Intel Corporation
198 .%B Pentium Pro Family Developer's Manual
201 .%O Operating System Writer's Manual
206 device first appeared in
211 driver was written by
212 .An Garrett A. Wollman ,
213 MIT Laboratory for Computer Science.