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