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.\" $Id$ 30.Dd March 26, 1996 31.Dt PERFMON 4 i386 32.Os FreeBSD 2.2 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 perfmon 43driver provides access to the internal performance-monitoring 44capabilities of the 45.Tn Intel 46.Tn Pentium 47and 48.Tn "Pentium Pro" 49CPUs. These processors implement two internal counters which can be 50configured to measure a variety of events for either count or duration 51(in CPU cycles), as well as a cycle counter which counts clock cycles. 52The 53.Nm 54driver provides a device-style interface to these capabilities. 55.Pp 56All access to the performance-monitoring counters is performed through 57the special device file 58.Dq Pa /dev/perfmon . 59This device supports a number of 60.Xr ioctl 2 61requests, defined in 62.Aq Pa machine/perfmon.h 63along with the definitions of the various counters for both 64.Tn Pentium 65and 66.Tn "Pentium Pro" 67processors. 68.Pp 69.Sy NOTA BENE : 70The set of available events differs from processor to processor. It 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.Aq Pa 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. Due to hardware deficiencies, 123counters must be started and stopped in numerical order. (That is to 124say, counter 0 can never be stopped without first stopping counter 1.) 125The driver will 126.Em not 127enforce this restriction (since it may not be present in future CPUs). 128.It Dv PMIORESET 129.Pq Li int 130reset the specified counter to zero. The counter should be stopped 131with 132.Dv PMIOSTOP 133before it is reset. All counters are automatically reset by 134.Dv PMIOSETUP . 135.It Dv PMIOREAD 136.Pq Li "struct pmc_data" 137get the current value of the counter. The 138.Li pmc_data 139structure defines two fields: 140.Pp 141.Bl -tag -compact -width "quad_t pmcd_value" 142.It Li "int pmcd_num" 143the number of the counter to read 144.It Li "int pmcd_value" 145the resulting value as a 64-bit signed integer 146.El 147.Pp 148In the future, it may be possible to use the 149.Li RDPMC 150instruction on 151.Tn "Pentium Pro" 152processors to read the counters directly. 153.It Dv PMIOTSTAMP 154.Pq Li "struct pmc_tstamp" 155read the time stamp counter. The 156.Li pmc_tstamp 157structure defines two fields: 158.Pp 159.Bl -tag -compact -width "quad_t pmct_value" 160.It Li "int pmct_rate" 161the approximate rate of the counter, in MHz 162.It Li "quad_t pmct_value" 163the current value of the counter as a 64-bit integer 164.El 165.Pp 166It is important to note that the counter rate, as provided in the 167.Li pmct_rate 168field, is often incorrect because of calibration difficulties and 169non-integral clock rates. This field should be considered more of a 170hint or sanity-check than an actual representation of the rate of 171clock ticks. 172.El 173.Sh FILES 174.Bl -tag -compact -width "/usr/include/machine/perfmon.h" 175.It Pa /dev/perfmon 176character device interface to counters 177.It Pa /usr/include/machine/perfmon.h 178include file with definitions of structures and event types 179.It Pa /usr/share/examples/perfmon 180sample source code demonstrating use of all the 181.Fn ioctl 182commands 183.El 184.Sh SEE ALSO 185.Xr ioctl 2 186.Rs 187.%A Intel Corporation 188.%B Pentium Pro Family Developer's Manual 189.%D January 1996 190.%V vol. 3 191.%O Operating System Writer's Manual 192.Re 193.Sh HISTORY 194The 195.Nm 196device first appeared in 197.Fx 2.2 . 198.Sh AUTHOR 199The 200.Nm 201driver was written by Garrett A. Wollman, MIT Laboratory for Computer 202Science. 203