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.Dd March 26, 1996 29.Dt PERFMON 4 i386 30.Os 31.Sh NAME 32.Nm perfmon 33.Nd CPU performance-monitoring interface 34.Sh SYNOPSIS 35.Cd cpu I586_CPU 36.Cd cpu I686_CPU 37.Cd options PERFMON 38.Sh DESCRIPTION 39The 40.Nm 41driver provides access to the internal performance-monitoring 42capabilities of the 43.Tn Intel 44.Tn Pentium 45and 46.Tn "Pentium Pro" 47CPUs. 48These processors implement two internal counters which can be 49configured to measure a variety of events for either count or duration 50(in CPU cycles), as well as a cycle counter which counts clock cycles. 51The 52.Nm 53driver provides a device-style interface to these capabilities. 54.Pp 55All access to the performance-monitoring counters is performed through 56the special device file 57.Dq Pa /dev/perfmon . 58This device supports a number of 59.Xr ioctl 2 60requests, defined in 61.In machine/perfmon.h 62along with the definitions of the various counters for both 63.Tn Pentium 64and 65.Tn "Pentium Pro" 66processors. 67.Pp 68.Sy NOTA BENE : 69The set of available events differs from processor to processor. 70It 71is the responsibility of the programmer to ensure that the event 72numbers used are the correct ones for the CPU type being measured. 73.Pp 74The following 75.Xr ioctl 2 76requests are defined: 77.Bl -tag -width PMIOTSTAMP 78.It Dv PMIOSETUP 79.Pq Li "struct pmc" 80Set up a counter with parameters and flags defined in the structure. 81The following fields are defined in 82.Li struct pmc : 83.Bl -tag -width "u_char pmc_eventx" 84.It Li "int pmc_num" 85the number of the counter in question; must be less than 86.Dv NPMC 87(currently 2). 88.It Li "u_char pmc_event" 89the particular event number to be monitored, as defined in 90.In machine/perfmon.h . 91.It Li "u_char pmc_unit" 92the unit mask value, specific to the event type (see the 93.Tn Intel 94documentation). 95.It Li "u_char pmc_flags" 96flags modifying the operation of the counter (see below). 97.It Li "u_char pmc_mask" 98the counter mask value; essentially, this is a threshold used to 99restrict the count to events lasting more (or less) than the specified 100number of clocks. 101.El 102.Pp 103The following 104.Li pmc_flags 105values are defined: 106.Bl -tag -compact -width PMCF_USRxx 107.It Dv PMCF_USR 108count events in user mode 109.It Dv PMCF_OS 110count events in kernel mode 111.It Dv PMCF_E 112count number of events rather than their duration 113.It Dv PMCF_INV 114invert the sense of the counter mask comparison 115.El 116.It Dv PMIOGET 117.Pq Li "struct pmc" 118returns the current configuration of the specified counter. 119.It Dv PMIOSTART 120.It Dv PMIOSTOP 121.Pq Li int 122starts (stops) the specified counter. 123Due to hardware deficiencies, 124counters must be started and stopped in numerical order. 125(That is to 126say, counter 0 can never be stopped without first stopping counter 1.) 127The driver will 128.Em not 129enforce this restriction (since it may not be present in future CPUs). 130.It Dv PMIORESET 131.Pq Li int 132reset the specified counter to zero. 133The counter should be stopped 134with 135.Dv PMIOSTOP 136before it is reset. 137All counters are automatically reset by 138.Dv PMIOSETUP . 139.It Dv PMIOREAD 140.Pq Li "struct pmc_data" 141get the current value of the counter. 142The 143.Li pmc_data 144structure defines two fields: 145.Pp 146.Bl -tag -compact -width "quad_t pmcd_value" 147.It Li "int pmcd_num" 148the number of the counter to read 149.It Li "quad_t pmcd_value" 150the resulting value as a 64-bit signed integer 151.El 152.Pp 153In the future, it may be possible to use the 154.Li RDPMC 155instruction on 156.Tn "Pentium Pro" 157processors to read the counters directly. 158.It Dv PMIOTSTAMP 159.Pq Li "struct pmc_tstamp" 160read the time stamp counter. 161The 162.Li pmc_tstamp 163structure defines two fields: 164.Pp 165.Bl -tag -compact -width "quad_t pmct_value" 166.It Li "int pmct_rate" 167the approximate rate of the counter, in MHz 168.It Li "quad_t pmct_value" 169the current value of the counter as a 64-bit integer 170.El 171.Pp 172It is important to note that the counter rate, as provided in the 173.Li pmct_rate 174field, is often incorrect because of calibration difficulties and 175non-integral clock rates. 176This field should be considered more of a 177hint or sanity-check than an actual representation of the rate of 178clock ticks. 179.El 180.Sh FILES 181.Bl -tag -compact -width "/usr/include/machine/perfmon.h" 182.It Pa /dev/perfmon 183character device interface to counters 184.It Pa /usr/include/machine/perfmon.h 185include file with definitions of structures and event types 186.It Pa /usr/share/examples/perfmon 187sample source code demonstrating use of all the 188.Fn ioctl 189commands 190.El 191.Sh SEE ALSO 192.Xr ioctl 2 , 193.Xr hwpmc 4 194.Rs 195.%A Intel Corporation 196.%B Pentium Pro Family Developer's Manual 197.%D January 1996 198.%V vol. 3 199.%O Operating System Writer's Manual 200.Re 201.Sh HISTORY 202The 203.Nm 204device first appeared in 205.Fx 2.2 . 206.Sh AUTHORS 207The 208.Nm 209driver was written by 210.An Garrett A. Wollman , 211MIT Laboratory for Computer Science. 212