1 1
2 The contents of this directory allow users to 2 The contents of this directory allow users to specify PMU events in their
3 CPUs by their symbolic names rather than raw e 3 CPUs by their symbolic names rather than raw event codes (see example below).
4 4
5 The main program in this directory, is the 'je 5 The main program in this directory, is the 'jevents', which is built and
6 executed _BEFORE_ the perf binary itself is bu 6 executed _BEFORE_ the perf binary itself is built.
7 7
8 The 'jevents' program tries to locate and proc 8 The 'jevents' program tries to locate and process JSON files in the directory
9 tree tools/perf/pmu-events/arch/foo. 9 tree tools/perf/pmu-events/arch/foo.
10 10
11 - Regular files with '.json' extension 11 - Regular files with '.json' extension in the name are assumed to be
12 JSON files, each of which describes 12 JSON files, each of which describes a set of PMU events.
13 13
14 - The CSV file that maps a specific CP !! 14 - Regular files with basename starting with 'mapfile.csv' are assumed
15 be named 'mapfile.csv' (see below fo !! 15 to be a CSV file that maps a specific CPU to its set of PMU events.
>> 16 (see below for mapfile format)
16 17
17 - Directories are traversed, but all o 18 - Directories are traversed, but all other files are ignored.
18 19
19 - To reduce JSON event duplication per <<
20 use "ArchStdEvent" keyword to derefe <<
21 events", defined in architecture sta <<
22 Architecture standard JSONs must be <<
23 folder. Matching is based on the "Ev <<
24 <<
25 The PMU events supported by a CPU model are ex 20 The PMU events supported by a CPU model are expected to grouped into topics
26 such as Pipelining, Cache, Memory, Floating-po 21 such as Pipelining, Cache, Memory, Floating-point etc. All events for a topic
27 should be placed in a separate JSON file - whe 22 should be placed in a separate JSON file - where the file name identifies
28 the topic. Eg: "Floating-point.json". 23 the topic. Eg: "Floating-point.json".
29 24
30 All the topic JSON files for a CPU model/famil 25 All the topic JSON files for a CPU model/family should be in a separate
31 sub directory. Thus for the Silvermont X86 CPU 26 sub directory. Thus for the Silvermont X86 CPU:
32 27
33 $ ls tools/perf/pmu-events/arch/x86/si !! 28 $ ls tools/perf/pmu-events/arch/x86/Silvermont_core
34 cache.json memory.json virtual- !! 29 Cache.json Memory.json Virtual-Memory.json
35 frontend.json pipeline.json !! 30 Frontend.json Pipeline.json
36 <<
37 The JSONs folder for a CPU model/family may be <<
38 folder, or may be placed in a vendor sub-folde <<
39 for instances where the arch and vendor are no <<
40 31
41 Using the JSON files and the mapfile, 'jevents 32 Using the JSON files and the mapfile, 'jevents' generates the C source file,
42 'pmu-events.c', which encodes the two sets of 33 'pmu-events.c', which encodes the two sets of tables:
43 34
44 - Set of 'PMU events tables' for all k 35 - Set of 'PMU events tables' for all known CPUs in the architecture,
45 (one table like the following, per J 36 (one table like the following, per JSON file; table name 'pme_power8'
46 is derived from JSON file name, 'pow 37 is derived from JSON file name, 'power8.json').
47 38
48 struct pmu_event pme_power8[] 39 struct pmu_event pme_power8[] = {
49 40
50 ... 41 ...
51 42
52 { 43 {
53 .name = "pm_1p 44 .name = "pm_1plus_ppc_cmpl",
54 .event = "even 45 .event = "event=0x100f2",
55 .desc = "1 or 46 .desc = "1 or more ppc insts finished,",
56 }, 47 },
57 48
58 ... 49 ...
59 } 50 }
60 51
61 - A 'mapping table' that maps each CPU 52 - A 'mapping table' that maps each CPU of the architecture, to its
62 'PMU events table' 53 'PMU events table'
63 54
64 struct pmu_events_map pmu_even 55 struct pmu_events_map pmu_events_map[] = {
65 { 56 {
66 .cpuid = "004b0000", 57 .cpuid = "004b0000",
67 .version = "1", 58 .version = "1",
68 .type = "core", 59 .type = "core",
69 .table = pme_power8 60 .table = pme_power8
70 }, 61 },
71 ... 62 ...
72 63
73 }; 64 };
74 65
75 After the 'pmu-events.c' is generated, it is c 66 After the 'pmu-events.c' is generated, it is compiled and the resulting
76 'pmu-events.o' is added to 'libperf.a' which i 67 'pmu-events.o' is added to 'libperf.a' which is then used to build perf.
77 68
78 NOTES: 69 NOTES:
79 1. Several CPUs can support same set o 70 1. Several CPUs can support same set of events and hence use a common
80 JSON file. Hence several entries in 71 JSON file. Hence several entries in the pmu_events_map[] could map
81 to a single 'PMU events table'. 72 to a single 'PMU events table'.
82 73
83 2. The 'pmu-events.h' has an extern de 74 2. The 'pmu-events.h' has an extern declaration for the mapping table
84 and the generated 'pmu-events.c' de 75 and the generated 'pmu-events.c' defines this table.
85 76
86 3. _All_ known CPU tables for architec 77 3. _All_ known CPU tables for architecture are included in the perf
87 binary. 78 binary.
88 79
89 At run time, perf determines the actual CPU it 80 At run time, perf determines the actual CPU it is running on, finds the
90 matching events table and builds aliases for t 81 matching events table and builds aliases for those events. This allows
91 users to specify events by their name: 82 users to specify events by their name:
92 83
93 $ perf stat -e pm_1plus_ppc_cmpl sleep 84 $ perf stat -e pm_1plus_ppc_cmpl sleep 1
94 85
95 where 'pm_1plus_ppc_cmpl' is a Power8 PMU even 86 where 'pm_1plus_ppc_cmpl' is a Power8 PMU event.
96 87
97 However some errors in processing may cause th !! 88 In case of errors when processing files in the tools/perf/pmu-events/arch
>> 89 directory, 'jevents' tries to create an empty mapping file to allow the perf
>> 90 build to succeed even if the PMU event aliases cannot be used.
>> 91
>> 92 However some errors in processing may cause the perf build to fail.
98 93
99 Mapfile format 94 Mapfile format
100 =============== 95 ===============
101 96
102 The mapfile enables multiple CPU models to sha 97 The mapfile enables multiple CPU models to share a single set of PMU events.
103 It is required even if such mapping is 1:1. 98 It is required even if such mapping is 1:1.
104 99
105 The mapfile.csv format is expected to be: 100 The mapfile.csv format is expected to be:
106 101
107 Header line 102 Header line
108 CPUID,Version,Dir/path/name,Type 103 CPUID,Version,Dir/path/name,Type
109 104
110 where: 105 where:
111 106
112 Comma: 107 Comma:
113 is the required field delimite 108 is the required field delimiter (i.e other fields cannot
114 have commas within them). 109 have commas within them).
115 110
116 Comments: 111 Comments:
117 Lines in which the first chara 112 Lines in which the first character is either '\n' or '#'
118 are ignored. 113 are ignored.
119 114
120 Header line 115 Header line
121 The header line is the first l 116 The header line is the first line in the file, which is
122 always _IGNORED_. It can be em !! 117 always _IGNORED_. It can empty.
123 118
124 CPUID: 119 CPUID:
125 CPUID is an arch-specific char 120 CPUID is an arch-specific char string, that can be used
126 to identify CPU (and associate 121 to identify CPU (and associate it with a set of PMU events
127 it supports). Multiple CPUIDS 122 it supports). Multiple CPUIDS can point to the same
128 File/path/name.json. 123 File/path/name.json.
129 124
130 Example: 125 Example:
131 CPUID == 'GenuineIntel 126 CPUID == 'GenuineIntel-6-2E' (on x86).
132 CPUID == '004b0100' (P 127 CPUID == '004b0100' (PVR value in Powerpc)
133 Version: 128 Version:
134 is the Version of the mapfile. 129 is the Version of the mapfile.
135 130
136 Dir/path/name: 131 Dir/path/name:
137 is the pathname to the directo 132 is the pathname to the directory containing the CPU's JSON
138 files, relative to the directo 133 files, relative to the directory containing the mapfile.csv
139 134
140 Type: 135 Type:
141 indicates whether the events a !! 136 indicates whether the events or "core" or "uncore" events.
142 137
143 138
144 Eg: 139 Eg:
145 140
146 $ grep silvermont tools/perf/pmu-event !! 141 $ grep Silvermont tools/perf/pmu-events/arch/x86/mapfile.csv
147 GenuineIntel-6-37,v13,silvermont,core !! 142 GenuineIntel-6-37,V13,Silvermont_core,core
148 GenuineIntel-6-4D,v13,silvermont,core !! 143 GenuineIntel-6-4D,V13,Silvermont_core,core
149 GenuineIntel-6-4C,v13,silvermont,core !! 144 GenuineIntel-6-4C,V13,Silvermont_core,core
150 145
151 i.e the three CPU models use the JSON 146 i.e the three CPU models use the JSON files (i.e PMU events) listed
152 in the directory 'tools/perf/pmu-event !! 147 in the directory 'tools/perf/pmu-events/arch/x86/Silvermont_core'.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.