From 9ec48f3bd4887e942f34791dac62dbee2e155367 Mon Sep 17 00:00:00 2001 From: jkoshy Date: Tue, 16 Sep 2008 16:34:55 +0000 Subject: Move PMC documentation to separate manual pages, one per PMC class. --- lib/libpmc/pmc.p5.3 | 402 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 402 insertions(+) create mode 100644 lib/libpmc/pmc.p5.3 (limited to 'lib/libpmc/pmc.p5.3') diff --git a/lib/libpmc/pmc.p5.3 b/lib/libpmc/pmc.p5.3 new file mode 100644 index 0000000..aaf0a8f --- /dev/null +++ b/lib/libpmc/pmc.p5.3 @@ -0,0 +1,402 @@ +.\" Copyright (c) 2003-2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" $FreeBSD$ +.\" +.Dd September 16, 2008 +.Os +.Dt PMC 3 +.Sh NAME +.Nm pmc +.Nd library for accessing hardware performance monitoring counters +.Sh LIBRARY +.Lb libpmc +.Sh SYNOPSIS +.In pmc.h +.Sh DESCRIPTION +Intel Pentium PMCs are present in Intel +.Tn Pentium +and +.Tn "Pentium MMX" +processors. +These PMCs are documented in the +.Rs +.%B "Intel 64 and IA-32 Intel(R) Architectures Software Developer's Manual" +.%T "Volume 3B: System Programming Guide, Part 2" +.%N "Order Number 253669-024US" +.%D "August 2007" +.%Q "Intel Corporation" +.Re +.Ss PMC Features +These CPUs contain two PMCs, each 40 bits wide. +These PMCs support the following capabilities: +.Bl -column "PMC_CAP_INTERRUPT" "Support" +.It Em Capability Ta Em Support +.It PMC_CAP_CASCADE Ta \&No +.It PMC_CAP_EDGE Ta \&No +.It PMC_CAP_INTERRUPT Ta \&No +.It PMC_CAP_INVERT Ta \&No +.It PMC_CAP_READ Ta Yes +.It PMC_CAP_PRECISE Ta \&No +.It PMC_CAP_SYSTEM Ta Yes +.It PMC_CAP_TAGGING Ta \&No +.It PMC_CAP_THRESHOLD Ta \&No +.It PMC_CAP_USER Ta Yes +.It PMC_CAP_WRITE Ta Yes +.El +.Ss Event Qualifiers +Event specifiers for Intel Pentium PMCs can have the following common +qualifiers: +.Bl -tag -width indent +.It Li duration +Count duration (in clocks) of events. +The default is to count events. +.It Li os +Measure events at privilege levels 0, 1 and 2. +.It Li overflow +Assert the external processor pin associated with a counter on counter +overflow. +.It Li usr +Measure events at privilege level 3. +.El +.Pp +If neither of the +.Dq Li os +or +.Dq Li usr +qualifiers are specified, the default is to enable both. +.Pp +Some events may only be used on specific counters and some events +are defined only on processors supporting the MMX instruction set. +Note that these PMCs do not have the ability to interrupt the CPU. +.Ss Intel Pentium Event Specifiers +The event specifiers supported by Intel Pentium PMCs are: +.Bl -tag -width indent +.It Li p5-any-segment-register-loaded +The number of writes to any segment register, including the LDTR, +GDTR, TR and IDTR. +Far control transfers and task switches that involve privilege +level changes will count this event twice. +.It Li p5-bank-conflicts +The number of actual bank conflicts. +.It Li p5-branches +The number of taken and not taken branches including branches, jumps, calls, +software interrupts and interrupt returns. +.It Li p5-breakpoint-match-on-dr0-register +The number of matches on the DR0 breakpoint register. +.It Li p5-breakpoint-match-on-dr1-register +The number of matches on the DR1 breakpoint register. +.It Li p5-breakpoint-match-on-dr2-register +The number of matches on the DR2 breakpoint register. +.It Li p5-breakpoint-match-on-dr3-register +The number of matches on the DR3 breakpoint register. +.It Li p5-btb-false-entries +.Pq Tn Pentium MMX +The number of false entries in the BTB. +This event is only allocated on counter 0. +.It Li p5-btb-hits +The number of branches executed that hit in the branch table buffer. +.It Li p5-btb-miss-prediction-on-not-taken-branch +.Pq Tn Pentium MMX +The number of times the BTB predicted a not-taken branch as taken. +This event is only allocated on counter 1. +.It Li p5-bus-cycle-duration +The number of cycles while a bus cycle was in progress. +.It Li p5-bus-ownership-latency +.Pq Tn Pentium MMX +The time from bus ownership being requested to ownership being granted. +This event is only allocated on counter 0. +.It Li p5-bus-ownership-transfers +.Pq Tn Pentium MMX +The number of bus ownership transfers. +This event is only allocated on counter 1. +.It Li p5-bus-utilization-due-to-processor-activity +.Pq Tn Pentium MMX +The number of clocks the bus is busy due to the processor's own +activity. +This event is only allocated on counter 0. +.It Li p5-cache-line-sharing +.Pq Tn Pentium MMX +The number of shared data lines in L1 cache. +This event is only allocated on counter 1. +.It Li p5-cache-m-state-line-sharing +.Pq Tn Pentium MMX +The number of hits to an M- state line due to a memory access by +another processor. +This event is only allocated on counter 0. +.It Li p5-code-cache-miss +The number of instruction reads that miss the internal code cache. +Both cacheable and uncacheable misses are counted. +.It Li p5-code-read +The number of instruction reads to both cacheable and uncacheable regions. +.It Li p5-code-tlb-miss +The number of instruction reads that miss the instruction TLB. +Both cacheable and uncacheable unreads are counted. +.It Li p5-d1-starvation-and-fifo-is-empty +.Pq Tn Pentium MMX +The number of times the D1 stage cannot issue any instructions because +the FIFO was empty. +This event is only allocated on counter 0. +.It Li p5-d1-starvation-and-only-one-instruction-in-fifo +.Pq Tn Pentium MMX +The number of times the D1 stage could issue only one instruction +because the FIFO had one instruction ready. +This event is only allocated on counter 1. +.It Li p5-data-cache-lines-written-back +The number of data cache lines that are written back, including +those caused by internal and external snoops. +.It Li p5-data-cache-tlb-miss-stall-duration +.Pq Tn Pentium MMX +The number of clocks the pipeline is stalled due to a data cache +TLB miss. +This event is only allocated on counter 1. +.It Li p5-data-read +The number of memory data reads, counting internal data cache hits and +misses. +I/O and data memory accesses due to TLB miss processing are +not included. +Split cycle reads are counted individually. +.It Li p5-data-read-miss +The number of memory read accesses that miss the data cache, counting +both cacheable and uncacheable accesses. +Data accesses that are part of TLB miss processing are not included. +I/O accesses are not included. +.It Li p5-data-read-miss-or-write-miss +The number of data reads and writes that miss the internal data cache, +counting uncacheable accesses. +Data accesses due to TLB miss processing are not counted. +.It Li p5-data-read-or-write +The number of data reads and writes including internal data cache hits +and misses. +Data reads due to TLB miss processing are not counted. +.It Li p5-data-tlb-miss +The number of misses to the data cache translation lookaside buffer. +.It Li p5-data-write +The number of memory data writes, counting internal data cache hits +and misses. +I/O is not included and split cycle writes are counted individually. +.It Li p5-data-write-miss +The number of memory write accesses that miss the data cache, counting +both cacheable and uncacheable accesses. +I/O accesses are not counted. +.It Li p5-emms-instructions-executed +.Pq Tn Pentium MMX +The number of EMMS instructions executed. +This event is only allocated on counter 0. +.It Li p5-external-data-cache-snoop-hits +The number of external snoops to the data cache that hit a valid line, +or the data line fill buffer, or one of the write back buffers. +.It Li p5-external-snoops +The number of external snoop requests accepted, including snoops that +hit in the code cache, the data cache and that hit in neither. +.It Li p5-floating-point-stalls-duration +.Pq Tn Pentium MMX +The number of cycles the pipeline is stalled due to a floating point +freeze. +This event is only allocated on counter 0. +.It Li p5-flops +The number of floating point adds, subtracts, multiples, divides and +square roots. +Transcendental instructions trigger this event multiple times. +Instructions generating divide-by-zero, negative square root, special +operand and stack exceptions are not counted. +Integer multiply instructions that use the x87 FPU are counted. +.It Li p5-full-write-buffer-stall-duration-while-executing-mmx-instructions +.Pq Tn Pentium MMX +The number of clocks the pipeline has stalled due to full write +buffers when executing MMX instructions. +This event is only allocated on counter 0. +.It Li p5-hardware-interrupts +The number of taken INTR and NMI interrupts. +.It Li p5-instructions-executed +The number of instructions executed. +Repeat prefixed instructions are counted only once. +The HLT instruction is counted only once, irrespective of the number +of cycles spent in the halted state. +All hardware and software exceptions are counted as instructions, and +fault handler invocations are also counted as instructions. +.It Li p5-instructions-executed-v-pipe +The number of instructions that executed in the V pipe. +.It Li p5-io-read-or-write-cycle +The number of bus cycles directed to I/O space. +.It Li p5-locked-bus-cycle +The number of locked bus cycles that occur on account of the lock +prefixes, LOCK instructions, page table updates and descriptor table +updates. +.It Li p5-memory-accesses-in-both-pipes +The number of data memory reads or writes that are paired in both pipes. +.It Li p5-misaligned-data-memory-on-mmx-instructions +.Pq Tn Pentium MMX +The number of misaligned data memory references when executing MMX +instructions. +This event is only allocated on counter 0. +.It Li p5-misaligned-data-memory-or-io-references +The number of memory or I/O reads or writes that are not aligned on +natural boundaries. +2- and 4-byte accesses are counted as misaligned if they cross a 4 +byte boundary. +.It Li p5-mispredicted-or-unpredicted-returns +.Pq Tn Pentium MMX +The number of returns predicted incorrectly or not at all, only +counting RET instructions. +This event is only allocated on counter 0. +.It Li p5-mmx-instruction-data-read-misses +.Pq Tn Pentium MMX +The number of MMX instruction data read misses. +This event is only allocated on counter 1. +.It Li p5-mmx-instruction-data-reads +.Pq Tn Pentium MMX +The number of MMX instruction data reads. +This event is only allocated on counter 0. +.It Li p5-mmx-instruction-data-write-misses +.Pq Tn Pentium MMX +The number of data write misses caused by MMX instructions. +This event is only allocated on counter 1. +.It Li p5-mmx-instruction-data-writes +.Pq Tn Pentium MMX +The number of data writes caused by MMX instructions. +This event is only allocated on counter 0. +.It Li p5-mmx-instructions-executed-u-pipe +.Pq Tn Pentium MMX +The number of MMX instructions executed in the U pipe. +This event is only allocated on counter 0. +.It Li p5-mmx-instructions-executed-v-pipe +The number of MMX instructions executed in the V pipe. +This event is only allocated on counter 1. +.It Li p5-mmx-multiply-unit-interlock +.Pq Tn Pentium MMX +The number of clocks the pipeline is stalled because the destination +of a prior MMX multiply is not ready. +This event is only allocated on counter 0. +.It Li p5-movd-movq-store-stall-due-to-previous-mmx-operation +.Pq Tn Pentium MMX +The number of clocks a MOVD/MOVQ instruction stalled in the D2 stage +of the pipeline due to a previous MMX instruction. +This event is only allocated on counter 1. +.It Li p5-noncacheable-memory-reads +The number of bus cycles for non-cacheable instruction or data reads, +including cycles caused by TLB misses. +.It Li p5-number-of-cycles-not-in-halt-state +.Pq Tn Pentium MMX +The number of cycles the processor is not idle due to the HLT +instruction. +This event is only allocated on counter 0. +.It Li p5-pipeline-agi-stalls +The number of address generation interlock stalls. +An AGI that occurs in both the U and V pipelines in the same clock +signals the event twice. +.It Li p5-pipeline-flushes +The number of pipeline flushes that occur. +Pipeline flushes are caused by branch mispredicts, exceptions, +interrupts, some segment register loads, and BTB misses. +Prefetch queue flushes due to serializing instructions are not +counted. +.It Li p5-pipeline-flushes-due-to-wrong-branch-predictions +.Pq Tn Pentium MMX +The number of pipeline flushes due to wrong branch predictions +resolved in either the E- or WB- stage of the pipeline. +This event is only allocated on counter 0. +.It Li p5-pipeline-flushes-due-to-wrong-branch-predictions-resolved-in-wb-stage +.Pq Tn Pentium MMX +The number of pipeline flushes due to wrong branch predictions +resolved in the stage of the pipeline. +This event is only allocated on counter 1. +.It Li p5-pipeline-stall-for-mmx-instruction-data-memory-reads +.Pq Tn Pentium MMX +The number of clocks during pipeline stalls caused by waiting MMX data +memory reads. +This event is only allocated on counter 0. +.It Li p5-predicted-returns +.Pq Tn Pentium MMX +The number of predicted returns, whether correct or incorrect. +This counter only counts RET instructions. +This event is only allocated on counter 1. +.It Li p5-returns +.Pq Tn Pentium MMX +The number of RET instructions executed. +This event is only allocated on counter 0. +.It Li p5-saturating-mmx-instructions-executed +.Pq Tn Pentium MMX +The number of saturating MMX instructions executed. +This event is only allocated on counter 0. +.It Li p5-saturations-performed +.Pq Tn Pentium MMX +The number of saturating MMX instructions executed when at least one +of its results were actually saturated. +This event is only allocated on counter 1. +.It Li p5-stall-on-mmx-instruction-write-to-e-o-m-state-line +.Pq Tn Pentium MMX +The number of clocks during stalls on MMX instructions writing to +E- or M- state cache lines. +This event is only allocated on counter 1. +.It Li p5-stall-on-write-to-an-e-or-m-state-line +The number of stalls on a write to an exclusive or modified data cache +line. +.It Li p5-taken-branch-or-btb-hit +The number of events that may cause a hit in the BTB, namely either +taken branches or BTB hits. +.It Li p5-taken-branches +.Pq Tn Pentium MMX +The number of taken branches. +This event is only allocated on counter 1. +.It Li p5-transitions-between-mmx-and-fp-instructions +.Pq Tn Pentium MMX +The number of transitions between MMX and floating-point instructions +and vice-versa. +This event is only allocated on counter 1. +.It Li p5-waiting-for-data-memory-read-stall-duration +The number of clocks the pipeline was stalled waiting for data +memory reads. +Data TLB misses processing is included in this count. +.It Li p5-write-buffer-full-stall-duration +The number of clocks while the pipeline was stalled due to write +buffers being full. +.It Li p5-write-hit-to-m-or-e-state-lines +The number of writes that hit exclusive or modified lines in the data +cache. +.It Li p5-writes-to-noncacheable-memory +.Pq Tn Pentium MMX +The number of writes to non-cacheable memory, including write cycles +caused by TLB misses and I/O writes. +This event is only allocated on counter 1. +.El +.Sh SEE ALSO +.Xr pmc 3 , +.Xr pmc.k7 3 , +.Xr pmc.k8 3 , +.Xr pmc.p4 3 , +.Xr pmc.p6 3 , +.Xr pmc.tsc 3 , +.Xr pmclog 3 , +.Xr hwpmc 4 +.Sh HISTORY +The +.Nm pmc +library first appeared in +.Fx 6.0 . +.Sh AUTHORS +The +.Lb libpmc +library was written by +.An "Joseph Koshy" +.Aq jkoshy@FreeBSD.org . -- cgit v1.1