Signed-off-by: Sukadev Bhattiprolu <suka...@linux.vnet.ibm.com>
---
tools/perf/pmu-events/README | 115 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 115 insertions(+)
create mode 100644 tools/perf/pmu-events/README
diff --git a/tools/perf/pmu-events/README b/tools/perf/pmu-events/README
new file mode 100644
index 0000000..00fd2e1
--- /dev/null
+++ b/tools/perf/pmu-events/README
@@ -0,0 +1,115 @@
+The contents of this directory allows users to specify PMU events in
+their CPUs by their symbolic names rather than raw event codes (see
+example below).
+
+The main program in this directory, is the 'jevents', which is built and
+executed _before_ the perf binary itself is built.
+
+The 'jevents' program tries to locate and process JSON files in the directory
+tree tools/perf/pmu-events/arch/xxx.
+
+ - Regular files with '.json' extension in the name are assumed to be
+ JSON files.
+
+ - Regular files with base name starting with 'mapfile.csv' are assumed
+ to be a CSV file that - maps a specific CPU to its set of PMU events.
+
+Directories are traversed, but all other files are ignored.
+
+Using the JSON files and the mapfile, 'jevents' generates a C source file,
+'pmu-events.c', which encodes the two sets of tables:
+
+ - Set of 'PMU events tables' for all known CPUs in the architecture,
+ (one table like the following, per JSON file; table name 'pme_power8'
+ is derived from JSON file name, 'power8.json').
+
+ struct pmu_event pme_power8[] = {
+
+ ...
+
+ {
+ .name = "pm_1plus_ppc_cmpl",
+ .event = "event=0x100f2",
+ .desc = "1 or more ppc insts finished,",
+ },
+
+ ...
+ }
+
+ - A 'mapping table' that maps each CPU of the architecture, to its
+ 'PMU events table'
+
+ struct pmu_events_map pmu_events_map[] = {
+ {
+ .cpuid = "004b0000",
+ .version = "1",
+ .type = "core",
+ .table = pme_power8
+ },
+ {
+ ...
+ },
+
+ };
+
+After the 'pmu-events.c' is generated, it is compiled and the resulting
+'pmu-events.o' is added to 'libperf.a' which is then used to build perf.
+
+NOTES:
+ 1. Several CPUs can support same set of events and hence use a common
+ JSON file. Hence several entries in the pmu_events_map[] could map
+ to a single 'PMU events table'.
+
+ 2. The 'pmu-events.h' has an extern declaration for the mapping table
+ and the generated 'pmu-events.c' defines this table.
+
+ 3. _All_ known CPU tables for architecture are included in the perf
+ binary.
+
+At run time, perf determines the actual CPU it is running on, finds the
+matching events table and builds aliases for those events. This allows
+users to specify events by their name:
+
+ $ perf stat -e pm_1plus_ppc_cmpl sleep 1
+
+where 'pm_1plus_ppc_cmpl' is a Power8 PMU event.
+
+In case of errors when processing files in the tools/perf/pmu-events/arch
+directory, 'jevents' tries to create an empty mapping file to allow perf
+build to succeed even if the PMU event aliases cannot be used.
+
+However some errors in processing may cause the perf build to fail.
+
+The mapfile format is expected to be:
+
+ Header line
+ CPUID,Version,JSON/file/path/name,Type
+
+where:
+
+ Lines in which the first character is either '\n' or '#' are ignored.
+
+ Header line
+ is the first line in the file and is ignored. Even if
+ first line is empty or is a comment, subsequent non-comment/
+ blank lines are expected to adhere to the format of the second
+ line above.
+
+ Comma:
+ is the required field delimiter (i.e other fields cannot
+ have commas within them)
+
+ CPUID:
+ represents is an arch-specific CPUID for the set of CPUs
+ that use the PMU events specified in JSON/file/path/name.
+ (Multiple CPU ids can point to the same JSON/file/path/name)
+
+ Version:
+ is the Version of the mapfile.
+
+ JSON/file/path/name:
+ is the pathname for the JSON file, relative to the directory
+ containing the mapfile.csv
+
+ Type:
+ indicates whether the events or "core" or "uncore" events.
--
1.7.9.5
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
