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$
  30 .Dd March 26, 1996
  31 .Dt PERFMON 4 i386
  32 .Os
  33 .Sh NAME
  34 .Nm perfmon
  35 .Nd CPU performance-monitoring interface
  36 .Sh SYNOPSIS
  37 .Cd cpu I586_CPU
  38 .Cd cpu I686_CPU
  39 .Cd options PERFMON
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 driver provides access to the internal performance-monitoring
  44 capabilities of the
  45 .Tn Intel
  46 .Tn Pentium
  47 and
  48 .Tn "Pentium Pro"
  49 CPUs.
  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.
  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.
  72 It
  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.
  75 .Pp
  76 The following
  77 .Xr ioctl 2
  78 requests are defined:
  79 .Bl -tag -width PMIOTSTAMP
  80 .It Dv PMIOSETUP
  81 .Pq Li "struct pmc"
  82 Set up a counter with parameters and flags defined in the structure.
  83 The following fields are defined in
  84 .Li struct pmc :
  85 .Bl -tag -width "u_char pmc_eventx"
  86 .It Li "int pmc_num"
  87 the number of the counter in question; must be less than
  88 .Dv NPMC
  89 (currently 2).
  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
  95 .Tn Intel
  96 documentation).
  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
 102 number of clocks.
 103 .El
 104 .Pp
 105 The following
 106 .Li pmc_flags
 107 values are defined:
 108 .Bl -tag -compact -width PMCF_USRxx
 109 .It Dv PMCF_USR
 110 count events in user mode
 111 .It Dv PMCF_OS
 112 count events in kernel mode
 113 .It Dv PMCF_E
 114 count number of events rather than their duration
 115 .It Dv PMCF_INV
 116 invert the sense of the counter mask comparison
 117 .El
 118 .It Dv PMIOGET
 119 .Pq Li "struct pmc"
 120 returns the current configuration of the specified counter.
 121 .It Dv PMIOSTART
 122 .It Dv PMIOSTOP
 123 .Pq Li int
 124 starts (stops) the specified counter.
 125 Due to hardware deficiencies,
 126 counters must be started and stopped in numerical order.
 127 (That is to
 128 say, counter 0 can never be stopped without first stopping counter 1.)
 129 The driver will
 130 .Em not
 131 enforce this restriction (since it may not be present in future CPUs).
 132 .It Dv PMIORESET
 133 .Pq Li int
 134 reset the specified counter to zero.
 135 The counter should be stopped
 136 with
 137 .Dv PMIOSTOP
 138 before it is reset.
 139 All counters are automatically reset by
 140 .Dv PMIOSETUP .
 141 .It Dv PMIOREAD
 142 .Pq Li "struct pmc_data"
 143 get the current value of the counter.
 144 The
 145 .Li pmc_data
 146 structure defines two fields:
 147 .Pp
 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
 153 .El
 154 .Pp
 155 In the future, it may be possible to use the
 156 .Li RDPMC
 157 instruction on
 158 .Tn "Pentium Pro"
 159 processors to read the counters directly.
 160 .It Dv PMIOTSTAMP
 161 .Pq Li "struct pmc_tstamp"
 162 read the time stamp counter.
 163 The
 164 .Li pmc_tstamp
 165 structure defines two fields:
 166 .Pp
 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
 172 .El
 173 .Pp
 174 It is important to note that the counter rate, as provided in the
 175 .Li pmct_rate
 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
 180 clock ticks.
 181 .El
 182 .Sh FILES
 183 .Bl -tag -compact -width "/usr/include/machine/perfmon.h"
 184 .It Pa /dev/perfmon
 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
 190 .Fn ioctl
 191 commands
 192 .El
 193 .Sh SEE ALSO
 194 .Xr ioctl 2 ,
 195 .Xr hwpmc 4
 196 .Rs
 197 .%A Intel Corporation
 198 .%B Pentium Pro Family Developer's Manual
 199 .%D January 1996
 200 .%V vol. 3
 201 .%O Operating System Writer's Manual
 202 .Re
 203 .Sh HISTORY
 204 The
 205 .Nm
 206 device first appeared in
 207 .Fx 2.2 .
 208 .Sh AUTHORS
 209 The
 210 .Nm
 211 driver was written by
 212 .An Garrett A. Wollman ,
 213 MIT Laboratory for Computer Science.