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