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