1.\" Copyright (c) 2008 Joseph Koshy. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.Dd November 14, 2008 25.Dt PMC.IAF 3 26.Os 27.Sh NAME 28.Nm pmc.iaf 29.Nd measurement events for 30.Tn Intel 31fixed function performance counters. 32.Sh LIBRARY 33.Lb libpmc 34.Sh SYNOPSIS 35.In pmc.h 36.Sh DESCRIPTION 37.Tn Intel 38fixed-function PMCs are present in CPUs that conform to version 2 or 39later of the 40.Tn Intel 41Performance Measurement Architecture. 42Each fixed-function PMC measures a specific hardware event. 43The number of fixed-function PMCs implemented in a CPU can vary. 44The number of fixed-function PMCs present can be determined at runtime 45by using function 46.Xr pmc_cpuinfo 3 . 47.Pp 48Intel fixed-function PMCs are documented in 49.Rs 50.%B "IA-32 Intel(R) Architecture Software Developer's Manual" 51.%T "Volume 3: System Programming Guide" 52.%N "Order Number 253669-027US" 53.%D July 2008 54.%Q "Intel Corporation" 55.Re 56.Ss PMC Capabilities 57Fixed-function PMCs support the following capabilities: 58.Bl -column "PMC_CAP_INTERRUPT" "Support" 59.It Em Capability Ta Em Support 60.It PMC_CAP_CASCADE Ta \&No 61.It PMC_CAP_EDGE Ta \&No 62.It PMC_CAP_INTERRUPT Ta Yes 63.It PMC_CAP_INVERT Ta \&No 64.It PMC_CAP_READ Ta Yes 65.It PMC_CAP_PRECISE Ta \&No 66.It PMC_CAP_SYSTEM Ta Yes 67.It PMC_CAP_TAGGING Ta \&No 68.It PMC_CAP_THRESHOLD Ta \&No 69.It PMC_CAP_USER Ta Yes 70.It PMC_CAP_WRITE Ta Yes 71.El 72.Ss Class Name Prefix 73These PMCs are named using a class name prefix of 74.Dq Li iaf- . 75.Ss Event Qualifiers (Fixed Function PMCs) 76These PMCs support the following modifiers: 77.Bl -tag -width indent 78.It Li os 79Configure the PMC to count events occurring at ring level 0. 80.It Li usr 81Configure the PMC to count events occurring at ring levels 1, 2 82or 3. 83.It Li anythread 84.Pq Tn Atom CPUs 85Configure the PMC to count events on all logical processors sharing a 86processor core. 87The default is to count events on the current logical processor. 88.El 89.Pp 90If neither of the 91.Dq Li os 92or 93.Dq Li usr 94qualifiers are specified, the default is to enable both. 95.Ss Event Specifiers (Fixed Function PMCs) 96The fixed function PMCs are selectable using the following 97event names: 98.Bl -tag -width indent 99.It Li INSTR_RETIRED.ANY 100.Pq Fixed Function Counter 0 101The number of instructions retired. 102.It Li CPU_CLK_UNHALTED.CORE 103.Pq Fixed Function Counter 1 104The number of core cycles for which the core is not halted. 105.It Li CPU_CLK_UNHALTED.REF 106.Pq Fixed Function Counter 2 107The number of reference cycles for which the core is not halted. 108.El 109.Sh EXAMPLES 110To measure the number of core cycles for which the core was not halted 111use the event specifier 112.Qq iaf-cpu-clk-unhalted.core . 113.Pp 114To measure the number of user instructions retired use the event specifier 115.Qq iaf-instr-retired.any,usr . 116.Pp 117To measure the number of user instructions retired on all logical processors 118in an 119.Tn Atom 120CPU, use the event specifier 121.Qq iaf-instr-retired.any,usr,anythread . 122.Sh SEE ALSO 123.Xr pmc 3 , 124.Xr pmc.amd 3 , 125.Xr pmc.atom 3 , 126.Xr pmc.core 3 , 127.Xr pmc.core2 3 , 128.Xr pmc.soft 3 , 129.Xr pmc.tsc 3 , 130.Xr pmc_cpuinfo 3 , 131.Xr pmclog 3 , 132.Xr hwpmc 4 133.Sh HISTORY 134The 135.Nm pmc 136library first appeared in 137.Fx 6.0 . 138.Sh AUTHORS 139The 140.Lb libpmc 141library was written by 142.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . 143