tools/perf/pmu-events/README

   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
  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
  20 The PMU events supported by a CPU model are expected to grouped into topics
  21 such as Pipelining, Cache, Memory, Floating-point etc. All events for a topic
  22 should be placed in a separate JSON file - where the file name identifies
  23 the topic. Eg: "Floating-point.json".
  24
  25 All the topic JSON files for a CPU model/family should be in a separate
  26 sub 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
  32 Using 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
  66 After 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
  69 NOTES:
  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
  80 At run time, perf determines the actual CPU it is running on, finds the
  81 matching events table and builds aliases for those events. This allows
  82 users to specify events by their name:
  83
  84         $ perf stat -e pm_1plus_ppc_cmpl sleep 1
  85
  86 where 'pm_1plus_ppc_cmpl' is a Power8 PMU event.
  87
  88 In case of errors when processing files in the tools/perf/pmu-events/arch
  89 directory, 'jevents' tries to create an empty mapping file to allow the perf
  90 build to succeed even if the PMU event aliases cannot be used.
  91
  92 However some errors in processing may cause the perf build to fail.
  93
  94 Mapfile format
  95 ===============
  96
  97 The mapfile enables multiple CPU models to share a single set of PMU events.
  98 It is required even if such mapping is 1:1.
  99
 100 The mapfile.csv format is expected to be:
 101
 102         Header line
 103         CPUID,Version,Dir/path/name,Type
 104
 105 where:
 106
 107         Comma:
 108                 is the required field delimiter (i.e other fields cannot
 109                 have commas within them).
 110
 111         Comments:
 112                 Lines in which the first character is either '\n' or '#'
 113                 are ignored.
 114
 115         Header line
 116                 The header line is the first line in the file, which is
 117                 always _IGNORED_. It can empty.
 118
 119         CPUID:
 120                 CPUID is an arch-specific char string, that can be used
 121                 to identify CPU (and associate it with a set of PMU events
 122                 it supports). Multiple CPUIDS can point to the same
 123                 File/path/name.json.
 124
 125                 Example:
 126                         CPUID == 'GenuineIntel-6-2E' (on x86).
 127                         CPUID == '004b0100' (PVR value in Powerpc)
 128         Version:
 129                 is the Version of the mapfile.
 130
 131         Dir/path/name:
 132                 is the pathname to the directory containing the CPU's JSON
 133                 files, relative to the directory containing the mapfile.csv
 134
 135         Type:
 136                 indicates whether the events or "core" or "uncore" events.
 137
 138
 139         Eg:
 140
 141         $ grep Silvermont tools/perf/pmu-events/arch/x86/mapfile.csv
 142         GenuineIntel-6-37,V13,Silvermont_core,core
 143         GenuineIntel-6-4D,V13,Silvermont_core,core
 144         GenuineIntel-6-4C,V13,Silvermont_core,core
 145
 146         i.e the three CPU models use the JSON files (i.e PMU events) listed
 147         in the directory 'tools/perf/pmu-events/arch/x86/Silvermont_core'.