1
2The contents of this directory allow users to specify PMU events in their
3CPUs by their symbolic names rather than raw event codes (see example below).
4
5The main program in this directory, is the 'jevents', which is built and
6executed _BEFORE_ the perf binary itself is built.
7
8The 'jevents' program tries to locate and process JSON files in the directory
9tree 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
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).
16
17	- Directories are traversed, but all other files are ignored.
18
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
25The PMU events supported by a CPU model are expected to grouped into topics
26such as Pipelining, Cache, Memory, Floating-point etc. All events for a topic
27should be placed in a separate JSON file - where the file name identifies
28the topic. Eg: "Floating-point.json".
29
30All the topic JSON files for a CPU model/family should be in a separate
31sub directory. Thus for the Silvermont X86 CPU:
32
33	$ ls tools/perf/pmu-events/arch/x86/silvermont
34	cache.json     memory.json    virtual-memory.json
35	frontend.json  pipeline.json
36
37The JSONs folder for a CPU model/family may be placed in the root arch
38folder, or may be placed in a vendor sub-folder under the arch folder
39for instances where the arch and vendor are not the same.
40
41Using 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
75After 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
78NOTES:
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
89At run time, perf determines the actual CPU it is running on, finds the
90matching events table and builds aliases for those events. This allows
91users to specify events by their name:
92
93	$ perf stat -e pm_1plus_ppc_cmpl sleep 1
94
95where 'pm_1plus_ppc_cmpl' is a Power8 PMU event.
96
97However some errors in processing may cause the alias build to fail.
98
99Mapfile format
100===============
101
102The mapfile enables multiple CPU models to share a single set of PMU events.
103It is required even if such mapping is 1:1.
104
105The mapfile.csv format is expected to be:
106
107	Header line
108	CPUID,Version,Dir/path/name,Type
109
110where:
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 be 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 are "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
148	GenuineIntel-6-4D,v13,silvermont,core
149	GenuineIntel-6-4C,v13,silvermont,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'.
153