lib/libpmc/pmc.k7.3

   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
  40 AMD K7 PMCs are present in the
  41 .Tn "AMD Athlon"
  42 series 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
  50 AMD K7 PMCs are 48 bits wide.
  51 Each 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
  67 Event specifiers for AMD K7 PMCs can have the following optional
  68 qualifiers:
  69 .Bl -tag -width indent
  70 .It Li count= Ns Ar value
  71 Configure the counter to increment only if the number of configured
  72 events measured in a cycle is greater than or equal to
  73 .Ar value .
  74 .It Li edge
  75 Configure the counter to only count negated-to-asserted transitions
  76 of the conditions expressed by the other qualifiers.
  77 In other words, the counter will increment only once whenever a given
  78 condition becomes true, irrespective of the number of clocks during
  79 which the condition remains true.
  80 .It Li inv
  81 Invert the sense of comparison when the
  82 .Dq Li count
  83 qualifier is present, making the counter to increment when the
  84 number of events per cycle is less than the value specified by
  85 the
  86 .Dq Li count
  87 qualifier.
  88 .It Li os
  89 Configure the PMC to count events happening at privilege level 0.
  90 .It Li unitmask= Ns Ar mask
  91 This 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
  94 and
  95 .Dq Li k7-dc-writebacks .
  96 Here
  97 .Ar mask
  98 is a string of the following characters optionally separated by
  99 .Ql +
 100 characters:
 101 .Pp
 102 .Bl -tag -width indent -compact
 103 .It Li m
 104 Count operations for lines in the
 105 .Dq Modified
 106 state.
 107 .It Li o
 108 Count operations for lines in the
 109 .Dq Owner
 110 state.
 111 .It Li e
 112 Count operations for lines in the
 113 .Dq Exclusive
 114 state.
 115 .It Li s
 116 Count operations for lines in the
 117 .Dq Shared
 118 state.
 119 .It Li i
 120 Count operations for lines in the
 121 .Dq Invalid
 122 state.
 123 .El
 124 .Pp
 125 If no
 126 .Dq Li unitmask
 127 qualifier is specified, the default is to count events for caches
 128 lines in any of the above states.
 129 .It Li usr
 130 Configure the PMC to count events occurring at privilege levels 1, 2
 131 or 3.
 132 .El
 133 .Pp
 134 If neither of the
 135 .Dq Li os
 136 or
 137 .Dq Li usr
 138 qualifiers were specified, the default is to enable both.
 139 .Ss AMD K7 Event Specifiers
 140 The event specifiers supported on AMD K7 PMCs are:
 141 .Bl -tag -width indent
 142 .It Li k7-dc-accesses
 143 .Pq Event 40H
 144 Count data cache accesses.
 145 .It Li k7-dc-misses
 146 .Pq Event 41H
 147 Count data cache misses.
 148 .It Li k7-dc-refills-from-l2 Op Li ,unitmask= Ns Ar mask
 149 .Pq Event 42H
 150 Count data cache refills from L2 cache.
 151 This event may be further qualified using the
 152 .Dq Li unitmask
 153 qualifier.
 154 .It Li k7-dc-refills-from-system Op Li ,unitmask= Ns Ar mask
 155 .Pq Event 43H
 156 Count data cache refills from system memory.
 157 This event may be further qualified using the
 158 .Dq Li unitmask
 159 qualifier.
 160 .It Li k7-dc-writebacks Op Li ,unitmask= Ns Ar mask
 161 .Pq Event 44H
 162 Count data cache writebacks.
 163 This event may be further qualified using the
 164 .Dq Li unitmask
 165 qualifier.
 166 .It Li k7-hardware-interrupts
 167 .Pq Event CFH
 168 Count the number of taken hardware interrupts.
 169 .It Li k7-ic-fetches
 170 .Pq Event 80H
 171 Count instruction cache fetches.
 172 .It Li k7-ic-misses
 173 .Pq Event 81H
 174 Count instruction cache misses.
 175 .It Li k7-interrupts-masked-cycles
 176 .Pq Event CDH
 177 Count the number of cycles when the processor's
 178 .Va IF
 179 flag was zero.
 180 .It Li k7-interrupts-masked-while-pending-cycles
 181 .Pq Event CEH
 182 Count the number of cycles interrupts were masked while pending due
 183 to the processor's
 184 .Va IF
 185 flag being zero.
 186 .It Li k7-l1-and-l2-dtlb-misses
 187 .Pq Event 46H
 188 Count L1 and L2 DTLB misses.
 189 .It Li k7-l1-dtlb-miss-and-l2-dtlb-hits
 190 .Pq Event 45H
 191 Count L1 DTLB misses and L2 DTLB hits.
 192 .It Li k7-l1-itlb-misses
 193 .Pq Event 84H
 194 Count L1 ITLB misses that are L2 ITLB hits.
 195 .It Li k7-l1-l2-itlb-misses
 196 .Pq Event 85H
 197 Count L1 (and L2) ITLB misses.
 198 .It Li k7-misaligned-references
 199 .Pq Event 47H
 200 Count misaligned data references.
 201 .It Li k7-retired-branches
 202 .Pq Event C2H
 203 Count all retired branches (conditional, unconditional, exceptions
 204 and interrupts).
 205 .It Li k7-retired-branches-mispredicted
 206 .Pq Event C3H
 207 Count all mispredicted retired branches.
 208 .It Li k7-retired-far-control-transfers
 209 .Pq Event C6H
 210 Count retired far control transfers.
 211 .It Li k7-retired-instructions
 212 .Pq Event C0H
 213 Count all retired instructions.
 214 .It Li k7-retired-ops
 215 .Pq Event C1H
 216 Count retired ops.
 217 .It Li k7-retired-resync-branches
 218 .Pq Event C7H
 219 Count retired resync branches (non control transfer branches).
 220 .It Li k7-retired-taken-branches
 221 .Pq Event C4H
 222 Count retired taken branches.
 223 .It Li k7-retired-taken-branches-mispredicted
 224 .Pq Event C5H
 225 Count mispredicted taken branches that were retired.
 226 .El
 227 .Ss Event Name Aliases
 228 The following table shows the mapping between the PMC-independent
 229 aliases supported by
 230 .Lb libpmc
 231 and 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
 257 The
 258 .Nm pmc
 259 library first appeared in
 260 .Fx 6.0 .
 261 .Sh AUTHORS
 262 The
 263 .Lb libpmc
 264 library was written by
 265 .An "Joseph Koshy"
 266 .Aq jkoshy@FreeBSD.org .