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