linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: tip-bot for Sukadev Bhattiprolu <tipbot@zytor.com>
To: linux-tip-commits@vger.kernel.org
Cc: tglx@linutronix.de, linux-kernel@vger.kernel.org,
	mingo@kernel.org, acme@redhat.com, maddy@linux.vnet.ibm.com,
	sukadev@linux.vnet.ibm.com, peterz@infradead.org, hpa@zytor.com,
	jolsa@redhat.com
Subject: [tip:perf/urgent] perf tools: Add README for info on parsing JSON/map files
Date: Tue, 4 Oct 2016 01:17:27 -0700	[thread overview]
Message-ID: <tip-06d839b4f712065d76cba92e7e10e9d771771c5a@git.kernel.org> (raw)
In-Reply-To: <1473978296-20712-16-git-send-email-sukadev@linux.vnet.ibm.com>

Commit-ID:  06d839b4f712065d76cba92e7e10e9d771771c5a
Gitweb:     http://git.kernel.org/tip/06d839b4f712065d76cba92e7e10e9d771771c5a
Author:     Sukadev Bhattiprolu <sukadev@linux.vnet.ibm.com>
AuthorDate: Thu, 15 Sep 2016 15:24:52 -0700
Committer:  Arnaldo Carvalho de Melo <acme@redhat.com>
CommitDate: Mon, 3 Oct 2016 21:37:48 -0300

perf tools: Add README for info on parsing JSON/map files

Signed-off-by: Sukadev Bhattiprolu <sukadev@linux.vnet.ibm.com>
Acked-by: Ingo Molnar <mingo@kernel.org>
Acked-by: Jiri Olsa <jolsa@redhat.com>
Cc: Madhavan Srinivasan <maddy@linux.vnet.ibm.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: linuxppc-dev@lists.ozlabs.org
Link: http://lkml.kernel.org/r/1473978296-20712-16-git-send-email-sukadev@linux.vnet.ibm.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
---
 tools/perf/pmu-events/README | 147 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)

diff --git a/tools/perf/pmu-events/README b/tools/perf/pmu-events/README
new file mode 100644
index 0000000..1408ade
--- /dev/null
+++ b/tools/perf/pmu-events/README
@@ -0,0 +1,147 @@
+
+The contents of this directory allow 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/foo.
+
+	- Regular files with '.json' extension in the name are assumed to be
+	  JSON files, each of which describes a set of PMU events.
+
+	- Regular files with basename starting with 'mapfile.csv' are assumed
+	  to be a CSV file that maps a specific CPU to its set of PMU events.
+	  (see below for mapfile format)
+
+	- Directories are traversed, but all other files are ignored.
+
+The PMU events supported by a CPU model are expected to grouped into topics
+such as Pipelining, Cache, Memory, Floating-point etc. All events for a topic
+should be placed in a separate JSON file - where the file name identifies
+the topic. Eg: "Floating-point.json".
+
+All the topic JSON files for a CPU model/family should be in a separate
+sub directory. Thus for the Silvermont X86 CPU:
+
+	$ ls tools/perf/pmu-events/arch/x86/Silvermont_core
+	Cache.json 	Memory.json 	Virtual-Memory.json
+	Frontend.json 	Pipeline.json
+
+Using the JSON files and the mapfile, 'jevents' generates the 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 the 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.
+
+Mapfile format
+===============
+
+The mapfile enables multiple CPU models to share a single set of PMU events.
+It is required even if such mapping is 1:1.
+
+The mapfile.csv format is expected to be:
+
+	Header line
+	CPUID,Version,Dir/path/name,Type
+
+where:
+
+	Comma:
+		is the required field delimiter (i.e other fields cannot
+		have commas within them).
+
+	Comments:
+		Lines in which the first character is either '\n' or '#'
+		are ignored.
+
+	Header line
+		The header line is the first line in the file, which is
+		always _IGNORED_. It can empty.
+
+	CPUID:
+		CPUID is an arch-specific char string, that can be used
+		to identify CPU (and associate it with a set of PMU events
+		it supports). Multiple CPUIDS can point to the same
+		File/path/name.json.
+
+		Example:
+			CPUID == 'GenuineIntel-6-2E' (on x86).
+			CPUID == '004b0100' (PVR value in Powerpc)
+	Version:
+		is the Version of the mapfile.
+
+	Dir/path/name:
+		is the pathname to the directory containing the CPU's JSON
+		files, relative to the directory containing the mapfile.csv
+
+	Type:
+		indicates whether the events or "core" or "uncore" events.
+
+
+	Eg:
+
+	$ grep Silvermont tools/perf/pmu-events/arch/x86/mapfile.csv
+	GenuineIntel-6-37,V13,Silvermont_core,core
+	GenuineIntel-6-4D,V13,Silvermont_core,core
+	GenuineIntel-6-4C,V13,Silvermont_core,core
+
+	i.e the three CPU models use the JSON files (i.e PMU events) listed
+	in the directory 'tools/perf/pmu-events/arch/x86/Silvermont_core'.

  parent reply	other threads:[~2016-10-04  8:18 UTC|newest]

Thread overview: 70+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-09-15 22:24 [PATCH v21 00/20] perf, tools: Add support for PMU events in JSON format Sukadev Bhattiprolu
2016-09-15 22:24 ` [PATCH v21 01/19] perf, tools: Add jsmn `jasmine' JSON parser Sukadev Bhattiprolu
2016-10-04  8:11   ` [tip:perf/urgent] perf " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 02/19] perf, tools, jevents: Program to convert JSON file to C style file Sukadev Bhattiprolu
2016-09-15 22:24 ` [PATCH v21 03/19] perf, tools: Use pmu_events table to create aliases Sukadev Bhattiprolu
2016-09-27 13:16   ` Arnaldo Carvalho de Melo
2016-10-04  8:12   ` [tip:perf/urgent] perf pmu: " tip-bot for Sukadev Bhattiprolu
2016-09-15 22:24 ` [PATCH v21 04/19] perf, tools: Support CPU ID matching for Powerpc Sukadev Bhattiprolu
2016-10-04  8:13   ` [tip:perf/urgent] perf powerpc: " tip-bot for Sukadev Bhattiprolu
2016-09-15 22:24 ` [PATCH v21 05/19] perf, tools: Support CPU id matching for x86 v2 Sukadev Bhattiprolu
2016-10-04  8:13   ` [tip:perf/urgent] perf " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 06/19] perf, tools: Support alias descriptions Sukadev Bhattiprolu
2016-09-27 17:41   ` Arnaldo Carvalho de Melo
2016-09-27 18:11     ` Sukadev Bhattiprolu
2016-09-28 13:57       ` Arnaldo Carvalho de Melo
2016-09-28 18:29         ` Sukadev Bhattiprolu
2016-09-28 19:08           ` Arnaldo Carvalho de Melo
2016-10-03 20:52           ` Arnaldo Carvalho de Melo
2016-10-04  8:14   ` [tip:perf/urgent] perf pmu: " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 07/19] perf, tools: Query terminal width and use in perf list Sukadev Bhattiprolu
2016-10-04  8:14   ` [tip:perf/urgent] perf " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 08/19] perf, tools: Add a --no-desc flag to " Sukadev Bhattiprolu
2016-10-04  8:15   ` [tip:perf/urgent] perf list: Add a --no-desc flag tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 09/19] perf, tools: Add override support for event list CPUID Sukadev Bhattiprolu
2016-10-04  8:15   ` [tip:perf/urgent] perf pmu: " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 10/19] perf, tools, jevents: Add support for long descriptions Sukadev Bhattiprolu
2016-10-04  8:16   ` [tip:perf/urgent] perf " tip-bot for Sukadev Bhattiprolu
2016-09-15 22:24 ` [PATCH v21 11/19] perf, tools: Add alias " Sukadev Bhattiprolu
2016-10-04  0:20   ` Arnaldo Carvalho de Melo
2016-09-15 22:24 ` [PATCH v21 12/19] perf, tools: Support long descriptions with perf list Sukadev Bhattiprolu
2016-10-04  0:26   ` Arnaldo Carvalho de Melo
2016-10-04  8:16   ` [tip:perf/urgent] perf list: Support long jevents descriptions tip-bot for Sukadev Bhattiprolu
2016-09-15 22:24 ` [PATCH v21 13/19] perf, tools: Add support for event list topics Sukadev Bhattiprolu
2016-10-04  8:16   ` [tip:perf/urgent] perf list jevents: " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 14/19] perf, tools, jevents: Handle header line in mapfile Sukadev Bhattiprolu
2016-10-04  0:36   ` Arnaldo Carvalho de Melo
2016-10-04  8:13   ` [tip:perf/urgent] perf " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 15/19] perf, tools: Add README for info on parsing JSON/map files Sukadev Bhattiprolu
2016-10-04  0:38   ` Arnaldo Carvalho de Melo
2016-10-04  8:17   ` tip-bot for Sukadev Bhattiprolu [this message]
2016-09-15 22:24 ` [PATCH v21 16/19] perf, tools: Make alias matching case-insensitive Sukadev Bhattiprolu
2016-10-04  0:47   ` Arnaldo Carvalho de Melo
2016-10-04  0:54     ` Arnaldo Carvalho de Melo
2016-10-04  8:19       ` Jiri Olsa
2016-10-04  8:19     ` Jiri Olsa
2016-10-04  8:18   ` [tip:perf/urgent] perf " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 17/19] perf, tools, pmu-events: Fix fixed counters on Intel Sukadev Bhattiprolu
2016-10-04  8:18   ` [tip:perf/urgent] perf " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 18/19] perf, tools, pmu-events: Add Skylake frontend MSR support Sukadev Bhattiprolu
2016-10-04  8:19   ` [tip:perf/urgent] perf " tip-bot for Andi Kleen
2016-09-15 22:24 ` [PATCH v21 19/19] perf, tools: Allow period= in perf stat CPU event descriptions Sukadev Bhattiprolu
2016-10-04  8:17   ` [tip:perf/urgent] perf " tip-bot for Sukadev Bhattiprolu
2016-09-19 16:58 ` [PATCH v21 00/20] perf, tools: Add support for PMU events in JSON format Sukadev Bhattiprolu
2016-09-19 21:20 ` Arnaldo Carvalho de Melo
2016-09-19 23:31   ` Arnaldo Carvalho de Melo
2016-09-19 23:37     ` Arnaldo Carvalho de Melo
2016-09-20  0:02       ` Arnaldo Carvalho de Melo
2016-09-20  0:28         ` Arnaldo Carvalho de Melo
2016-09-22 14:56           ` Arnaldo Carvalho de Melo
2016-09-22 15:00           ` Jiri Olsa
2016-09-22 16:27             ` Jiri Olsa
2016-09-26  8:35               ` Jiri Olsa
2016-09-26 15:03                 ` Arnaldo Carvalho de Melo
2016-09-26 16:59                   ` Andi Kleen
2016-09-27 14:18                     ` Jiri Olsa
2016-09-29 22:19                       ` Arnaldo Carvalho de Melo
2016-09-30  9:10                         ` Jiri Olsa
2016-10-04  8:10                       ` [tip:perf/urgent] tools build: Add support for host programs format tip-bot for Jiri Olsa
2016-10-04  8:11                       ` [tip:perf/urgent] tools build: Make fixdep a hostprog tip-bot for Jiri Olsa
2016-10-04  8:12                       ` [tip:perf/urgent] perf jevents: Program to convert JSON file tip-bot for Andi Kleen

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=tip-06d839b4f712065d76cba92e7e10e9d771771c5a@git.kernel.org \
    --to=tipbot@zytor.com \
    --cc=acme@redhat.com \
    --cc=hpa@zytor.com \
    --cc=jolsa@redhat.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-tip-commits@vger.kernel.org \
    --cc=maddy@linux.vnet.ibm.com \
    --cc=mingo@kernel.org \
    --cc=peterz@infradead.org \
    --cc=sukadev@linux.vnet.ibm.com \
    --cc=tglx@linutronix.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).