Move PMC documentation to separate manual pages, one per PMC class.

1 files changed, 239 insertions, 0 deletions

diff --git a/lib/libpmc/pmc.k7.3 b/lib/libpmc/pmc.k7.3
new file mode 100644
index 0000000..745a56b
--- /dev/null
+++ b/lib/libpmc/pmc.k7.3
@@ -0,0 +1,239 @@
+.\" 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.K7 3
+.Sh NAME
+.Nm pmc.k7
+.Nd measurement events for
+.Tn AMD
+.Tn Athlon
+(K7 family) CPUs
+.Sh LIBRARY
+.Lb libpmc
+.Sh SYNOPSIS
+.In pmc.h
+.Sh DESCRIPTION
+AMD K7 PMCs are present in the
+.Tn "AMD Athlon"
+series of CPUs and are documented in:
+.Rs
+.%B "AMD Athlon Processor x86 Code Optimization Guide"
+.%N "Publication No. 22007"
+.%D "February 2002"
+.%Q "Advanced Micro Devices, Inc."
+.Re
+.Ss PMC Features
+AMD K7 PMCs are 48 bits wide.
+Each K7 CPU contains 4 PMCs with 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 Yes
+.It PMC_CAP_INTERRUPT Ta Yes
+.It PMC_CAP_INVERT Ta Yes
+.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 Yes
+.It PMC_CAP_USER Ta Yes
+.It PMC_CAP_WRITE Ta Yes
+.El
+.Ss Event Qualifiers
+.Pp
+Event specifiers for AMD K7 PMCs can have the following optional
+qualifiers:
+.Bl -tag -width indent
+.It Li count= Ns Ar value
+Configure the counter to increment only if the number of configured
+events measured in a cycle is greater than or equal to
+.Ar value .
+.It Li edge
+Configure the counter to only count negated-to-asserted transitions
+of the conditions expressed by the other qualifiers.
+In other words, the counter will increment only once whenever a given
+condition becomes true, irrespective of the number of clocks during
+which the condition remains true.
+.It Li inv
+Invert the sense of comparision when the
+.Dq Li count
+qualifier is present, making the counter to increment when the
+number of events per cycle is less than the value specified by
+the
+.Dq Li count
+qualifier.
+.It Li os
+Configure the PMC to count events happening at privilege level 0.
+.It Li unitmask= Ns Ar mask
+This qualifier is used to further qualify a select few events,
+.Dq Li k7-dc-refills-from-l2 ,
+.Dq Li k7-dc-refills-from-system
+and
+.Dq Li k7-dc-writebacks .
+Here
+.Ar mask
+is a string of the following characters optionally separated by
+.Ql +
+characters:
+.Pp
+.Bl -tag -width indent -compact
+.It Li m
+Count operations for lines in the
+.Dq Modified
+state.
+.It Li o
+Count operations for lines in the
+.Dq Owner
+state.
+.It Li e
+Count operations for lines in the
+.Dq Exclusive
+state.
+.It Li s
+Count operations for lines in the
+.Dq Shared
+state.
+.It Li i
+Count operations for lines in the
+.Dq Invalid
+state.
+.El
+.Pp
+If no
+.Dq Li unitmask
+qualifier is specified, the default is to count events for caches
+lines in any of the above states.
+.It Li usr
+Configure the PMC to count events occurring at privilege levels 1, 2
+or 3.
+.El
+.Pp
+If neither of the
+.Dq Li os
+or
+.Dq Li usr
+qualifiers were specified, the default is to enable both.
+.Ss AMD K7 Event Specifiers
+The event specifiers supported on AMD K7 PMCs are:
+.Bl -tag -width indent
+.It Li k7-dc-accesses
+Count data cache accesses.
+.It Li k7-dc-misses
+Count data cache misses.
+.It Li k7-dc-refills-from-l2 Op Li ,unitmask= Ns Ar mask
+Count data cache refills from L2 cache.
+This event may be further qualified using the
+.Dq Li unitmask
+qualifier.
+.It Li k7-dc-refills-from-system Op Li ,unitmask= Ns Ar mask
+Count data cache refills from system memory.
+This event may be further qualified using the
+.Dq Li unitmask
+qualifier.
+.It Li k7-dc-writebacks Op Li ,unitmask= Ns Ar mask
+Count data cache writebacks.
+This event may be further qualified using the
+.Dq Li unitmask
+qualifier.
+.It Li k7-l1-dtlb-miss-and-l2-dtlb-hits
+Count L1 DTLB misses and L2 DTLB hits.
+.It Li k7-l1-and-l2-dtlb-misses
+Count L1 and L2 DTLB misses.
+.It Li k7-misaligned-references
+Count misaligned data references.
+.It Li k7-ic-fetches
+Count instruction cache fetches.
+.It Li k7-ic-misses
+Count instruction cache misses.
+.It Li k7-l1-itlb-misses
+Count L1 ITLB misses that are L2 ITLB hits.
+.It Li k7-l1-l2-itlb-misses
+Count L1 (and L2) ITLB misses.
+.It Li k7-retired-instructions
+Count all retired instructions.
+.It Li k7-retired-ops
+Count retired ops.
+.It Li k7-retired-branches
+Count all retired branches (conditional, unconditional, exceptions
+and interrupts).
+.It Li k7-retired-branches-mispredicted
+Count all misprediced retired branches.
+.It Li k7-retired-taken-branches
+Count retired taken branches.
+.It Li k7-retired-taken-branches-mispredicted
+Count mispredicted taken branches that were retired.
+.It Li k7-retired-far-control-transfers
+Count retired far control transfers.
+.It Li k7-retired-resync-branches
+Count retired resync branches (non control transfer branches).
+.It Li k7-interrupts-masked-cycles
+Count the number of cycles when the processor's
+.Va IF
+flag was zero.
+.It Li k7-interrupts-masked-while-pending-cycles
+Count the number of cycles interrupts were masked while pending due
+to the processor's
+.Va IF
+flag being zero.
+.It Li k7-hardware-interrupts
+Count the number of taken hardware interrupts.
+.El
+.Ss Event Name Aliases
+The following table shows the mapping between the PMC-independent
+aliases supported by
+.Lb libpmc
+and the underlying hardware events used.
+.Bl -column "branch-mispredicts" "Description"
+.It Em Alias Ta Em Event
+.It Li branches Ta Li k7-retired-branches
+.It Li branch-mispredicts Ta Li k7-retired-branches-mispredicted
+.It Li dc-misses Ta Li k7-dc-misses
+.It Li ic-misses Ta Li k7-ic-misses
+.It Li instructions Ta Li k7-retired-instructions
+.It Li interrupts Ta Li k7-hardware-interrupts
+.It Li unhalted-cycles Ta (unsupported)
+.El
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr pmc.k8 3 ,
+.Xr pmc.p4 3 ,
+.Xr pmc.p5 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 .