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.4 2007/11/04 19:04:42 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 ".Dv 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.