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