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 3 28.Os 29.Sh NAME 30.Nm pmc 31.Nd library for accessing hardware performance monitoring counters 32.Sh LIBRARY 33.Lb libpmc 34.Sh SYNOPSIS 35.In pmc.h 36.Sh DESCRIPTION 37Intel Pentium PMCs are present in Intel 38.Tn Pentium 39and 40.Tn "Pentium MMX" 41processors. 42These PMCs are documented in the 43.Rs 44.%B "Intel 64 and IA-32 Intel(R) Architectures Software Developer's Manual" 45.%T "Volume 3B: System Programming Guide, Part 2" 46.%N "Order Number 253669-024US" 47.%D "August 2007" 48.%Q "Intel Corporation" 49.Re 50.Ss PMC Features 51These CPUs contain two PMCs, each 40 bits wide. 52These PMCs support the following capabilities: 53.Bl -column "PMC_CAP_INTERRUPT" "Support" 54.It Em Capability Ta Em Support 55.It PMC_CAP_CASCADE Ta \&No 56.It PMC_CAP_EDGE Ta \&No 57.It PMC_CAP_INTERRUPT Ta \&No 58.It PMC_CAP_INVERT Ta \&No 59.It PMC_CAP_READ Ta Yes 60.It PMC_CAP_PRECISE Ta \&No 61.It PMC_CAP_SYSTEM Ta Yes 62.It PMC_CAP_TAGGING Ta \&No 63.It PMC_CAP_THRESHOLD Ta \&No 64.It PMC_CAP_USER Ta Yes 65.It PMC_CAP_WRITE Ta Yes 66.El 67.Ss Event Qualifiers 68Event specifiers for Intel Pentium PMCs can have the following common 69qualifiers: 70.Bl -tag -width indent 71.It Li duration 72Count duration (in clocks) of events. 73The default is to count events. 74.It Li os 75Measure events at privilege levels 0, 1 and 2. 76.It Li overflow 77Assert the external processor pin associated with a counter on counter 78overflow. 79.It Li usr 80Measure events at privilege level 3. 81.El 82.Pp 83If neither of the 84.Dq Li os 85or 86.Dq Li usr 87qualifiers are specified, the default is to enable both. 88.Pp 89Some events may only be used on specific counters and some events 90are defined only on processors supporting the MMX instruction set. 91Note that these PMCs do not have the ability to interrupt the CPU. 92.Ss Intel Pentium Event Specifiers 93The event specifiers supported by Intel Pentium PMCs are: 94.Bl -tag -width indent 95.It Li p5-any-segment-register-loaded 96.Pq Event 0FH 97The number of writes to any segment register, including the LDTR, 98GDTR, TR and IDTR. 99Far control transfers and task switches that involve privilege 100level changes will count this event twice. 101.It Li p5-bank-conflicts 102.Pq Event 0AH 103The number of actual bank conflicts. 104.It Li p5-branches 105.Pq Event 12H 106The number of taken and not taken branches including branches, jumps, calls, 107software interrupts and interrupt returns. 108.It Li p5-breakpoint-match-on-dr0-register 109.Pq Event 23H 110The number of matches on the DR0 breakpoint register. 111.It Li p5-breakpoint-match-on-dr1-register 112.Pq Event 24H 113The number of matches on the DR1 breakpoint register. 114.It Li p5-breakpoint-match-on-dr2-register 115.Pq Event 25H 116The number of matches on the DR2 breakpoint register. 117.It Li p5-breakpoint-match-on-dr3-register 118.Pq Event 26H 119The number of matches on the DR3 breakpoint register. 120.It Li p5-btb-false-entries 121.Pq Event 3AH , Tn Pentium MMX 122The number of false entries in the BTB. 123This event is only allocated on counter 0. 124.It Li p5-btb-hits 125.Pq Event 13H 126The number of branches executed that hit in the branch table buffer. 127.It Li p5-btb-miss-prediction-on-not-taken-branch 128.Pq Event 3AH , Tn Pentium MMX 129The number of times the BTB predicted a not-taken branch as taken. 130This event is only allocated on counter 1. 131.It Li p5-bus-cycle-duration 132.Pq Event 18H 133The number of cycles while a bus cycle was in progress. 134.It Li p5-bus-ownership-latency 135.Pq Event 2AH , Tn Pentium MMX 136The time from bus ownership being requested to ownership being granted. 137This event is only allocated on counter 0. 138.It Li p5-bus-ownership-transfers 139.Pq Event 2AH , Tn Pentium MMX 140The number of bus ownership transfers. 141This event is only allocated on counter 1. 142.It Li p5-bus-utilization-due-to-processor-activity 143.Pq Event 2EH , Tn Pentium MMX 144The number of clocks the bus is busy due to the processor's own 145activity. 146This event is only allocated on counter 0. 147.It Li p5-cache-line-sharing 148.Pq Event 2CH , Tn Pentium MMX 149The number of shared data lines in L1 cache. 150This event is only allocated on counter 1. 151.It Li p5-cache-m-state-line-sharing 152.Pq Event 2CH , Tn Pentium MMX 153The number of hits to an M- state line due to a memory access by 154another processor. 155This event is only allocated on counter 0. 156.It Li p5-code-cache-miss 157.Pq Event 0EH 158The number of instruction reads that miss the internal code cache. 159Both cacheable and un-cacheable misses are counted. 160.It Li p5-code-read 161.Pq Event 0CH 162The number of instruction reads to both cacheable and un-cacheable regions. 163.It Li p5-code-tlb-miss 164.Pq Event 0DH 165The number of instruction reads that miss the instruction TLB. 166Both cacheable and un-cacheable unreads are counted. 167.It Li p5-d1-starvation-and-fifo-is-empty 168.Pq Event 33H , Tn Pentium MMX 169The number of times the D1 stage cannot issue any instructions because 170the FIFO was empty. 171This event is only allocated on counter 0. 172.It Li p5-d1-starvation-and-only-one-instruction-in-fifo 173.Pq Event 33H , Tn Pentium MMX 174The number of times the D1 stage could issue only one instruction 175because the FIFO had one instruction ready. 176This event is only allocated on counter 1. 177.It Li p5-data-cache-lines-written-back 178.Pq Event 06H 179The number of data cache lines that are written back, including 180those caused by internal and external snoops. 181.It Li p5-data-cache-tlb-miss-stall-duration 182.Pq Event 30H , Tn Pentium MMX 183The number of clocks the pipeline is stalled due to a data cache 184TLB miss. 185This event is only allocated on counter 1. 186.It Li p5-data-read 187.Pq Event 00H 188The number of memory data reads, counting internal data cache hits and 189misses. 190I/O and data memory accesses due to TLB miss processing are 191not included. 192Split cycle reads are counted individually. 193.It Li p5-data-read-miss 194.Pq Event 03H 195The number of memory read accesses that miss the data cache, counting 196both cacheable and un-cacheable accesses. 197Data accesses that are part of TLB miss processing are not included. 198I/O accesses are not included. 199.It Li p5-data-read-miss-or-write-miss 200.Pq Event 29H 201The number of data reads and writes that miss the internal data cache, 202counting un-cacheable accesses. 203Data accesses due to TLB miss processing are not counted. 204.It Li p5-data-read-or-write 205.Pq Event 28H 206The number of data reads and writes including internal data cache hits 207and misses. 208Data reads due to TLB miss processing are not counted. 209.It Li p5-data-tlb-miss 210.Pq Event 02H 211The number of misses to the data cache translation look aside buffer. 212.It Li p5-data-write 213.Pq Event 01H 214The number of memory data writes, counting internal data cache hits 215and misses. 216I/O is not included and split cycle writes are counted individually. 217.It Li p5-data-write-miss 218.Pq Event 04H 219The number of memory write accesses that miss the data cache, counting 220both cacheable and un-cacheable accesses. 221I/O accesses are not counted. 222.It Li p5-emms-instructions-executed 223.Pq Event 2DH , Tn Pentium MMX 224The number of EMMS instructions executed. 225This event is only allocated on counter 0. 226.It Li p5-external-data-cache-snoop-hits 227.Pq Event 08H 228The number of external snoops to the data cache that hit a valid line, 229or the data line fill buffer, or one of the write back buffers. 230.It Li p5-external-snoops 231.Pq Event 07H 232The number of external snoop requests accepted, including snoops that 233hit in the code cache, the data cache and that hit in neither. 234.It Li p5-floating-point-stalls-duration 235.Pq Event 32H , Tn Pentium MMX 236The number of cycles the pipeline is stalled due to a floating point 237freeze. 238This event is only allocated on counter 0. 239.It Li p5-flops 240.Pq Event 22H 241The number of floating point adds, subtracts, multiples, divides and 242square roots. 243Transcendental instructions trigger this event multiple times. 244Instructions generating divide-by-zero, negative square root, special 245operand and stack exceptions are not counted. 246Integer multiply instructions that use the x87 FPU are counted. 247.It Li p5-full-write-buffer-stall-duration-while-executing-mmx-instructions 248.Pq Event 3BH , Tn Pentium MMX 249The number of clocks the pipeline has stalled due to full write 250buffers when executing MMX instructions. 251This event is only allocated on counter 0. 252.It Li p5-hardware-interrupts 253.Pq Event 27H 254The number of taken INTR and NMI interrupts. 255.It Li p5-instructions-executed 256.Pq Event 16H 257The number of instructions executed. 258Repeat prefixed instructions are counted only once. 259The HLT instruction is counted only once, irrespective of the number 260of cycles spent in the halted state. 261All hardware and software exceptions are counted as instructions, and 262fault handler invocations are also counted as instructions. 263.It Li p5-instructions-executed-v-pipe 264.Pq Event 17H 265The number of instructions that executed in the V pipe. 266.It Li p5-io-read-or-write-cycle 267.Pq Event 1DH 268The number of bus cycles directed to I/O space. 269.It Li p5-locked-bus-cycle 270.Pq Event 1CH 271The number of locked bus cycles that occur on account of the lock 272prefixes, LOCK instructions, page table updates and descriptor table 273updates. 274.It Li p5-memory-accesses-in-both-pipes 275.Pq Event 09H 276The number of data memory reads or writes that are paired in both pipes. 277.It Li p5-misaligned-data-memory-or-io-references 278.Pq Event 0BH 279The number of memory or I/O reads or writes that are not aligned on 280natural boundaries. 2812- and 4-byte accesses are counted as misaligned if they cross a 4 282byte boundary. 283.It Li p5-misaligned-data-memory-reference-on-mmx-instructions 284.Pq Event 36H , Tn Pentium MMX 285The number of misaligned data memory references when executing MMX 286instructions. 287This event is only allocated on counter 0. 288.It Li p5-mispredicted-or-unpredicted-returns 289.Pq Event 37H , Tn Pentium MMX 290The number of returns predicted incorrectly or not at all, only 291counting RET instructions. 292This event is only allocated on counter 0. 293.It Li p5-mmx-instruction-data-read-misses 294.Pq Event 31H , Tn Pentium MMX 295The number of MMX instruction data read misses. 296This event is only allocated on counter 1. 297.It Li p5-mmx-instruction-data-reads 298.Pq Event 31H , Tn Pentium MMX 299The number of MMX instruction data reads. 300This event is only allocated on counter 0. 301.It Li p5-mmx-instruction-data-write-misses 302.Pq Event 34H , Tn Pentium MMX 303The number of data write misses caused by MMX instructions. 304This event is only allocated on counter 1. 305.It Li p5-mmx-instruction-data-writes 306.Pq Event 34H , Tn Pentium MMX 307The number of data writes caused by MMX instructions. 308This event is only allocated on counter 0. 309.It Li p5-mmx-instructions-executed-u-pipe 310.Pq Event 2BH , Tn Pentium MMX 311The number of MMX instructions executed in the U pipe. 312This event is only allocated on counter 0. 313.It Li p5-mmx-instructions-executed-v-pipe 314.Pq Event 2BH , Tn Pentium MMX 315The number of MMX instructions executed in the V pipe. 316This event is only allocated on counter 1. 317.It Li p5-mmx-multiply-unit-interlock 318.Pq Event 38H , Tn Pentium MMX 319The number of clocks the pipeline is stalled because the destination 320of a prior MMX multiply is not ready. 321This event is only allocated on counter 0. 322.It Li p5-movd-movq-store-stall-due-to-previous-mmx-operation 323.Pq Event 38H , Tn Pentium MMX 324The number of clocks a MOVD/MOVQ instruction stalled in the D2 stage 325of the pipeline due to a previous MMX instruction. 326This event is only allocated on counter 1. 327.It Li p5-noncacheable-memory-reads 328.Pq Event 1EH 329The number of bus cycles for non-cacheable instruction or data reads, 330including cycles caused by TLB misses. 331.It Li p5-number-of-cycles-not-in-halt-state 332.Pq Event 30H , Tn Pentium MMX 333The number of cycles the processor is not idle due to the HLT 334instruction. 335This event is only allocated on counter 0. 336.It Li p5-pipeline-agi-stalls 337.Pq Event 1FH 338The number of address generation interlock stalls. 339An AGI that occurs in both the U and V pipelines in the same clock 340signals the event twice. 341.It Li p5-pipeline-flushes 342.Pq Event 15H 343The number of pipeline flushes that occur. 344Pipeline flushes are caused by branch mispredicts, exceptions, 345interrupts, some segment register loads, and BTB misses. 346Prefetch queue flushes due to serializing instructions are not 347counted. 348.It Li p5-pipeline-flushes-due-to-wrong-branch-predictions 349.Pq Event 35H , Tn Pentium MMX 350The number of pipeline flushes due to wrong branch predictions 351resolved in either the E- or WB- stage of the pipeline. 352This event is only allocated on counter 0. 353.It Li p5-pipeline-flushes-due-to-wrong-branch-predictions-resolved-in-wb-stage 354.Pq Event 35H , Tn Pentium MMX 355The number of pipeline flushes due to wrong branch predictions 356resolved in the stage of the pipeline. 357This event is only allocated on counter 1. 358.It Li p5-pipeline-stall-for-mmx-instruction-data-memory-reads 359.Pq Event 36H , Tn Pentium MMX 360The number of clocks during pipeline stalls caused by waiting MMX data 361memory reads. 362This event is only allocated on counter 1. 363.It Li p5-predicted-returns 364.Pq Event 37H , Tn Pentium MMX 365The number of predicted returns, whether correct or incorrect. 366This counter only counts RET instructions. 367This event is only allocated on counter 1. 368.It Li p5-returns 369.Pq Event 39H , Tn Pentium MMX 370The number of RET instructions executed. 371This event is only allocated on counter 0. 372.It Li p5-saturating-mmx-instructions-executed 373.Pq Event 2FH , Tn Pentium MMX 374The number of saturating MMX instructions executed. 375This event is only allocated on counter 0. 376.It Li p5-saturations-performed 377.Pq Event 2FH , Tn Pentium MMX 378The number of saturating MMX instructions executed when at least one 379of its results were actually saturated. 380This event is only allocated on counter 1. 381.It Li p5-stall-on-mmx-instruction-write-to-e-o-m-state-line 382.Pq Event 3BH , Tn Pentium MMX 383The number of clocks during stalls on MMX instructions writing to 384E- or M- state cache lines. 385This event is only allocated on counter 1. 386.It Li p5-stall-on-write-to-an-e-or-m-state-line 387.Pq Event 1BH 388The number of stalls on a write to an exclusive or modified data cache 389line. 390.It Li p5-taken-branch-or-btb-hit 391.Pq Event 14H 392The number of events that may cause a hit in the BTB, namely either 393taken branches or BTB hits. 394.It Li p5-taken-branches 395.Pq Event 32H , Tn Pentium MMX 396The number of taken branches. 397This event is only allocated on counter 1. 398.It Li p5-transitions-between-mmx-and-fp-instructions 399.Pq Event 2DH , Tn Pentium MMX 400The number of transitions between MMX and floating-point instructions 401and vice-versa. 402This event is only allocated on counter 1. 403.It Li p5-waiting-for-data-memory-read-stall-duration 404.Pq Event 1AH 405The number of clocks the pipeline was stalled waiting for data 406memory reads. 407Data TLB misses processing is included in this count. 408.It Li p5-write-buffer-full-stall-duration 409.Pq Event 19H 410The number of clocks while the pipeline was stalled due to write 411buffers being full. 412.It Li p5-write-hit-to-m-or-e-state-lines 413.Pq Event 05H 414The number of writes that hit exclusive or modified lines in the data 415cache. 416.It Li p5-writes-to-noncacheable-memory 417.Pq Event 2EH , Tn Pentium MMX 418The number of writes to non-cacheable memory, including write cycles 419caused by TLB misses and I/O writes. 420This event is only allocated on counter 1. 421.El 422.Ss Event Name Aliases 423The following table shows the mapping between the PMC-independent 424aliases supported by 425.Lb libpmc 426and the underlying hardware events used. 427.Bl -column "branch-mispredicts" "Description" 428.It Em Alias Ta Em Event 429.It Li branches Ta Li p5-taken-branches 430.It Li branch-mispredicts Ta Li (unsupported) 431.It Li dc-misses Ta Li p5-data-read-miss-or-write-miss 432.It Li ic-misses Ta Li p5-code-cache-miss 433.It Li instructions Ta Li p5-instructions-executed 434.It Li interrupts Ta Li p5-hardware-interrupts 435.It Li unhalted-cycles Ta Li p5-number-of-cycles-not-in-halt-state 436.El 437.Sh SEE ALSO 438.Xr pmc 3 , 439.Xr pmc.atom 3 , 440.Xr pmc.core 3 , 441.Xr pmc.core2 3 , 442.Xr pmc.iaf 3 , 443.Xr pmc.k7 3 , 444.Xr pmc.k8 3 , 445.Xr pmc.p4 3 , 446.Xr pmc.p6 3 , 447.Xr pmc.soft 3 , 448.Xr pmc.tsc 3 , 449.Xr pmclog 3 , 450.Xr hwpmc 4 451.Sh HISTORY 452The 453.Nm pmc 454library first appeared in 455.Fx 6.0 . 456.Sh AUTHORS 457The 458.Lb libpmc 459library was written by 460.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . 461