0001
0002 The contents of this directory allow users to specify PMU events in their
0003 CPUs by their symbolic names rather than raw event codes (see example below).
0004
0005 The main program in this directory, is the 'jevents', which is built and
0006 executed _BEFORE_ the perf binary itself is built.
0007
0008 The 'jevents' program tries to locate and process JSON files in the directory
0009 tree tools/perf/pmu-events/arch/foo.
0010
0011 - Regular files with '.json' extension in the name are assumed to be
0012 JSON files, each of which describes a set of PMU events.
0013
0014 - The CSV file that maps a specific CPU to its set of PMU events is to
0015 be named 'mapfile.csv' (see below for mapfile format).
0016
0017 - Directories are traversed, but all other files are ignored.
0018
0019 - To reduce JSON event duplication per architecture, platform JSONs may
0020 use "ArchStdEvent" keyword to dereference an "Architecture standard
0021 events", defined in architecture standard JSONs.
0022 Architecture standard JSONs must be located in the architecture root
0023 folder. Matching is based on the "EventName" field.
0024
0025 The PMU events supported by a CPU model are expected to grouped into topics
0026 such as Pipelining, Cache, Memory, Floating-point etc. All events for a topic
0027 should be placed in a separate JSON file - where the file name identifies
0028 the topic. Eg: "Floating-point.json".
0029
0030 All the topic JSON files for a CPU model/family should be in a separate
0031 sub directory. Thus for the Silvermont X86 CPU:
0032
0033 $ ls tools/perf/pmu-events/arch/x86/silvermont
0034 cache.json memory.json virtual-memory.json
0035 frontend.json pipeline.json
0036
0037 The JSONs folder for a CPU model/family may be placed in the root arch
0038 folder, or may be placed in a vendor sub-folder under the arch folder
0039 for instances where the arch and vendor are not the same.
0040
0041 Using the JSON files and the mapfile, 'jevents' generates the C source file,
0042 'pmu-events.c', which encodes the two sets of tables:
0043
0044 - Set of 'PMU events tables' for all known CPUs in the architecture,
0045 (one table like the following, per JSON file; table name 'pme_power8'
0046 is derived from JSON file name, 'power8.json').
0047
0048 struct pmu_event pme_power8[] = {
0049
0050 ...
0051
0052 {
0053 .name = "pm_1plus_ppc_cmpl",
0054 .event = "event=0x100f2",
0055 .desc = "1 or more ppc insts finished,",
0056 },
0057
0058 ...
0059 }
0060
0061 - A 'mapping table' that maps each CPU of the architecture, to its
0062 'PMU events table'
0063
0064 struct pmu_events_map pmu_events_map[] = {
0065 {
0066 .cpuid = "004b0000",
0067 .version = "1",
0068 .type = "core",
0069 .table = pme_power8
0070 },
0071 ...
0072
0073 };
0074
0075 After the 'pmu-events.c' is generated, it is compiled and the resulting
0076 'pmu-events.o' is added to 'libperf.a' which is then used to build perf.
0077
0078 NOTES:
0079 1. Several CPUs can support same set of events and hence use a common
0080 JSON file. Hence several entries in the pmu_events_map[] could map
0081 to a single 'PMU events table'.
0082
0083 2. The 'pmu-events.h' has an extern declaration for the mapping table
0084 and the generated 'pmu-events.c' defines this table.
0085
0086 3. _All_ known CPU tables for architecture are included in the perf
0087 binary.
0088
0089 At run time, perf determines the actual CPU it is running on, finds the
0090 matching events table and builds aliases for those events. This allows
0091 users to specify events by their name:
0092
0093 $ perf stat -e pm_1plus_ppc_cmpl sleep 1
0094
0095 where 'pm_1plus_ppc_cmpl' is a Power8 PMU event.
0096
0097 However some errors in processing may cause the alias build to fail.
0098
0099 Mapfile format
0100 ===============
0101
0102 The mapfile enables multiple CPU models to share a single set of PMU events.
0103 It is required even if such mapping is 1:1.
0104
0105 The mapfile.csv format is expected to be:
0106
0107 Header line
0108 CPUID,Version,Dir/path/name,Type
0109
0110 where:
0111
0112 Comma:
0113 is the required field delimiter (i.e other fields cannot
0114 have commas within them).
0115
0116 Comments:
0117 Lines in which the first character is either '\n' or '#'
0118 are ignored.
0119
0120 Header line
0121 The header line is the first line in the file, which is
0122 always _IGNORED_. It can be empty.
0123
0124 CPUID:
0125 CPUID is an arch-specific char string, that can be used
0126 to identify CPU (and associate it with a set of PMU events
0127 it supports). Multiple CPUIDS can point to the same
0128 File/path/name.json.
0129
0130 Example:
0131 CPUID == 'GenuineIntel-6-2E' (on x86).
0132 CPUID == '004b0100' (PVR value in Powerpc)
0133 Version:
0134 is the Version of the mapfile.
0135
0136 Dir/path/name:
0137 is the pathname to the directory containing the CPU's JSON
0138 files, relative to the directory containing the mapfile.csv
0139
0140 Type:
0141 indicates whether the events are "core" or "uncore" events.
0142
0143
0144 Eg:
0145
0146 $ grep silvermont tools/perf/pmu-events/arch/x86/mapfile.csv
0147 GenuineIntel-6-37,v13,silvermont,core
0148 GenuineIntel-6-4D,v13,silvermont,core
0149 GenuineIntel-6-4C,v13,silvermont,core
0150
0151 i.e the three CPU models use the JSON files (i.e PMU events) listed
0152 in the directory 'tools/perf/pmu-events/arch/x86/silvermont'.
