1.\" Copyright (c) 2003-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 October 4, 2008 25.Dt PMC.K7 3 26.Os 27.Sh NAME 28.Nm pmc.k7 29.Nd measurement events for 30.Tn AMD 31.Tn Athlon 32(K7 family) CPUs 33.Sh LIBRARY 34.Lb libpmc 35.Sh SYNOPSIS 36.In pmc.h 37.Sh DESCRIPTION 38AMD K7 PMCs are present in the 39.Tn "AMD Athlon" 40series of CPUs and are documented in: 41.Rs 42.%B "AMD Athlon Processor x86 Code Optimization Guide" 43.%N "Publication No. 22007" 44.%D "February 2002" 45.%Q "Advanced Micro Devices, Inc." 46.Re 47.Ss PMC Features 48AMD K7 PMCs are 48 bits wide. 49Each K7 CPU contains 4 PMCs with the following capabilities: 50.Bl -column "PMC_CAP_INTERRUPT" "Support" 51.It Em Capability Ta Em Support 52.It PMC_CAP_CASCADE Ta \&No 53.It PMC_CAP_EDGE Ta Yes 54.It PMC_CAP_INTERRUPT Ta Yes 55.It PMC_CAP_INVERT Ta Yes 56.It PMC_CAP_READ Ta Yes 57.It PMC_CAP_PRECISE Ta \&No 58.It PMC_CAP_SYSTEM Ta Yes 59.It PMC_CAP_TAGGING Ta \&No 60.It PMC_CAP_THRESHOLD Ta Yes 61.It PMC_CAP_USER Ta Yes 62.It PMC_CAP_WRITE Ta Yes 63.El 64.Ss Event Qualifiers 65Event specifiers for AMD K7 PMCs can have the following optional 66qualifiers: 67.Bl -tag -width indent 68.It Li count= Ns Ar value 69Configure the counter to increment only if the number of configured 70events measured in a cycle is greater than or equal to 71.Ar value . 72.It Li edge 73Configure the counter to only count negated-to-asserted transitions 74of the conditions expressed by the other qualifiers. 75In other words, the counter will increment only once whenever a given 76condition becomes true, irrespective of the number of clocks during 77which the condition remains true. 78.It Li inv 79Invert the sense of comparison when the 80.Dq Li count 81qualifier is present, making the counter to increment when the 82number of events per cycle is less than the value specified by 83the 84.Dq Li count 85qualifier. 86.It Li os 87Configure the PMC to count events happening at privilege level 0. 88.It Li unitmask= Ns Ar mask 89This qualifier is used to further qualify a select few events, 90.Dq Li k7-dc-refills-from-l2 , 91.Dq Li k7-dc-refills-from-system 92and 93.Dq Li k7-dc-writebacks . 94Here 95.Ar mask 96is a string of the following characters optionally separated by 97.Ql + 98characters: 99.Pp 100.Bl -tag -width indent -compact 101.It Li m 102Count operations for lines in the 103.Dq Modified 104state. 105.It Li o 106Count operations for lines in the 107.Dq Owner 108state. 109.It Li e 110Count operations for lines in the 111.Dq Exclusive 112state. 113.It Li s 114Count operations for lines in the 115.Dq Shared 116state. 117.It Li i 118Count operations for lines in the 119.Dq Invalid 120state. 121.El 122.Pp 123If no 124.Dq Li unitmask 125qualifier is specified, the default is to count events for caches 126lines in any of the above states. 127.It Li usr 128Configure the PMC to count events occurring at privilege levels 1, 2 129or 3. 130.El 131.Pp 132If neither of the 133.Dq Li os 134or 135.Dq Li usr 136qualifiers were specified, the default is to enable both. 137.Ss AMD K7 Event Specifiers 138The event specifiers supported on AMD K7 PMCs are: 139.Bl -tag -width indent 140.It Li k7-dc-accesses 141.Pq Event 40H 142Count data cache accesses. 143.It Li k7-dc-misses 144.Pq Event 41H 145Count data cache misses. 146.It Li k7-dc-refills-from-l2 Op Li ,unitmask= Ns Ar mask 147.Pq Event 42H 148Count data cache refills from L2 cache. 149This event may be further qualified using the 150.Dq Li unitmask 151qualifier. 152.It Li k7-dc-refills-from-system Op Li ,unitmask= Ns Ar mask 153.Pq Event 43H 154Count data cache refills from system memory. 155This event may be further qualified using the 156.Dq Li unitmask 157qualifier. 158.It Li k7-dc-writebacks Op Li ,unitmask= Ns Ar mask 159.Pq Event 44H 160Count data cache writebacks. 161This event may be further qualified using the 162.Dq Li unitmask 163qualifier. 164.It Li k7-hardware-interrupts 165.Pq Event CFH 166Count the number of taken hardware interrupts. 167.It Li k7-ic-fetches 168.Pq Event 80H 169Count instruction cache fetches. 170.It Li k7-ic-misses 171.Pq Event 81H 172Count instruction cache misses. 173.It Li k7-interrupts-masked-cycles 174.Pq Event CDH 175Count the number of cycles when the processor's 176.Va IF 177flag was zero. 178.It Li k7-interrupts-masked-while-pending-cycles 179.Pq Event CEH 180Count the number of cycles interrupts were masked while pending due 181to the processor's 182.Va IF 183flag being zero. 184.It Li k7-l1-and-l2-dtlb-misses 185.Pq Event 46H 186Count L1 and L2 DTLB misses. 187.It Li k7-l1-dtlb-miss-and-l2-dtlb-hits 188.Pq Event 45H 189Count L1 DTLB misses and L2 DTLB hits. 190.It Li k7-l1-itlb-misses 191.Pq Event 84H 192Count L1 ITLB misses that are L2 ITLB hits. 193.It Li k7-l1-l2-itlb-misses 194.Pq Event 85H 195Count L1 (and L2) ITLB misses. 196.It Li k7-misaligned-references 197.Pq Event 47H 198Count misaligned data references. 199.It Li k7-retired-branches 200.Pq Event C2H 201Count all retired branches (conditional, unconditional, exceptions 202and interrupts). 203.It Li k7-retired-branches-mispredicted 204.Pq Event C3H 205Count all mispredicted retired branches. 206.It Li k7-retired-far-control-transfers 207.Pq Event C6H 208Count retired far control transfers. 209.It Li k7-retired-instructions 210.Pq Event C0H 211Count all retired instructions. 212.It Li k7-retired-ops 213.Pq Event C1H 214Count retired ops. 215.It Li k7-retired-resync-branches 216.Pq Event C7H 217Count retired resync branches (non control transfer branches). 218.It Li k7-retired-taken-branches 219.Pq Event C4H 220Count retired taken branches. 221.It Li k7-retired-taken-branches-mispredicted 222.Pq Event C5H 223Count mispredicted taken branches that were retired. 224.El 225.Ss Event Name Aliases 226The following table shows the mapping between the PMC-independent 227aliases supported by 228.Lb libpmc 229and the underlying hardware events used. 230.Bl -column "branch-mispredicts" "Description" 231.It Em Alias Ta Em Event 232.It Li branches Ta Li k7-retired-branches 233.It Li branch-mispredicts Ta Li k7-retired-branches-mispredicted 234.It Li dc-misses Ta Li k7-dc-misses 235.It Li ic-misses Ta Li k7-ic-misses 236.It Li instructions Ta Li k7-retired-instructions 237.It Li interrupts Ta Li k7-hardware-interrupts 238.It Li unhalted-cycles Ta (unsupported) 239.El 240.Sh SEE ALSO 241.Xr pmc 3 , 242.Xr pmc.atom 3 , 243.Xr pmc.core 3 , 244.Xr pmc.core2 3 , 245.Xr pmc.iaf 3 , 246.Xr pmc.k8 3 , 247.Xr pmc.soft 3 , 248.Xr pmc.tsc 3 , 249.Xr pmclog 3 , 250.Xr hwpmc 4 251.Sh HISTORY 252The 253.Nm pmc 254library first appeared in 255.Fx 6.0 . 256.Sh AUTHORS 257The 258.Lb libpmc 259library was written by 260.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . 261