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