-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
164 lines (115 loc) · 5.24 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
# pmu-events
pmu-events from linux/tools/perf modified for use outside of perf
The files include/pmu-events/kernel-defs.h and src/kernel-defs.c contain code lifted from elsewhere
in the kernel to make it work.
The files include/pmu-events/util.h and src/$ARCH/util.c contain architecture specific functions.
The arch/ directory, include/pmu-events/pmu-events.h and jevents.py are lifted from the pmu-events directory. If possible (to ease updates, modifications should be done elsewhere.
example/ contains an example for using this API.
The contents of this directory allow users to specify PMU events in their
CPUs by their symbolic names rather than raw event codes (see example below).
The main program in this directory, is the 'jevents', which is built and
executed _BEFORE_ the perf binary itself is built.
The 'jevents' program tries to locate and process JSON files in the directory
tree tools/perf/pmu-events/arch/foo.
- Regular files with '.json' extension in the name are assumed to be
JSON files, each of which describes a set of PMU events.
- The CSV file that maps a specific CPU to its set of PMU events is to
be named 'mapfile.csv' (see below for mapfile format).
- Directories are traversed, but all other files are ignored.
- To reduce JSON event duplication per architecture, platform JSONs may
use "ArchStdEvent" keyword to dereference an "Architecture standard
events", defined in architecture standard JSONs.
Architecture standard JSONs must be located in the architecture root
folder. Matching is based on the "EventName" field.
The PMU events supported by a CPU model are expected to grouped into topics
such as Pipelining, Cache, Memory, Floating-point etc. All events for a topic
should be placed in a separate JSON file - where the file name identifies
the topic. Eg: "Floating-point.json".
All the topic JSON files for a CPU model/family should be in a separate
sub directory. Thus for the Silvermont X86 CPU:
$ ls tools/perf/pmu-events/arch/x86/silvermont
cache.json memory.json virtual-memory.json
frontend.json pipeline.json
The JSONs folder for a CPU model/family may be placed in the root arch
folder, or may be placed in a vendor sub-folder under the arch folder
for instances where the arch and vendor are not the same.
Using the JSON files and the mapfile, 'jevents' generates the C source file,
'pmu-events.c', which encodes the two sets of tables:
- Set of 'PMU events tables' for all known CPUs in the architecture,
(one table like the following, per JSON file; table name 'pme_power8'
is derived from JSON file name, 'power8.json').
struct pmu_event pme_power8[] = {
...
{
.name = "pm_1plus_ppc_cmpl",
.event = "event=0x100f2",
.desc = "1 or more ppc insts finished,",
},
...
}
- A 'mapping table' that maps each CPU of the architecture, to its
'PMU events table'
struct pmu_events_map pmu_events_map[] = {
{
.cpuid = "004b0000",
.version = "1",
.type = "core",
.table = pme_power8
},
...
};
After the 'pmu-events.c' is generated, it is compiled and the resulting
'pmu-events.o' is added to 'libperf.a' which is then used to build perf.
NOTES:
1. Several CPUs can support same set of events and hence use a common
JSON file. Hence several entries in the pmu_events_map[] could map
to a single 'PMU events table'.
2. The 'pmu-events.h' has an extern declaration for the mapping table
and the generated 'pmu-events.c' defines this table.
3. _All_ known CPU tables for architecture are included in the perf
binary.
At run time, perf determines the actual CPU it is running on, finds the
matching events table and builds aliases for those events. This allows
users to specify events by their name:
$ perf stat -e pm_1plus_ppc_cmpl sleep 1
where 'pm_1plus_ppc_cmpl' is a Power8 PMU event.
However some errors in processing may cause the alias build to fail.
Mapfile format
===============
The mapfile enables multiple CPU models to share a single set of PMU events.
It is required even if such mapping is 1:1.
The mapfile.csv format is expected to be:
Header line
CPUID,Version,Dir/path/name,Type
where:
Comma:
is the required field delimiter (i.e other fields cannot
have commas within them).
Comments:
Lines in which the first character is either '\n' or '#'
are ignored.
Header line
The header line is the first line in the file, which is
always _IGNORED_. It can be empty.
CPUID:
CPUID is an arch-specific char string, that can be used
to identify CPU (and associate it with a set of PMU events
it supports). Multiple CPUIDS can point to the same
File/path/name.json.
Example:
CPUID == 'GenuineIntel-6-2E' (on x86).
CPUID == '004b0100' (PVR value in Powerpc)
Version:
is the Version of the mapfile.
Dir/path/name:
is the pathname to the directory containing the CPU's JSON
files, relative to the directory containing the mapfile.csv
Type:
indicates whether the events are "core" or "uncore" events.
Eg:
$ grep silvermont tools/perf/pmu-events/arch/x86/mapfile.csv
GenuineIntel-6-37,v13,silvermont,core
GenuineIntel-6-4D,v13,silvermont,core
GenuineIntel-6-4C,v13,silvermont,core
i.e the three CPU models use the JSON files (i.e PMU events) listed
in the directory 'tools/perf/pmu-events/arch/x86/silvermont'.