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